Ordering SSL/TLS public certificates

You can use IBM Cloud® Secrets Manager to store, request, and generate public SSL/TLS certificates that you can use for your apps or services.

An SSL/TLS certificate is a type of digital certificate that is used to establish communication privacy between a server and a client. Certificates are issued by certificate authorities (CA)A trusted third-party organization or company that issues the digital certificates. The certificate authority typically verifies the identity of the individuals who are granted the unique certificate. and contain information that is used to create trusted and secure connections between endpoints. After you add a certificate to your Secrets Manager instance, you can use it to secure network communications for your cloud or on-premises deployments. Your certificate is stored securely in your dedicated Secrets Manager service instance, where you can centrally manage its lifecycle.

In Secrets Manager, Certificates that you order through Secrets Manager from a third-party certificate authority are public certificates. Certificates that you import to the service are imported certificates (imported_cert). Certificates that you create by using a private certificate authority are private certificates (private_cert).

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.

Before you order a certificate, be sure that you:

Prepare your instance to order certificates.
Review the certificate authority and DNS provider configurations that are available. To view the configurations that are defined for your instance, go to the Secrets engines > Public certificates page in the Secrets Manager UI.

To work with a DNS provider that is not currently integrated with the service, you do not need to add a configuration to order your public certificate.

Ordering public certificates

After you configure the public certificates engine for your instance, you can use Secrets Manager to request public SSL/TLS certificates from Let's Encrypt. Before a certificate can be issued to you, Secrets Manager uses domain validation to verify the ownership of your domains. When you order a certificate:

Secrets Manager sends your request to the selected certificate authority. The status of the certificate changes to Pre-activation to indicate that your request is being processed.
If the validation completes successfully, your certificate is issued and its status changes to Active.
If the validation doesn't complete successfully, the status of your certificate changes to Deactivated. From your Secrets table, you can check the issuance details of your certificate by clicking the Actions icon > View details.
If the validation doesn't complete successfully, the status of your certificate changes to Deactivated. From your Secrets table, you can check the issuance details of your certificate by clicking the Actions icon > View details.
If the validation doesn't complete successfully, the status of your certificate changes to Deactivated. You can use the Get secret metadata API to check the resources.issuance_info field for issuance details on your certificate.
After the certificate is issued, you can deploy it to your integrated apps, download it, or modify its rotation options.

Ordering public certificates with integrated DNS providers in the UI

You can order a certificate by using the Secrets Manager UI.

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.
Click the Order public certificate tile.
Add a name and description to easily identify your certificate.
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.
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.
Click Next.
Select a certificate authority configuration.

The configuration that you select determines the certificate authority to use for signing and issuing the certificate. To view the configurations that are defined for your instance, you can go to Secrets engines > Public certificates.
Select the key algorithm to be used to generate the public key for your certificate.

The key algorithm that you select determines the encryption algorithm (RSA or ECDSA) and key size to use to generate keys and sign certificates. For longer living certificates, it is recommended to use longer key lengths to provide more encryption protection. Options include RSA2048, RSA4096, ECDSA256, and ECDSA384.
Optional: Enable advanced options for the certificate.
1. To bundle your issued certificate with intermediate certificates, switch the bundle toggle to On. After your certificates are bundled, they can no longer be unbundled. If you choose not to bundle the certificates, this cannot be changed afterwards, only by creating a new secret.
2. To enable automatic rotation for the certificate, switch the rotation toggle to On. Your certificate is rotated 31 days before it expires.
3. To request a new private key with the certificate on each rotation, switch the rekey toggle to On.
Select a DNS provider configuration.

The configuration that you select determines the DNS provider to validate the ownership of your domains. To view the configurations that are defined for your instance, you can go to Secrets engines > Public certificates.
Add the domains to include in your request.

You can include up to 100 domains, subdomains, or wildcards. The Common Name, or fully qualified domain name of the certificate, can't exceed 64 characters in length. A wildcard can be selected as the Common Name.
1. Click Select domains.
2. From your list of domains, select the Common Name of the certificate.
Click Next.
Review the details of your certificate.
Click Add.

When you order a certificate, domain validation takes place to verify the ownership of your selected domains. This process can take a few minutes to complete. After you submit your certificate details, Secrets Manager sends your request to the selected certificate authority. After a certificate is issued, you can deploy it to your integrated apps, download it, or rotate it manually. Your private key for SSL/TLS is generated directly in Secrets Manager and stored securely.

