Creating IAM credentials

You can use IBM Cloud® Secrets Manager to dynamically generate IAM credentials for accessing an IBM Cloud resource that requires IAM authentication.

IAM credentials are dynamic secretsA unique value, such as a password or an API key, that is created dynamically and leased to an application that requires access to a protected resource. After a dynamic secret reaches the end of its lease, access to the protected resource is revoked and the secret is deleted automatically. that you can use to access an IBM Cloud resource. A set of IAM credentials consists of a service ID and an API key that is generated each time that the protected resource is read or accessed. You can define a time-to-live (TTL) or a lease duration for your IAM credential at its creation so that you shorten the amount of time that the secret exists.

To learn more about the types of secrets that you can manage in Secrets Manager, see What is a secret?

Before you begin

Before you get started, be sure that you have the required level of access. To create or add secrets, you need the Writer service role or higher.

IAM credentials require an extra configuration step before you can start to create or manage them in the service. For more information, see Configuring the IAM credentials engine.

When changing an IAM credential secret's TTL, it will be applied only on the next secret version rotation.

An account administrator (or any entity with the required level of access) can externally alter IAM Credentials that are created and managed by Secrets Manager. If such a service ID or API key is deleted outside of Secrets Manager, the service might behave unexpectedly. For example, you might be unable to create, or rotate credentials.

Creating IAM credentials in the UI

To create IAM credentials by using the Secrets Manager UI, complete the following steps.

In the console, click the Menu icon > Resource List.
From the list of services, select your instance of Secrets Manager.
In the Secrets table, click Add.
From the list of secret types, click the IAM credentials tile.
Click Next.
Add a name and description to easily identify your secret.
Select the secret groupThe environment and constraints that contained secrets in an instance must adhere to. A user can be associated with a secret group to enable access and collaboration. that you want to assign to the secret.

Don't have a secret group? In the Secret group field, you can click Create to provide a name and a description for a new group. Your secret is added to the new group automatically. For more information about secret groups, check out Organizing your secrets.
Optional: Add labels to help you to search for similar secrets in your instance.
Optional: Add metadata to your secret or to a specific version of your secret.
1. Upload a file or enter the metadata and the version metadata in JSON format.
Click Next.
Set a lease duration or time-to-live (TTL) for the secret.

By setting a lease duration for your IAM credential, you determine how long its associated API key remains valid. After the IAM credential reaches the end of its lease, it is revoked automatically.

Minimum duration is 1 minute. Maximum is 90 days.
Optional: Determine whether IAM credentials can be reused for your secret.
Optional: Enable automatic rotation of your secret. Secrets can be automatically rotated only if the reuse IAM credentials option is selected.
Click Next.
Determine the scope of access to assign for your IAM credential.
Click Next.
Review the details of your secret.
Click Add.

Reusing the same API key until the lease expires

IAM credentials consist of a service ID and an API key. By default, the service ID and API key are single-use, ephemeral values that are generated and deleted each time that an IAM credentials secret is read or accessed.

If you'd like to continue to use those credentials through the end of the lease of your secret, you can set Reuse IAM credentials until lease expires to On. When you enable this option, your secret retains its current service ID, and API key values and reuses them on each read while the secret remains valid. After the secret reaches the end of its lease, the credentials are revoked automatically.

If the reuse IAM credentials option is set to Off, manual rotation for the secret isn't supported. For more information, see Manually rotating secrets.

Using an existing service ID in your account

You might already have a service ID in your account that you want to use to dynamically generate an API key. In this scenario, you can choose to create an IAM credentials secret by bringing your own service ID. Or, if you prefer to generate both a service ID and an API key, you can assign access by choosing an access group.

In the Assign access step of the Create IAM credentials wizard, choose a scope of access for your credentials.

To use an existing service ID, select an ID from the list.

Choose this option when you need Secrets Manager to generate and manage only an API key for your IAM credentials secret, and not the service ID itself. The API key inherits the access policy of the service ID that you select from your account. Only the service IDs that you have access to are displayed.
To generate both a new service ID and API key for the secret, select an access group.

By selecting an access group from your IBM Cloud account, you determine the scope of access to assign to the service ID and the API key. The API key is dynamically generated and associated with your new IAM credential. This step ensures that your IAM credentials are scoped with the preferred level of permissions in your IBM Cloud account. You can assign up to 10 access groups.

