Creating service credentials

You can use IBM Cloud® Secrets Manager to create service credentials that you might use to access an IBM Cloud resource that requires authentication.

Service credentials can hold Identity and Access Management issued credentials. The credentials can also be service-specific native credentials such as HMAC keys, a database user ID and password, SASL credentials, or TLS certificates. To learn more about the types of secrets that you can manage by using Secrets Manager, see What is a secret?.

Supported IBM Cloud services

You can create service credentials through Secrets Manager for the following IBM Cloud services:

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.

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

Note that in the case of service credentials created for Databases, if in addition to the credential you are also altering the database permissions for the created credential, these will not be synced once the service credential was rotated. When rotating a Databases service credential, this is considered an identity rotation.

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

The service credential secret that is created by Secrets Manager will also be the name of the resource key. For example, a Service credential secret for Cloud Object Storage called my-secret-name will have a matching resource key in Cloud Object Storage named my-secret-name. If you will later rename the secret in Secrets Manager, this change will not reflect in the resource key but functionality will not break.

Assigning IAM service access role for Service credentials

In order to create a service credential, an IAM service access role must be selected. The available roles to select from may differ between the supported services. See list of supported services for related documentation. The selected role is then attached to an IAM Service ID that can be either an existing Service ID, or an auto-generated one.

The Service ID continues to be used once secret rotation takes place. If deleting a secret, a pre-existing Service ID will not be deleted, however an auto-generated Service ID will be deleted.

If selecting to use a pre-existing Service ID, you can also pre-configure its service access policies. In such a case, select None as the Role when creating the secret. Learn more about IAM policies.

Service credentials best practices

It is recommended to apply the principle of least privilege access for production use-cases:

When setting service-to-service authorization, it should be defined between concrete source and target service instances, not between all services.
When manually setting access for Service IDs to be used with a service credential, it should be applied for a concrete service instance.

Creating Service credentials in the UI

To create Service 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 Service 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.
Select the desired service and service instance to create a credential for

If this is the first time the service instance is selected or a service CRN was provided, first authorize Secrets Manager to access it
1. Click on Authorize and select Key Manager
Click Next.
Provide the requested input, depending on the selected service.
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.
Optional: Set a lease duration or time-to-live (TTL) for the secret.

By setting a lease duration for your Service credential, you determine how long its associated credential remains valid. After the Service credential reaches the end of its lease, it is revoked automatically.
Optional: Enable automatic rotation of your secret.
Click Next.
Review the details of your secret.
Click Add.

Creating Service credentials from the CLI

To create a Service credential secret by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-create command. You can specify the type of secret by using the --secret-type service_credentials option. For example, the following command creates a Service credential for a Cloud Object Storage instance, with HMAC support. As well as specifying the IAM role to provide for this credential, eg Writer.

ibmcloud secrets-manager secret-create --secret-type="service_credentials" --secret-name="example-service-credentials-secret" --secret-source-service='{"instance": {"crn": "CRN of the instance to create a credential for"},"parameters": {"HMAC": true},"role": {"crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"}}'

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 Service credentials with the API

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

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.

In the following example, a service crednetial for Cloud Object Storage is created, with custom parameters with an existing Service ID's IAM ID, and enabling HMAC. As well as specifying the IAM role to provide for this credential, eg Writer.

curl -X POST  
    -H "Authorization: Bearer {iam_token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ 
      {
        "name": "example-service-credentials-secret",
        "description": "Description of my Service Credentials secret",
        "secret_type": "service_credentials",
        "secret_group_id": "bfc0a4a9-3d58-4fda-945b-76756af516aa",
        "labels": [
          "dev",
          "us-south"
        ],
        "source_service": {
          "instance": {
            "crn": "CRN of the instance to create a credential for"
          },
          "parameters": {
            "serviceid_crn": "Existing Service ID's IAM ID",
            "HMAC": true
          },
          "role": {
            "crn": "crn:v1:bluemix:public:iam::::serviceRole:Writer"
          }
        }
      }' \ "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.