Need to check your order status? From your Secrets table, you can check the issuance details of your certificate by clicking the Actions icon > View details.

Ordering public certificates with integrated DNS providers from the CLI

To order a public certificate with an integrated DNS provider by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-create command.For example, the following command requests a public certificate secret from the certificate authority that you specify.

When you order a certificate, domain validation takes place to verify the ownership of your selected domains. This process can take a few minutes to complete.

ibmcloud secrets-manager secret-create --secret-prototype=
'{
    "name": "example-public-certificate", 
    "description": "Extended description for this secret.",
    "secret_type": "public_cert",
    "secret_group_id": "bc656587-8fda-4d05-9ad8-b1de1ec7e712", 
    "labels": [
        "dev","us-south"
    ], 
    "dns": "dns_provider",
    "common_name": "cert_common_name"
    "alt_names": [
        "alt_name1", "alt_name2"
    ],
    "ca": "lets-encrypt-config",
    "key_algorithm": "RSA2048",
    "rotation": {
        "auto_rotate": true,
        "rotate_keys":false
        },
    "custom_metadata" : {
        "anyKey" : "anyValue"
    },
    "version_custom_metadata" : {
        "anyKey" : "anyValue"
    }
}

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.

Ordering public certificates with integrated DNS providers by using the API

You can order certificates programmatically by calling the Secrets Manager API.

The following example shows a query that you can use to order a certificate. 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.

When you order a certificate, domain validation takes place to verify the ownership of your selected domains. This process can take a few minutes to complete.

curl -X POST  
    -H "Authorization: Bearer {iam_token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ 
            "name": "example-public-certificate",
            "description": "Description of my public certificate",
            "secret_type": "public_cert",
            "secret_group_id": "bfc0a4a9-3d58-4fda-945b-76756af516aa",
            "labels": [
                "dev",
                "us-south"
            ],
            "common_name": "example.com",
            "alt_names": [
                "s1.example.com",
                "*.s2.example.com"
            ],
            "ca": "lets-encrypt-config",
            "dns": "cloud-internet-services-config",
            "rotation": {
                "auto_rotate": true,
                "rotate_keys": true
            },
            "bundle_certs": 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"

When you submit your certificate details, Secrets Manager sends your request to the selected certificate authority. After a certificate is issued, you can deploy it to your integrated apps, download it, or rotate it manually. Your private key for SSL/TLS is generated directly in Secrets Manager and stored securely. For more information about the required and optional request parameters, see Create a secret.

Need to check your order status? Use the Get secret metadata API to check the resources.issuance_info field for issuance details on your certificate.

Ordering public certificates with integrated DNS providers by using Terraform

The following example shows a configuration that you can use to order a public certificate.

    resource "ibm_sm_public_certificate" "sm_public_certificate" {
        instance_id = local.instance_id
        region = local.region
        name = "test-public-certificate"
        secret_group_id = "default"
        ca = ibm_sm_public_certificate_configuration_ca_lets_encrypt.my_lets_encrypt_config.name
        dns = ibm_sm_public_certificate_configuration_dns_cis.my_cis_dns_config.name
        rotation {
            auto_rotate = true
            rotate_keys = false
        }
    }

Ordering public certificates with your own DNS provider in the UI

To create a public certificate by using a manual DNS provider in the 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.
Click the Order public certificate tile.
Add a name and description to easily identify your certificate.
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.
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.
Click Next.
Select a certificate authority configuration.

The configuration that you select determines the certificate authority to use for signing and issuing the certificate. To view the configurations that are defined for your instance, you can go to Secrets engines > Public certificates.
Select the key algorithm to be used to generate the public key for your certificate.

The key algorithm that you select determines the encryption algorithm (RSA or ECDSA) and key size to use to generate keys and sign certificates. For longer living certificates, it is recommended to use longer key lengths to provide more encryption protection. Options include RSA2048, RSA4096, ECDSA256, and ECDSA384.
Optional: Enable advanced options for the certificate.
1. To bundle your issued certificate with intermediate certificates, switch the bundle toggle to On. After your certificates are bundled, they can no longer be unbundled. If you choose not to bundle the certificates, this cannot be changed afterwards, only by creating a new secret.
2. To enable automatic rotation for the certificate, switch the rotation toggle to On. Your certificate is rotated 31 days before it expires.
3. To request a new private key with the certificate on each rotation, switch the rekey toggle to On.
Select Manual as your DNS provider.
Add the domains to include in your request.