If you used an existing service ID, the API key that was generated by Secrets Manager is automatically locked. If you selected an access group, both the new service ID and API key that Secrets Manager created for the secret are automatically locked. Each time you that retrieve an IAM credentials secret by using the API, the API key and the service ID that Secrets Manager generates are locked, even if you manually unlock them before retrieving the secret.

Creating IAM credentials from the CLI

To create a dynamic service ID and API key by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-create command. For example, the following command creates an IAM secret with a lease duration of 12 hours.

ibmcloud secrets-manager secret-create  \   
    --secret-prototype='{"name": "example-iam-credentials-secret","description": "Description of my IAM credentials secret","secret_type": "iam_credentials","secret_group_id": "<secret_group_id>","labels": ["dev","us-south"],"ttl": "30m","access_groups": ["<access_group_id>"],"reuse_api_key": false, "custom_metadata": {"metadata_custom_key": "metadata_custom_value"},"version_custom_metadata": { "custom_version_key": "custom_version_value"}}'

The command outputs the ID value of the secret, along with other metadata. For more information about the command options, see ibmcloud secrets-manager secret-create.

Reusing the same API key until the lease expires

If you'd like to continue to use those credentials through the end of the lease of your secret, you can use the reuse_api_key field. If set to true, your secret retains its current service ID and API key values and reuses them on each read while the secret remains valid. For example, the following example command creates IAM credentials that can be reused until they expire.

ibmcloud secrets-manager secret-create  \   
    --secret-prototype='{"name": "example-iam-credentials-secret","description": "Description of my IAM credentials secret","secret_type": "iam_credentials","secret_group_id": "<secret_group_id>","labels": ["dev","us-south"],"ttl": "30m","access_groups": ["<access_group_id>"],"reuse_api_key": true, "custom_metadata": {"metadata_custom_key": "metadata_custom_value"},"version_custom_metadata": { "custom_version_key": "custom_version_value"}}'

The command outputs the ID value of the secret, along with other metadata. After the secret reaches the end of its lease, the credentials are revoked automatically. For more information about the command options, see ibmcloud secrets-manager secret-create.

If reuse_api_key is false for IAM credentials, manual rotation for the secret isn't supported. For more information, see Manually rotating secrets.

Using an existing service ID in your account

You might already have a service ID in your account that you want to use to dynamically generate an API key. In this scenario, you can choose to create an IAM credentials secret by bringing your own service ID. For example, the following command creates an IAM credential by using the service_id field.

You can find the ID value of a service ID in the IAM section of the console. Go to Manage > Access (IAM) > Service IDs > name. Click Details to view the ID.

ibmcloud secrets-manager secret-create  \   
    --secret-prototype='{"name": "example-iam-credentials-secret","description": "Description of my IAM credentials secret","secret_type": "iam_credentials","secret_group_id": "<secret_group_id>","labels": ["dev","us-south"],"ttl": "30m","service_id":"<service_id>","reuse_api_key": false, "custom_metadata": {"metadata_custom_key": "metadata_custom_value"},"version_custom_metadata": { "custom_version_key": "custom_version_value"}}'

The command outputs the ID value of the secret, along with other metadata. For more information about the command options, see ibmcloud secrets-manager secret-create.

Creating IAM credentials with the API

You can create IAM credentials programmatically by calling the Secrets Manager API.

The following example shows a query that you can use to create a dynamic service ID and API key. When you call the API, replace the ID variables and IAM token with the values that are specific to your Secrets Manager instance.

You can store metadata that are relevant to the needs of your organization with the custom_metadata and version_custom_metadata request parameters. Values of the version_custom_metadata are returned only for the versions of a secret. The custom metadata of your secret is stored as all other metadata, for up to 50 versions, and you must not include confidential data.

curl -X POST  
    -H "Authorization: Bearer {iam_token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ 
      {
        "name": "example-iam-credentials-secret",
        "description": "Description of my IAM Credentials secret",
        "secret_type": "iam_credentials",
        "secret_group_id": "bfc0a4a9-3d58-4fda-945b-76756af516aa",
        "labels": [
          "dev",
          "us-south"
        ],
        "ttl": "30m",
        "access_groups": [
          "AccessGroupId-45884031-54be-4dd7-86ff-112511e92699",
          "AccessGroupId-8c0ed733-dfee-4a94-992b-e2247b86e2a2"
        ],
        "reuse_api_key": false,
        "custom_metadata": {
          "metadata_custom_key": "metadata_custom_value"
        },
        "version_custom_metadata": {
          "custom_version_key": "custom_version_value"
        }
      }' \ "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets"

