IBM Cloud Docs
Creating IAM credentials

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 a 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.

The IAM credential secret that is created by Secrets Manager will also be the name of the IAM API key. For example, a secret called my-secret-name will have a matching API key named Secrets-Manager-IAM-Secret-my-secret-name. If you will later rename the secret in Secrets Manager, this change will not reflect in IAM but functionality will not break.

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.

  1. In the console, click the Menu icon Menu icon > Resource List.

  2. From the list of services, select your instance of Secrets Manager.

  3. In the Secrets table, click Add.

  4. From the list of secret types, click the IAM credentials tile.

  5. Click Next.

  6. Add a name and description to easily identify your secret.

  7. 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.

  8. Optional: Add labels to help you to search for similar secrets in your instance.

  9. 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.

  10. Click Next.

  11. 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.

  12. Optional: Determine whether IAM credentials can be reused for your secret.

  13. Optional: Enable automatic rotation of your secret. Secrets can be automatically rotated only if the reuse IAM credentials option is selected.

  14. Click Next.

  15. Determine the source account.

  16. Determine the scope of access to assign.

  17. Click Next.

  18. Review the details of your secret.

  19. 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.

Determine source account

Secrets Manager can create and manage IAM credential secrets from either the current IBM Cloud account, or from a specific IBM Cloud account. When selecting to create a from a specific account, provide the account's ID.

Determine the scope of access to assign

You might already have a service ID in your account that you want to generate an API key for by selecting the service ID. Alternatively, you can generate both a service ID and an API key by assigning access to an access group.

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

  1. To use an existing service ID, select an ID from the list. If the source account is a specific other account, provide the ID of the service ID, in the following format: ServiceId-c0c7cfa4-b24e-4917-ad74-278f2fee5ba0.

    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.

  2. To generate both a new service ID and API key for the secret, select an access group. If the source account is a specific account, provide the IDs of the wanted access groups.

    By selecting an access group, you determine the scope of permissions that are assigned to the service ID and the API key using the access group. The service ID and API key are generated and associated with your new IAM credential. You can assign up to 10 access groups.

    Access policies should be assigned to the selected access group(s) and not directly to service IDs. Both the service ID and API key are deleted and new ones are created once the IAM credential's TTL is reached.

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 creates 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

Before you begin, follow the CLI docs to set your API endpoint.

To create a service ID and API key by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-create command. To create it in a specific other account add the --iam-credentials-account-id option.

ibmcloud secrets-manager secret-create --secret-type iam_credentials --secret-name "example-iam-credentials-secret" --secret-description "Description of my IAM credentials secret" --iam-credentials-access-groups ["<access_group_id>, ..."] --secret-ttl 30m --iam-credentials-reuse-apikey true

To use an existing service ID and create an API key by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-create command. To create it in a specific other account add the --iam-credentials-account-id option.

ibmcloud secrets-manager secret-create --secret-type iam_credentials --secret-name "example-iam-credentials-secret" --secret-description "Description of my IAM credentials secret" --iam-credentials-service-id "ServiceId-c0c7cfa4-b24e-4917-ad74-278f2fee5ba0" --secret-ttl 90d --iam-credentials-reuse-apikey true

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.

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 the IAM credentials through the end of the lease of your secret, you can use the --iam-credentials-reuse-apikey option. 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, otherwise set it to false. For example, the following example command creates IAM credentials that can be reused until they expire.

ibmcloud secrets-manager secret-create --secret-type iam_credentials --secret-name "example-iam-credentials-secret" --secret-description "Description of my IAM credentials secret" --iam-credentials-service-id "<iam_id_of_service_id>" --secret-ttl 30m --iam-credentials-reuse-apikey true

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 --iam-credentials-reuse-apikey is set to false for IAM credentials, manual rotation for the secret isn't supported. For more information, see Manually rotating secrets.

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 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. To create it in a specific other account add the account_id field.

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 the IAM 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.

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": 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. To create it in a specific other account add the account_id field.

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.

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",
          "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.