You can include up to 100 domains, subdomains, or wildcards. The Common Name, or fully qualified domain name of the certificate, can't exceed 64 characters in length. A wildcard can be selected as the Common Name.
1. In the Common name section, from your list of domains, select the Common Name of the certificate.
Click Next.
Review the details of your certificate.
Click Add.
Check the issuance details of your certificate by clicking the Actions icon > View details.
Click Challenges to access the TXT record name and value that are associated with each of your domains. You need them to complete the challenges.
To validate the ownership of your domains, manually add the TXT records that are provided for each of your domains to your DNS provider account. You must address only the challenges that are not validated before the expiration date.

If you order a certificate for a subdomain, for example, sub1.sub2.domain.com, you need to add the TXT records to your registered domain domain.com.
Verify that the TXT records that you added to your domains are propagated. Depending on your DNS provider, it can take some time to complete.
After you confirm that the records are propagated, click Validate to request Let's Encrypt to validate the challenges to your domains and create a public certificate.

If the order fails because the TXT records were not successfully propagated, you must start a new order to proceed.
When your certificate is issued, clean up and remove the TXT records from the domains in your DNS provider account.

Ordering public certificates with your own DNS provider by using the API

To create a public certificate by using a manual DNS provider, complete the following steps.

Create a certificate authority (CA) configuration by following the steps that are defined in Adding a CA configuration.

Create a new public certificate by specifying manual as your DNS configuration.

curl -X POST 
    -H "Authorization: Bearer {iam_token}" \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -d '{ 
            "name": "example-public-certificate",
            "description": "description of my public certificate",
            "secret_type": "public_cert",
            "secret_group_id": "bfc0a4a9-3d58-4fda-945b-76756af516aa",
            "labels": [
                "dev",
                "us-south"
            ],
            "common_name": "example.com",
            "alt_names": [
                "s1.example.com",
                "*.s2.example.com"
            ],
            "ca": "lets-encrypt-config",
            "dns": "manual",
            "rotation": {
                "auto_rotate": true,
                "rotate_keys": true
            },
            "bundle_certs": 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"

Example response:

"metadata": {
   "collection_type": "application/vnd.ibm.secrets-manager.secret+json",
   "collection_total": 1
 },
"resources": [
 {
   "alt_names": [
     "domain2",
     "domain3"
   ],
   "common_name": "domain1",
   "created_by": "User",
   "creation_date": "2022-09-13T06:21:33Z",
   "crn": "secret crn",
   "description": "Description for ordered certificate.",
   "downloaded": false,
   "id": "38747ae6-8c69-d745-5276-cdf3157b9021",
   "issuance_info": {
   "auto_rotated": false,
   "bundle_certs": false,
   "ca": "ca_config_name",
   "challenges": [
     {
         "domain": "domain1",
         "expiration": "2022-09-20T06:21:36Z",
         "status": "pending",
         "txt_record_name": "_acme-challenge.domain1.",
         "txt_record_value": "TA6J7fFYrwP3Jg-S_IAQSj2Ydqfw4Ycm4sMwlzuCcxk"
     },
         {
            "domain": "domain2",
            "expiration": "2022-09-20T06:21:36Z",
            "status": "pending",
            "txt_record_name": "_acme-challenge.domain2.",
            "txt_record_value": "qSDrCkFAViX4xANKuEPcMNairWm1PUtROm6kp9bmSS0"
         },
         {
            "domain": "domain3",
            "expiration": "2022-09-20T06:21:36Z",
            "status": "pending",
            "txt_record_name": "_acme-challenge.domain3.",
            "txt_record_value": "8dcgan91fW6aK3aIhPAVZRkHpbYEoMcCNPpVh1n4tSA"
         }
      ],
   "dns": "manual",
   "ordered_on": "2022-09-13T06:21:33Z",
   "state": 0,
   "state_description": "Pre-activation"
   },
   "key_algorithm": "RSA2048",
   "labels": [],
   "last_update_date": "2022-09-13T06:21:33Z",
   "locks_total": 0,
   "name": "my-public-certificate",
   "rotation": {
   "auto_rotate": false,
   "rotate_keys": false
   },
   "secret_type": "public_cert",
   "state": 0,
   "state_description": "Pre-activation",
   "versions": [],
   "versions_total": 1
   }
]

