Configuring the IAM credentials engine

Setting up the IAM credentials engine in the UI

You can add an IAM credentials engine configuration by using the Secrets Manager UI. To configure your instance to start creating IAM credentials, complete the following steps.

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

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

3. In the Secrets engines page, click the IAM credentials tab.

4. Click Configure.

5. Enter an API key that has access to create and manage other API keys in your account.

   The service ID that is associated with your API key must have Editor platform access on the IAM Access Groups Service, Service ID creator access, and Operator platform access on the IAM Identity Service.

6. Click Configure.

   Now, your Secrets Manager instance is enabled for IAM credential secrets.

Setting up the IAM credentials engine from the CLI

Before you can create dynamic IAM credentials, you must configure the IAM secrets engine for your service instance. Start by entering an IBM Cloud API key that is associated with a service ID in your IBM Cloud account.

To allow your IBM Cloud API key to create and manage other API keys dynamically, its associated service ID must have Editor platform access for the IAM Access Groups Service, Operator platform access for the IAM Identity Service.

1. In a terminal window, log in to IBM Cloud through the IBM Cloud CLI.

   ibmcloud login
   

   If the login fails, run the ibmcloud login --sso command to try again. The --sso parameter is required when you log in with a federated ID. If this option is used, go to the link listed in the CLI output to generate a one-time passcode.

2. Select the account, region, and resource group where your Secrets Manager service instance is located.

3. Create a service ID and set it as an environment variable.

   export SERVICE_ID=`ibmcloud iam service-id-create <service_ID_name> --description "<description>" --output json | jq -r ".id"`; echo $SERVICE_ID
   

4. Manage access for the service ID.

   Assign the service ID permissions to create and manage other service IDs.

   ibmcloud iam service-policy-create $SERVICE_ID --roles Operator --service-name "iam-identity"
   

   Assign the service ID permissions to view and update access groups in your account.

   ibmcloud iam access-group-policy-create $SERVICE_ID --roles Editor --service-name "iam-groups"
   

   Add the service ID to an access group in your account.

   ibmcloud iam access-group-service-id-add <access_group_name> $SERVICE_ID
   

   Create an IBM Cloud API key for your service ID.

   export IBM_CLOUD_API_KEY=`ibmcloud iam service-api-key-create <API_key_name> $SERVICE_ID --description "<description>" --output json | jq -r ".apikey"`
   

5. Use the API key to configure the IAM secrets engine for your instance.

   To configure a secrets engine from the IBM Cloud CLI, run the ibmcloud secrets-manager configuration-create command.

   ibmcloud secrets-manager configuration-create --configuration-prototype='{"config_type": "iam_credentials_configuration","name": "iam-configuration","api_key": "'$IBM_CLOUD_API_KEY'"}'
   

   Using a Windows™ command prompt (cmd.exe) or PowerShell? If you encounter errors with passing JSON content on the command line, you might need to adjust the strings for quotation-escaping requirements that are specific to your operating system. For more information, see Using quotation marks with strings in the IBM Cloud CLI.

Configuring the IAM credentials engine with the API

Before you can create dynamic IAM credentials, you must configure the IAM secrets engine for your service instance. You can configure a secrets engine programmatically by calling the Secrets Manager API.

First, you need an IBM Cloud API key that is associated with a service ID in your IBM Cloud account. To allow your IBM Cloud API key to create and manage other API keys dynamically, its associated service ID must have Editor platform access for the IAM Access Groups Service, and Operator platform access for the IAM Identity Service.

For step-by-step instructions to create an IBM Cloud API key with the correct level of access, switch to the UI or CLI steps.

The following example shows a query that you can use to configure a secrets engine for your instance. When you call the API, replace the API key variables and IAM token with the values that are specific to your Secrets Manager instance.

curl -X POST 
  --H "Authorization: Bearer {iam_token}" \
  --H "Accept: application/json" \
  --H "Content-Type: application/json" \
  --d '{ 
    "api_key": "2epu_ykv0PMp2MhxQmDMn7VzrkSlBwi6BOI8uthi_RCS", "config_type": "iam_credentials_configuration", 
    "name": "iam-configuration" 
    }' \ 
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/configurations"

A successful response returns the ID value of the secret, along with other metadata. For more information about the required and optional request parameters, see Create a secret.

Configuring the IAM credentials engine with Terraform

Before you can create dynamic IAM credentials, you must configure the IAM secrets engine for your service instance. You can configure a secrets engine programmatically by using Terraform for Secrets Manager.

The following example shows a configuration that you can use to configure the IAM credentials engine.

    resource "ibm_sm_iam_credentials_configuration" "iam_credentials_configuration" {
        instance_id = local.instance_id
        region = local.region
        name = "iam_credentials_config"
        api_key = var.ibmcloud_api_key
    }

Retrieving an IAM engine's configuration value in the UI

You can retrieve an engine's configuration by using the Secrets Manager UI.

1. In the IAM credentials secret engine, click the Actions menu to open a list of options for your engine configuration.
2. To view the configuration value, click View configurationt.
3. Click Confirm after you ensure that you are in a safe environment.

The secret value is displayed for 15 seconds, then the dialog closes.

Retrieving an engine's configuration value using CLI

You can retrieve an engine's configuration by using the Secrets Manager CLI. In the following example command, replace the engine configuration name with your configuration's name.

ibmcloud secrets-manager configuration --name EXAMPLE_CONFIG --service-url https://{instance_ID}.{region}.secrets-manager.appdomain.cloud

Replace {instance_ID} and {region} with the values that apply to your Secrets Manager service instance. To find the endpoint URL that is specific to your instance, you can copy it from the Endpoints page in the Secrets Manager UI. For more information, see Viewing your endpoint URLs

Retrieving an engine's configuration value using API

You can retrieve an engine's configuration by using the Secrets Manager API. In the following example request, replace the engine configuration name with your configuration's name.

curl -X GET --location --header "Authorization: Bearer {iam_token}" \
--header "Accept: application/json" \
"https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/configurations/{name}"

Replace {instance_ID} and {region} with the values that apply to your Secrets Manager service instance. To find the endpoint URL that is specific to your instance, you can copy it from the Endpoints page in the Secrets Manager UI. For more information, see Viewing your endpoint URLs

A successful response returns the value of the engine configuration, along with other metadata. For more information about the required and optional request parameters, see Get a secret.