How to use IAM trusted profiles with your VPC virtual server instances.

Virtual server instances for virtual private cloud (VPC) can now be linked to the IAM trusted profile identity type, similar to federated users and Kubernetes service accounts. Any virtual server instance that has the instance metadata service enabled can get an IAM token for a trusted profile and apply its permissions. This way, applications running inside virtual server instances in IBM Cloud can access IAM-enabled IBM Cloud services and classic infrastructure resources.

Advantages of using IAM trusted profiles

Before the ability to get IAM tokens for trusted profiles, workloads running in virtual server instances for VPC typically leveraged service IDs and their related API keys to access IBM Cloud services. This meant that the user was responsible for loading API keys into the virtual server instance before any IBM Cloud services could be called. The user was then responsible for the protection and management of API keys as “secrets” throughout the lifecycle of the virtual server instance.

IAM trusted profiles offer the following advantages:

• No IAM credential deployment: Prior to trusted profiles, to get an IAM token for a service ID, the virtual server instance needed access to an API key for that service ID. This API key is typically loaded into a secrets vault and read into the virtual server instance, which requires a sophisticated and security-sensitive deployment process.
• Eliminates the secret-zero problem: A credentials deployment process for virtual servers typically suffers from the classic “secret-zero” problem because the credentials to the secrets vault must be deployed into the instance to enable API key retrieval. IAM trusted profiles solve the secret-zero problem by eliminating the requirement for users to manage secrets vault credentials in virtual server instances, which reduces security risks.
• No credential rotation: Without the need to deploy a credential, there is also no need to rotate a credential.
• Auditing: Each retrieval of an instance identity access token and IAM token from a virtual server instance for VPC is audited in IBM Cloud Activity Tracker. This gives you a more fine-grained insight into the IAM token retrieval than if you were to use a service ID with an API key. The fields Initiator.id and Initiatior.name hold the details of the profile that is applied. The authnID field holds the cloud resource name (CRN) of the virtual server instance that applied the trusted profile. See Monitoring login sessions for trusted profiles and Instance Metadata service events for further information.
• Least privilege: Mapping a virtual server instance for VPC to an IAM trusted profile gives you the ability to assign the exact level of access to IAM-enabled IBM Cloud services that the virtual server instance requires. If another instance requires another level of access, this can be achieved by using a different IAM trusted profile configured with the appropriate level of access.

How to enable your virtual server instance for VPC to use IAM trusted profiles

The following IBM Cloud CLI example walks you through using a trusted profile with a VPC virtual server instance. A trusted profile is granted access rights to call other service API endpoints from the instance and is linked to the instance. Note that the access policies assigned to a trusted profile can easily be modified to call any IAM-enabled service APIs based on service roles. A few common example services include IBM Cloud Object Storage, IBM Key Protect for IBM Cloud and IBM Cloud Databases. Performing such API calls from an instance was possible in the past, but the key difference is that the trusted profile enables API calls to other cloud service APIs without requiring an API key.

In the first set of steps, we’ll create a trusted profile, define access for the trusted profile, and link the trusted profile to a new VPC virtual server instance. The access policy in this example allows the instance to acquire an IAM token with access rights to call VPC APIs requiring an operator role. We’ll create a new Linux virtual server instance for VPC with the instance metadata service enabled. The trusted profile is automatically linked to the instance during provisioning of the virtual server instance.

Step 1: Create a trusted profile

First, create a trusted profile with no access policy by running the following CLI command. For more information, see the CLI reference: Managing IAM access, API keys, trusted profiles, service IDs, and access groups, ibmcloud iam trusted-profile-create:

$ ibmcloud iam trusted-profile-create my-trusted-profile --description "My trusted profile"

Step 2: Add an access policy to the trusted profile

Next, create an access policy in the trusted profile that you created in Step 1. The access policy grants operator access to the trusted profile for the VPC infrastructure service. Later, this access will be used to call a VPC API from within a virtual server instance to which the trusted profile is linked. Additional access policies can be added later if the trusted profile requires additional access. For now, a single access policy is added. For more information, see ibmcloud iam trusted-profile-policy-create: 

$ ibmcloud iam trusted-profile-policy-create my-trusted-profile --roles Operator --service-name is

Step 3: Create a virtual server instance for VPC and link it to the trusted profile

Now create a Linux virtual server instance that adopts the compute identity from the trusted profile. You must create the instance with the metadata service enabled so that later in this example, you can call instance identity APIs from within the instance to generate IAM tokens.  In the instance-create command, a linked trusted profile is specified, which causes the trusted profile that was created in the previous steps to be linked during creation of the virtual server instance. The metadata service and default trusted profile parameters are the two integral settings for enabling the use of trusted profiles with instances.

