About trusted profiles for compute resource identities

Trusted profiles for compute resource identities allow for fine-grained authorization for all applications that run in a virtual server instance. They eliminate the need for creating service IDs or managing API key lifecycles for applications. Instead, compute resources become identities as part of a trusted profile, and trust is established through conditions based on resource attributes.

You can assign an IAM identity directly to the instance and acquire an instance identity access token. So the applications that are running on the virtual server instance can securely access other IBM Cloud services with the identity access token without storing API keys.

The compute resource identity service creates the trusted profile, then you can assign access rights to the trusted profile to enable the instance to call IAM-enabled services, such as IBM Cloud Object Storage and IBM® Key Protect.

You link a trusted profile when you provision an instance. Trusted profiles define authorization for all applications that are running on the instance.

The trusted profile that you specify when you provision the instance becomes the default trusted profile.

The instance inherits the access rights that are defined in the default trusted profile. VPC uses that trusted profile for any instance identity request to generate an IAM token from an instance identity access token, where the token generation request does not specify a trusted profile.

Before you begin

Using trusted profiles for compute resource identities

The general procedure and context for using trusted profiles are described in the following table. You can streamline the process by setting up dynamic rules in the first step to link the trusted profile automatically to new instances. The IAM token is obtained by exchanging the instance identity access token that was acquired through the metadata service with an IAM token.

For more information, see the IAM documentation on setting up trusted profiles.

End-to-end procedure for using a trusted profile to call IAM-enabled services

Default trusted profiles cannot be changed on existing instances. A default trusted profile can be specified only while you provision an instance.

1. Retrieve the information about the trusted profile that you want to use for the new instance.

2. Create the instance and specify a default trusted profile while you provision the instance. With the VPC API, set the auto_link property to true to automatically link the trusted profile to the instance. Specify the trusted profile ID or the CRN of the trusted profile. See the following example.

   curl -X POST "$vpc_api_endpoint/v1/instances?version=2025-04-22&generation=2" -H "Authorization: Bearer $iam_token" 
   -d '{
        "default_trusted_profile": {
           "auto_link": true,
           "target": {
              "crn": "crn:v1:bluemix:public:iam-identity::a/123456::profile:Profile-9fd84264-7de4-4627-94c4-8ecde51d5ac5
              }
           },
          .
          .
          .
        }'
   

   For more information, see the API VPC reference: Create an instance.

3. Obtain an instance identity access token and create an environment variable for it:

   1. Log in to IBM Cloud CLI.

   2. Go to an existing instance. Use ibmcloud is instances to locate a running instance in which to enable the metadata service. The instance must be associated with a VPC. The instance can be running a stock or a custom image. The metadata service is supported on all stock and custom images, and CPU profiles.

   3. Make an SSH connection to the virtual server instance to log in.

   4. From the virtual server instance, make an API request to the metadata token service to retrieve an instance identity access token. Specify how long the token is valid, for example 3600 seconds (1 hour). In this example, the command is run through the jq parser to format the JSON response. You can choose another parser if you prefer.

      curl -X PUT "$vpc_metadata_api_endpoint/instance_identity/v1/token?version=2025-04-22" -H "Metadata-Flavor: ibm" -d '{"expires_in": 3600}'| jq -r '(.instance_identity_token)'
      

      The response is the access token payload. For more information, see the Metadata API reference: Create an instance identity access token.

   5. You can now make a request to the metadata service. The first call is to get the initialization information:

      curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/initialization?version=2025-04-22" -H "Authorization: Bearer $instance_identity_token"
      

      Information in the response shows the SSH key and user data that were specified when the virtual server was provisioned. If you configured passwords, that information is also returned. For more information, see the Metadata API reference: Retrieve initialization information.

4. Generate an IAM token from the instance identity access token that was acquired from the metadata service.

5. Use the IAM token to make calls to IAM-enabled services.

Next steps

Make calls to the instance metadata service for instances, SSH keys, and placement group data. See Using the instance metadata service.