A successful response returns the ID value of the secret, along with other metadata. For more information about the required and optional request parameters, check out the API reference.

Reusing the same API key until the lease expires

If you'd like to use those credentials through the end of the lease of your secret, you can use the reuse_api_key field. If set to true, your secret retains its current service ID and API key values and reuses them on each read while the secret remains valid. For example, the following example command creates IAM credentials that can be reused until they expire.

curl -X POST  
    -H "Authorization: Bearer {iam_token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ 
      {
        "name": "example-iam-credentials-secret",
        "description": "Description of my IAM Credentials secret",
        "secret_type": "iam_credentials",
        "secret_group_id": "bfc0a4a9-3d58-4fda-945b-76756af516aa",
        "labels": [
          "dev",
          "us-south"
        ],
        "ttl": "30m",
        "access_groups": [
          "AccessGroupId-45884031-54be-4dd7-86ff-112511e92699",
          "AccessGroupId-8c0ed733-dfee-4a94-992b-e2247b86e2a2"
        ],
        "reuse_api_key": true,
        "custom_metadata": {
          "metadata_custom_key": "metadata_custom_value"
        },
        "version_custom_metadata": {
          "custom_version_key": "custom_version_value"
        }
      }' \ 
    "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets"

A successful request returns the ID value of the secret, along with other metadata. After the secret reaches the end of its lease, the credentials are revoked automatically. For more information, check out the API reference.

If reuse_api_key is false for IAM credentials, manual rotation for the secret isn't supported. For more information, see Manually rotating secrets.

Using an existing service ID in your account

You might already have a service ID in your account that you want to use to dynamically generate an API key. In this scenario, you can choose to create an IAM credentials secret by bringing your own service ID. For example, the following command creates an IAM credential by using the service_id field.

You can find the ID value of a service ID in the IAM section of the console. Go to Manage > Access (IAM) > Service IDs > name. Click Details to view the ID.

curl -X POST  
    -H "Authorization: Bearer {iam_token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ 
          "name": "example-iam-credentials-secret",
          "description": "Description of my IAM Credentials secret",
          "service_id":"iam-ServiceId-c0c7cfa4-b24e-4917-ad74-278f2fee5ba0",
          "secret_type": "iam_credentials",
          "secret_group_id": "bfc0a4a9-3d58-4fda-945b-76756af516aa",
          "labels": [
            "dev",
            "us-south"
          ],
          "ttl": "30m",
          "service_id": "ServiceId-c0c7cfa4-b24e-4917-ad74-278f2fee5ba0,
          "reuse_api_key": false,
          "custom_metadata": {
            "metadata_custom_key": "metadata_custom_value"
          },
          "version_custom_metadata": {
            "custom_version_key": "custom_version_value"
          }
        }' \
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets"

A successful request returns the ID value of the secret, along with other metadata. For more information, check out the API reference.

Creating IAM credentials with Terraform

You can create IAM credentials programmatically by using Terraform for Secrets Manager.

You must add a depends_on Terraform meta-argument and refer it to your IAM configuration resource. The depends_on meta-argument instructs Terraform to complete all actions on the IAM configuration before you perform actions on the IAM credentials secrets.

The following example shows a configuration that you can use to create IAM credentials.

    resource "ibm_sm_iam_credentials_secret" "test_iam_credentials_secret" {
        instance_id = local.instance_id
        region = local.region
        service_id = "ServiceId-f4b2deac-fbb5-4bf7-85de-88426701db97"
        ttl = "1800"
        name = "test-iam-credentials-secret"
        reuse_api_key = true
        secret_group_id = ibm_sm_secret_group.sm_secret_group_test.secret_group_id
        depends_on = [
            ibm_sm_iam_credentials_configuration.iam_credentials_configuration
        ]
    }

Deleting IAM credentials

If you have a service ID or API key that was generated by the IAM credentials secret engine and delete your instance of Secrets Manager, you must also delete the secret from IAM. For more information, see Managing user API keys.