There are three CLI commands required to complete this step. First, you create the instance with an SSH key (my-key) that will allow access to the instance command line with a SSH client. Second, you reserve a floating IP address. Third, you add the reserved floating IP address to the instance. The floating IP is used in this example to access the instance via the public network.  For more information, see IBM Cloud instance create CLI command:

1. Create an instance:

   $ ibmcloud is instance-create my-instance my-vpc us-south-3 bx2-2x8 my-subnet --image r006-b9ebf1d8-a674-42e8-898e-0fcb08994f66 --primary-network-interface '{"name": "primary-nic", "subnet": {"name":"my-sn3"}}' --keys my-key --metadata-service true --default-trusted-profile my-trusted-profile

2. Reserve a floating IP address:

   $ ibmcloud is floating-ip-reserve my-fip1 --zone us-south-3

   Note: Record the “Address” returned on this command for use in Step 4.

3. Add the reserved floating IP address to the instance:

   $ ibmcloud is instance-network-interface-floating-ip-add my-instance primary-nic my-fip1

How to use trusted profiles from your virtual server instance for VPC

Step 4: Sign onto the instance

Step 5 through Step 7 are done from your virtual server instance command prompt. First, use a secure shell (SSH) client on your desktop to sign on to the virtual server instance that was just created in Step 3. Using a SSH client from your desktop terminal, a sample command for accessing the example instance is below. Replace <instance-floating-ip-address> with the address that was recorded in Step 3:

$ ssh root@<instance-floating-ip-address>

Step 5: Acquire an instance identity access token

From the instance command prompt, use the curl command line tool to call the instance identity API. The instance identity service is accessible from within the instance on the metadata service’s well-known link local address of 169.254.169.254. Since the VPC instance identity APIs return JSON output, the jq tool will be used to parse the JSON structure returned in the API payload. Depending on the operating system of your virtual server instance, you might need to install the curl and jq tools.

First, use the instance identity API to acquire an instance identity token and store it in a variable to be used in the next step. The instance identity access token, by default, expires in 300 seconds. In this example, the token expiry time was modified to 600 seconds. Once the token expires, simply call the API again to generate a new token.

The instance identity access token may be used multiple times. The token is also multi-use, meaning the same token can be used to both acquire an IAM token and to get instance metadata.  For more information, see Create an instance identity access token: 

$ instance_identity_token=`curl -X PUT "http://169.254.169.254/instance_identity/v1/token?version=2022-03-31" -H "Metadata-Flavor: ibm" -d '{ "expires_in": 600}' | jq -r '(.access_token)'`

Step 6: Acquire an IAM token

Use the instance identity access token obtained in the previous step on another instance identity API call to generate an IAM token. Again, use the jq parser parse the token into a variable for use in Step 7. IAM tokens are valid for 60 minutes. IAM tokens can be used multiple times, and any application using IAM tokens can be optimized by caching the token and refreshing the token only as necessary. For more information, see Create an IAM token using an instance identity token: 

$ iam_token=`curl -X POST "http://169.254.169.254/instance_identity/v1/iam_token?version=2022-03-31" -H "Authorization: Bearer ${instance_identity_token}" | jq -r '(.access_token)'`

Step 7: Use the IAM token to call a VPC API

Now that you’ve generated an IAM token, you can use that token to call other cloud service APIs. In this example, the trusted profile access policy granted the operator role on the VPC infrastructure service. Therefore, you can use the IAM token to call VPC APIs that require an operator role. The example curl command below calls the VPC us-south regional API to list all virtual server instances in the account. For more information, see the VPC list all instances API:

$ curl -X GET "https://us-south.iaas.cloud.ibm.com/v1/instances?version=2022-03-31&generation=2" -H "Authorization: Bearer ${iam_token}"

Note that in this example, no API keys were required to call the VPC API, which is a significant change introduced by trusted profiles. If an application running in the instance is required to call other cloud services from the virtual server instance, you can simply add additional access policies to the trusted profile. Any service that uses IBM Cloud IAM for access control can be called using the process described in this example.

Ready to get started?

Begin exploring the trusted profiles page in the IBM Cloud console and the related documentation. In no time, you’ll be ready to create a trusted profile and start adding access policies that can be used to call other services from your VPC virtual server instances. 

You can choose from the following options to start creating trusted profiles: 

• In the IBM Cloud console.
• By using REST API calls. For more information, see IAM Identity Services: Create a trusted profile. 
• By using the command-line interface (CLI). Version 2.0.3 and later of the IBM Cloud CLI contains a set of new commands for creating and maintaining trusted profiles.

Check out the following VPC documentation to help you with using trusted profiles in your instances:  

• Using a trusted profile to call IAM-enabled services
• Virtual Private Cloud Instance Metadata API
• VPC CLI Reference