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 group 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.
- 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
orECDSA
) 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 includeRSA2048
,RSA4096
,ECDSA256
, andECDSA384
. -
Optional: Enable advanced options for the certificate.
- 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.
- To enable automatic rotation for the certificate, switch the rotation toggle to On. Your certificate is rotated 31 days before it expires.
- 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.
- Click Select domains.
- From your list of domains, select the Common Name of the certificate.
You can optionally also manually add valid domains using the Add domains manually field.
-
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
Before you begin, follow the CLI docs to set your API endpoint.
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 group 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.
- 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
orECDSA
) 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 includeRSA2048
,RSA4096
,ECDSA256
, andECDSA384
. -
Optional: Enable advanced options for the certificate.
- 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.
- 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.
- 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 domaindomain.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.-
Provide the path to your
.edgerc
file and the relevantconfig_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 } }
2. 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 domaindomain.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 commandterraform 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.