Complete the challenges that are marked as pending before they expire by adding the TXT records that are specified in the challenge to your domain in your DNS provider account to verify your ownership of the domain.

If you order a certificate for subdomains, for example, sub1.sub2.domain.com, you need to add the TXT records to your registered domain domain.com.
Validate that the TXT records that you added are propagated. Depending on your DNS provider, it can take some time to complete.
After the records are propagated, call the Secrets Manager Create a secret action API to request Let's Encrypt to validate the challenges to your domain and create a public certificate.
```
 curl -X POST 
 --header "Authorization: Bearer {iam_token}" 
 --header "Accept: application/json" 
 --header "Content-Type: application/json" 
 --data '{ 
     "action_type": "public_cert_action_validate_dns_challenge"
 }'\ 
 "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/actions"
```
If you need to update your certificate later, you can use the Create a secret action API but with the action rotate. However, you can't automatically rotate manual DNS provider certificates in Secrets Manager.
When your certificate is issued, clean up and remove the TXT records from the domains in your DNS provider account.

Want to automate the creation of your public certificates? If your domains are configured through a DNS provider, you can create a script to complete the challenges. Some DNS providers offer an API that checks whether the new records are fully transmitted. If your DNS provider doesn't offer this option, you can configure your client to wait for a specified amount of time, sometimes up to an hour. In Secrets Manager, after you call validate-dns-challenges, you can check the status of the certificate issuance by obtaining your certificate metadata. When the IssuanceInfo.State field that is returned changes to active, the certificate is issued.

Ordering public certificates with your own DNS provider by using the CLI

To order a public certificate with your own DNS provider by using the Secrets Manager CLI plug-in, run the ibmcloud secrets-manager secret-create command. For example, the following command requests a public certificate secret from the certificate authority that you specify.

When you order a certificate, domain validation takes place to verify the ownership of your selected domains. This process can take a few minutes to complete.

ibmcloud secrets-manager secret-create --secret-prototype \
'{
    "name": "example-public-certificate", 
    "description": "Extended description for this secret.", 
    "secret_group_id": "bc656587-8fda-4d05-9ad8-b1de1ec7e712", 
    "labels": [
        "dev","us-south"
    ], 
    "dns": "manual",
    "common_name": "cert_common_name"
    "alt_names": [
        "alt_name1", "alt_name2"
    ],
    "ca": "lets-encrypt-config",
    "key_algorithm": "RSA2048",
    "rotation": {
        "enabled": false,
        "rotate_keys":false
        },
    "custom_metadata" : {
        "anyKey" : "anyValue"
    },
    "version_custom_metadata" : {
        "anyKey" : "anyValue"
    }
}

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.

Ordering public certificates with Akamai DNS provider by using Terraform

To create a public certificate by using Akamai as your DNS provider, complete the following steps.

Create a certificate authority (CA) configuration by following the steps that are defined in Adding a CA configuration.
Create a new public certificate by specifying akamai as your DNS configuration.

Use one of the following Akamai's authentication methods. You can use an edgerc file or directly provide your Akamai authentication credentials. Learn more about Akamai's authentication credentials.

