IBM Cloud Docs
Storing user credentials

Storing user credentials

You can use IBM Cloud® Secrets Manager to store a username and password that you can use to log in to and access a protected service inside or outside of IBM Cloud.

User credentials consist of username and password values that you can use to log in to or access an external service or application. Your secret is stored securely in your dedicated Secrets Manager service instance. In the instance, you can centrally manage its lifecycle, and control the secret's lifespan by setting an expiration date, automatic rotation policies, and more.

In user credentials, only the password value in the can be rotated. Once the username value is set, it cannot be changed.

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.

Adding user credentials in the UI

To store a username and password 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, select the User 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. Enter the username and password that you want to associate with the secret.

    If you choose to generate a password, Secrets Manager replaces the existing value with a randomly generated 32-character password that contains uppercase letters, lowercase letters, digits, and symbols. You can choose to further customize the generated password by configuring its length (12-256 characters), and whether to include numbers, symbols, and upper-case letters.

  12. Optional: Enable expiration and rotation options to control the lifespan of the secret.

    1. To set an expiration date for the secret, switch the expiration toggle to Yes.
    2. To rotate your secret at a 30, 60, or 90-day interval, switch the Automatic secret rotation toggle to Yes.

  13. Click Next.

  14. Review the details of your secret.

  15. Click Add.

Adding user credentials from the CLI

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

To store a username and password by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-create command.

ibmcloud secrets-manager secret-create \    
    --secret-prototype='{"name": "example-username-password-secret","description": "Description of my user credentials secret","secret_type": "username_password","secret_group_id": "bfc0a4a9-3d58-4fda-945b-76756af516aa","labels": ["dev","us-south"],"username": "example-username","password": "example-password","rotation": {"auto_rotate": true,"interval": 10,"unit": "day"},"custom_metadata": {"metadata_custom_key": "metadata_custom_value"},"version_custom_metadata": {"custom_version_key": "custom_version_value"}}'

Generating a random password from the CLI

You can choose to further customize the generated password by configuring its length (12-256 characters), and whether to include numbers, symbols, and upper-case letters. To generate a random password using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-create command and include the password_generation_policy field.

ibmcloud secrets-manager secret-create \    
    --secret-prototype='{"name": "example-username-password-secret","description": "Description of my user credentials secret","secret_type": "username_password","secret_group_id": "bfc0a4a9-3d58-4fda-945b-76756af516aa","labels": ["dev","us-south"],"username": "example-username","password": "example-password","rotation": {"auto_rotate": true,"interval": 10,"unit": "day"},"password_generation_policy": {"length": 24, "include_digits": true, "include_symbols": false, "include_uppercase": 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. For more information about the command options, see ibmcloud secrets-manager secret-create.

Adding user credentials with the API

You can store a username and password programmatically by calling the Secrets Manager API.

The following example shows a query that you can use to create a username and password secret. 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-username-password-secret",
      "description": "Description of my user credentials secret",
      "secret_type": "username_password",
      "secret_group_id": "bfc0a4a9-3d58-4fda-945b-76756af516aa",
      "labels": [
        "dev",
        "us-south"
      ],
      "username": "example-username",
      "password": "example-password",
      "rotation": {
        "auto_rotate": true,
        "interval": 10,
        "unit": "day"
      },
      "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"

Generating a random password with the API

You can choose to further customize the generated password by configuring its length (12-256 characters), and whether to include numbers, symbols, and upper-case letters. When calling the Secrets Manager API include the password_generation_policy field.

curl -X POST 
    -H "Authorization: Bearer {IAM_token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "example-username-password-secret",
      "description": "Description of my user credentials secret",
      "secret_type": "username_password",
      "secret_group_id": "bfc0a4a9-3d58-4fda-945b-76756af516aa",
      "labels": [
        "dev",
        "us-south"
      ],
      "username": "example-username",
      "password": "example-password",
      "rotation": {
        "auto_rotate": true,
        "interval": 10,
        "unit": "day"
      },
      "password_generation_policy": {
        "length": 24,
        "include_digits": true,
        "include_symbols": false,
        "include_uppercase": 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"

Adding user credentials with Terraform

You can store a username and password programmatically by using Terraform for Secrets Manager.

You can either provide a password by setting the optional password argument in the Terraform configuration or choose to generate a random password. If you omit the password argument, Secrets Manager generates a 32-character random password that contains uppercase letters, lowercase letters, digits, and symbols. You can choose to further customize the generated password by configuring its length (12-256 characters), and whether to include numbers, symbols, and upper-case letters.

If you configure the secret with an automatic rotation policy it is recommended to omit the password argument to have the initial password also generated automatically. This is to avoid a Terraform drift situation, where after automatic rotation has occured, Terraform detects that the password had been changed outside of Terraform.

The following example shows a query that you can use to create a username and password secret with a randomly-generated password and auto-rotation enabled. This example also shows how to specify a non-default password generation policy for thr secret.

    resource "ibm_sm_username_password_secret" "test_username_password_secret" {
        instance_id = local.instance_id
        region = local.region
        secret_group_id = "default"
        name = "test-user-creds-secret"
        username = "sm_username"
        rotation {
            auto_rotate = true
            interval = 10
            unit = "day"
        }
        password_generation_policy {
            length = 24
            include_digits = true
            include_symbols = false
            include_uppercase = true
        }
    }

The following example shows a query that you can use to create a username and password secret with the password provided in the Terraform configuration. Auto-rotation is disabled in this example, but you can rotate the password manually by modifying the value of the password argument in the configuration.

    resource "ibm_sm_username_password_secret" "test_username_password_secret" {
        instance_id = local.instance_id
        region = local.region
        secret_group_id = "default"
        name = "test-user-creds-secret"
        username = "sm_username"
        password = "sm_password"
    }

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