IBM Cloud Docs
Connecting third-party certificate authorities

Connecting third-party certificate authorities

With IBM Cloud® Secrets Manager, you can connect to a third-party certificate authority by adding a configuration to your instance.

A certificate authority (CA) is the entity that signs and issues your SSL/TLS certificates. By adding a CA configuration, you can specify the authority that you want to use when you order public certificates through Secrets Manager.

You can define up to 10 certificate authority configurations per instance. To view a list of configurations that are available for your instance, go to the Secrets engines > Public certificates page in the Secrets Manager UI.

You can define up to 10 certificate authority configurations per instance. To obtain a list of configurations that are available for your instance, you can use the List configurations API.

Before you begin

Before you get started, be sure that you have the required level of access. To manage engine configurations for your instance, you need the Manager service role or higher.

Supported certificate authorities

You can integrate the following certificate authorities with your Secrets Manager service instance.

Table 1. Prerequisites - Let's Encrypt
Prerequisites

Before you connect Let's Encrypt, be sure that you:

  • Obtain the private key that's associated with your Automatic Certificate Management Environment (ACME) account.
    The ACME protocol makes it possible to automatically obtain browser trusted certificates without human intervention. Before you can request Let's Encrypt certificates through Secrets Manager, you must have an ACME account. If you already have a working ACME account, you need the private key that was generated when the account was initially created.

  • Optional: Create an ACME account.
    If you don't have an existing ACME client or account, you can create one by using the ACME account creation tool.

Certificate authorities might apply a charge when you order or renew a certificate. Additionally, various rate limits apply. Secrets Manager does not control costs or rate limits that are associated with ordering certificates. For more information about rate limits to keep in mind as you order Let's Encrypt certificates, check out the Let's Encrypt documentation.

Adding a certificate authority configuration in the UI

You can add certificate authority configurations to your service instance by using the Secrets Manager UI.

  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 engines page, click the Public certificates tab.

  4. In the Certificate authorities table, click Add.

  5. Select the certificate authority that you want to use. Currently, Let's Encrypt is supported.

    1. To target the production environment, select Let's Encrypt.
    2. To target the staging environment, select Let's Encrypt (Staging). Choose this option if you'd like to issue certificates that aren't production-ready yet.
  6. Add the private key file in PEM format that's associated with your ACME account or enter its value.

  7. Click Add.

    You can now select this configuration when you order a certificate. To modify or remove an existing configuration, click Actions menu Actions icon in the row of the configuration that you want to update.

Adding a certificate authority configuration from the CLI

You can add certificate authority configurations to your service instance by using the Secrets Manager CLI.

To add a configuration, run the ibmcloud secrets-manager configuration-create command.

ibmcloud secrets-manager configuration-create '{
  config_type": "public_cert_configuration_ca_lets_encrypt",
  "lets_encrypt_environment": "production", 
  "lets_encrypt_private_key": "-----BEGIN PRIVATE KEY-----\nMY_PRIVATE_KEY_WITH_NEWLINES_TRANSFORMED_TO_\N_CHARS-----...", "name": "my-lets-encrypt-config"
  }'

Adding a certificate authority configuration with the API

You can add certificate authority configurations to your service instance by calling the Secrets Manager API.

The following example shows a query that you can use to add a configuration for Let's Encrypt. When you call the API, replace the private_key value with the private key that is associated with your ACME account.

Be sure to convert your private key file to single-line format so that it can be parsed correctly by the Secrets Manager API. You can use the following UNIX command to format the file to a single-line string: awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' <private_key_file>

curl -X POST 
  --H "Authorization: Bearer {iam_token}" \
  --H "Accept: application/json" \
  --H "Content-Type: application/json" \
  --d '{
    "config_type": "public_cert_configuration_ca_lets_encrypt",
    "lets_encrypt_environment": "production",
    "lets_encrypt_private_key": "-----BEGIN PRIVATE KEY-----\nMIIEowIBAAKCAQEAqcRbzV1wp0nVrPtEpMtnWMO6Js1q3rhREZluKZfu0Q8SY4H3",
    "name": "lets-encrypt-config"
  }' \
    "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/configurations"

A successful response adds the configuration to your service instance. For more information about the required and optional request parameters, see Add a configuration.

Adding a certificate authority configuration with Terraform

The following example shows a configuration that you can use to create a root certificate authority.

    resource "ibm_sm_public_certificate_configuration_ca_lets_encrypt" "my_lets_encrypt_config" {
        instance_id = local.instance_id
        region = local.region
        name = "lets-encrypt-config"
        lets_encrypt_environment = "production"
        lets_encrypt_private_key = var.my_lets_encrypt_private_ley
    }

Deleting a certificate authority configuration in the UI

If you no longer need a configuration, you can delete it by using the Secrets Manager UI.

After you delete a configuration, the certificates that are associated with the certificate authority can no longer be rotated automatically. Do not delete configurations that are associated with certificates in your production apps or services.

  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 engines page, click the Public certificates tab.

  4. Use the Certificate authorities table to view the configurations in your instance.

  5. In the row for the configuration that you want to delete, click the Actions menu Actions icon > Delete.

  6. Enter the name of the configuration to confirm its deletion.

  7. Click Delete.

Deleting a certificate authority configuration with the API

You can delete configurations by calling the Secrets Manager API.

The following example shows a query that you can use to remove a certificate authority configuration from your instance. When you call the API, replace {config_name} with the name of the configuration that you want to delete.

After you delete a configuration, the certificates that are associated with the certificate authority can no longer be rotated automatically. Do not delete configurations that are associated with certificates in your production apps or services.

curl -X DELETE 
  --H "Authorization: Bearer {iam_token}"\
  "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/configurations/{name}"

A successful response removes the configuration from your service instance. For more information about the required and optional request parameters, see Remove a configuration.

Retrieving a certificate authority configuration in the UI

You can retrieve the certificate authority value by using the Secrets Manager UI.

  1. In the Public certificates secret engine, click the Actions menu Actions icon from the Certificate authority table 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 a certificate authority configuration using CLI

You can retrieve the certificate authority value 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 a certificate authority configuration using API

You can retrieve the certificate authority value 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.

Next steps