a. Provide the path to your .edgerc file and the relevant config_section.

  resource "ibm_sm_public_certificate" "sm_public_certificate" {
      instance_id = local.instance_id
      region = local.region
      name = "test-public-certificate"
      secret_group_id = "default"
      ca = ibm_sm_public_certificate_configuration_ca_lets_encrypt.my_lets_encrypt_config.name
      dns = “akamai”
      akamai {
          edgerc {
            path_to_edgerc = “/path/to/your/edgerc/file”
            config_section = “default”
          }
      }
      rotation {
          auto_rotate = true
          rotate_keys = false
      }
  }

  b. Provide your Akamai's authentication credentials:
  ```terraform {: pre}
    resource "ibm_sm_public_certificate" "sm_public_certificate" {
        instance_id = local.instance_id
        region = local.region
        name = "test-public-certificate"
        secret_group_id = "default"
        ca = ibm_sm_public_certificate_configuration_ca_lets_encrypt.my_lets_encrypt_config.name
        dns = “akamai”
        akamai {
            config {
              client_secret = “your_client_secret”
              host = “your_host”
              access_token = "your_access_token"
              client_token = "your_client_token"
            }
        }
        rotation {
            auto_rotate = true
            rotate_keys = false
        }
    }

The newly-created TXT records that are in the relevant domains in Akamai are not automatically deleted.

Ordering public certificates with your own DNS provider by using Terraform

Create a certificate authority (CA) configuration by following the steps that are defined in Adding a CA configuration.
Create a new public certificate by specifying manual as your DNS configuration.

    resource "ibm_sm_public_certificate" "sm_public_certificate" {
        instance_id = local.instance_id
        region = local.region
        name = "test-public-certificate"
        secret_group_id = "default"
        ca = ibm_sm_public_certificate_configuration_ca_lets_encrypt.my_lets_encrypt_config.name
        dns = “manual”
        rotation {
            auto_rotate = true
            rotate_keys = false
        }
    }

Example response:

{
   "alt_names": [
     "domain2",
     "domain3"
   ],
   "bundle_certs": false,
   "ca": "ca_config_name",
   "common_name": "domain1",
   "created_by": "User",
   "creation_date": "2022-09-13T06:21:33Z",
   "crn": "secret crn",
   "description": "Description for ordered certificate.",
   "downloaded": false,
   "id": "38747ae6-8c69-d745-5276-cdf3157b9021",
   "issuance_info": {
       "auto_rotated": false,
       "challenges": [
         {
             "domain": "domain1",
             "expiration": "2022-09-20T06:21:36Z",
             "status": "pending",
             "txt_record_name": "_acme-challenge.domain1.",
             "txt_record_value": "TA6J7fFYrwP3Jg-S_IAQSj2Ydqfw4Ycm4sMwlzuCcxk"
         },
             {
               "domain": "domain2",
               "expiration": "2022-09-20T06:21:36Z",
               "status": "pending",
               "txt_record_name": "_acme-challenge.domain2.",
               "txt_record_value": "qSDrCkFAViX4xANKuEPcMNairWm1PUtROm6kp9bmSS0"
             },
             {
               "domain": "domain3",
               "expiration": "2022-09-20T06:21:36Z",
               "status": "pending",
               "txt_record_name": "_acme-challenge.domain3.",
               "txt_record_value": "8dcgan91fW6aK3aIhPAVZRkHpbYEoMcCNPpVh1n4tSA"
             }
         ],
       "dns": "manual",
       "ordered_on": "2022-09-13T06:21:33Z",
       "state": 0,
       "state_description": "Pre-activation"
       },
   "key_algorithm": "RSA2048",
   "labels": [],
   "last_update_date": "2022-09-13T06:21:33Z",
   "locks_total": 0,
   "name": "my-public-certificate",
   "rotation": {
       "auto_rotate": false,
       "rotate_keys": false
    },
   "secret_type": "public_cert",
   "state": 0,
   "state_description": "Pre-activation",
   "versions": [],
   "versions_total": 1
}

Complete the challenges that are marked as pending before they expire by adding the TXT records that are specified in the challenge to your domain in your DNS provider account to verify your ownership of the domain.

If you order a certificate for subdomains, for example, sub1.sub2.domain.com, you need to add the TXT records to your registered domain domain.com.
Validate that the TXT records that you added are propagated. Depending on your DNS provider, it can take some time to complete.
After the records are propagated, request Let's Encrypt to validate the challenges to your domain and create a public certificate. You can do this by using the Terraform’s ibm_sm_public_certificate_action_validate_manual_dns resource, as shown in the following example of a configuration:

    resource "ibm_sm_public_certificate_action_validate_manual_dns" "sm_public_certificate_action_validate_manual_dns_instance" {
        instance_id = local.instance_id
        region = local.region
        secret_id = ibm_sm_public_certificate.sm_public_certificate.secret_id
    }

You can use Terraform’s depends_on meta-argument to insure Terraform’s configuration is being created in the correct logical order as shown in these instructions.

Alternatively, you can call the Secrets Manager Create a secret action API to request Let's Encrypt to validate the challenges to your domain and create a public certificate.

 curl -X POST 
 --header "Authorization: Bearer {iam_token}" 
 --header "Accept: application/json" 
 --header "Content-Type: application/json" 
 --data '{ 
     "action_type": "public_cert_action_validate_dns_challenge"
 }'\ 
 "https://{instance_ID}.{region}.secrets-manager.appdomain.cloud/api/v2/secrets/{id}/actions"

After your certificate is issued (its state is active), you must run the Terraform command terraform apply again in order to update your public certificate’s Terraform resource and to use your newly issued certificate.
Clean up and remove the TXT records from the domains in your DNS provider account.