Oracle Cloud Infrastructure Documentation
Try Free Tier

Setting Up Custom Domains and TLS Certificates

Find out how to set up custom domains and TLS certificates with API Gateway.

The API gateways you create with the API Gateway service are TLS-enabled, and therefore require TLS certificates (formerly SSL certificates) issued by a Certificate Authority to secure them. You can direct the API Gateway service to obtain a default TLS certificate for you (if your tenancy exists in the OC1 realm), or you can obtain a custom TLS certificate from a Certificate Authority yourself. To specify a particular custom domain name for an API gateway, you must obtain a custom TLS certificate, rather than have the API Gateway service obtain a default TLS certificate.

When you create an API gateway, you specify that the API gateway uses one of the following:

  • A default TLS certificate that the API Gateway service obtains for you (OC1 realm only). In this case, the API Gateway service requests a TLS certificate from an Oracle-designated Certificate Authority.
  • A custom TLS certificate that you obtain from your chosen Certificate Authority yourself. Your request to the Certificate Authority includes the custom domain name. The Certificate Authority returns a file containing the custom TLS certificate, and typically one or more files containing intermediate certificates forming a certificate chain from the TLS certificate back to the Certificate Authority.

You can obtain a custom TLS certificate in multiple ways:

  • You can obtain a custom TLS certificate from a third-party Certificate Authority, and then create an API Gateway certificate resource comprising the custom TLS certificate, any intermediate certificates, and the private key used to generate the TLS certificate. You can then select that API Gateway certificate resource when creating a new API gateway.
  • You can obtain a custom TLS certificate using the Certificates service to create a certificate resource. The Certificates service can issue a certificate directly, or you can import a certificate issued by a third-party Certificate Authority into the Certificates service. You can then select that Certificates service certificate resource when creating a new API gateway.

The way in which the TLS certificate is obtained determines how much control you have over the API gateway's domain name:

  • If the API Gateway service obtains a default TLS certificate for you (OC1 realm only), the API Gateway service gives the API gateway an auto-generated default domain name. The auto-generated default domain name comprises a random string of characters followed by .apigateway.<region-identifier>.oci.customer-oci.com. For example, laksjd.apigateway.us-phoenix-1.oci.customer-oci.com .
  • If you obtain a custom TLS certificate yourself, the API Gateway service gives the API gateway the custom domain name you specified in your request to the Certificate Authority.

The way in which the TLS certificate is obtained also determines responsibility for recording the mapping between the API gateway's domain name and its public IP address with a DNS provider:

  • If the API Gateway service obtains a default TLS certificate for you (OC1 realm only), the API Gateway service takes responsibility for recording the mapping between the API gateway's auto-generated default domain name and its public IP address with the Oracle Cloud Infrastructure DNS service.
  • If you obtain a custom TLS certificate yourself, you are responsible for recording the mapping between the API gateway's custom domain name and its public IP address with your chosen DNS provider as an A record.

Similarly, the handling of TLS certificate expiry and renewal is determined by how the TLS certificate is originally obtained:

  • If the API Gateway service obtains a default TLS certificate for you (OC1 realm only), the API Gateway service automatically renews the TLS certificate with the Oracle-designated Certificate Authority before it expires.
  • If you obtain a custom TLS certificate yourself, you are responsible for renewing the TLS certificate with your chosen Certificate Authority before it expires. See Renewing Custom TLS Certificates Used by API Gateways.

For some customers, use of custom domains and custom TLS certificates is obligatory. For example, if you are using Oracle Cloud Infrastructure Government Cloud, you are required to:

  • only obtain a TLS certificate from a particular, approved Certificate Authority
  • only use a particular, approved DNS provider

For other customers, use of custom domains is likely to be driven by commercial requirements. For example, typically you'll want to include your company name in the API gateway's domain name, rather than using the auto-generated random string of characters followed by .apigateway.<region-identifier>.oci.customer-oci.com.

Note the following:

  • You cannot delete an API Gateway certificate resource or Certificates service certificate resource that is currently being used by an API gateway. To delete the certificate resource, you must first remove it from any API gateway that is using it.
  • You can only specify one API Gateway certificate resource or Certificates service certificate resource for an API gateway.
  • You cannot update an API Gateway certificate resource after you have created it. However, you can update a Certificates service certificate resource.
  • You can only direct the API Gateway service to obtain default TLS certificates for you if your tenancy exists in the OC1 realm.
Important

For public or production systems, Oracle recommends using custom TLS certificates. Oracle recommends only using default TLS certificates obtained by the API Gateway service for private or non-production systems (for example, for development and testing).

Obtaining a Custom TLS Certificate to Set Up a Custom Domain Name for an API Gateway

You can set up a custom domain name and custom TLS certificate in multiple ways:

Using an API Gateway Certificate Resource to Set Up a Custom Domain Name for an API Gateway

To use an API Gateway certificate resource to set up a custom domain name for an API gateway:

Using a Certificates Service Certificate Resource to Set Up a Custom Domain Name for an API Gateway

To use a Certificates service certificate resource to set up a custom domain name for an API gateway:

Renewing Custom TLS Certificates Used by API Gateways

TLS certificates are valid for a limited period of time (typically one or two years) before they expire. If the TLS certificate used by an API gateway expires, calls to an API deployed on the API gateway might be marked as insecure by the API client (for example, by a browser or by the curl command line tool) and blocked. To avoid blocked calls, you have to renew TLS certificates before they expire (sometimes referred to as 'rotating' certificates).

If the API Gateway service obtained the original TLS certificate for you, the API Gateway service automatically renews the TLS certificate with the Oracle-designated Certificate Authority before it expires. However, if you obtained a custom TLS certificate yourself, you are responsible for renewing the custom TLS certificate with your chosen Certificate Authority before it expires. When you request the renewal of a TLS certificate, the Certificate Authority returns a completely new TLS certificate.

The procedure for renewing a custom TLS certificate used by API gateways depends on whether you've created API Gateway certificate resources or Certificates service certificate resources.

Renewing custom TLS certificates for API Gateway certificate resources

When you've created an API Gateway certificate resource used by an API gateway, you cannot simply update the existing API Gateway certificate resource with the new TLS certificate. Instead, you create a new API Gateway certificate resource, add the new TLS certificate to the new certificate resource, and then update any API gateways that used the previous certificate resource to use the new certificate resource.

To renew the custom TLS certificate used by an API gateway:

  1. Submit a TLS certificate renewal request to the Certificate Authority from which you originally obtained the TLS certificate. The exact steps to renew a TLS certificate depend on the Certificate Authority you use, so always refer to the Certificate Authority documentation for more detailed information.

    When you create the certificate renewal request, a public key is added to the request, and a corresponding private key is also generated and stored in a local file. You'll use this private key when you set up the new API Gateway certificate resource, so make a note of its location.

    The Certificate Authority returns a file containing the new custom TLS certificate, and typically one or more files containing intermediate certificates forming a certificate chain from the TLS certificate back to the Certificate Authority.

  2. Create a new API Gateway certificate resource and add to it the new TLS certificate, any intermediate certificates, and the new private key (see Step 2: Create an API Gateway certificate resource).
  3. Update all the existing API gateways that used the original API Gateway certificate resource to use the new API Gateway certificate resource (see Updating an API Gateway).
  4. When there are no API gateways still using the original API Gateway certificate resource, delete the original certificate resource:
    • If using the Console: On the Certificates page, select the Actions menu (Actions Menu) beside the original API Gateway certificate resource you want to delete, and then select Delete.
    • If using the CLI: Use the following command to delete the original API Gateway certificate resource:
      Command
      oci api-gateway certificate delete --certificate-id <certificate-ocid>

    Note that you cannot delete an API Gateway certificate resource if there are API gateways still using it.

Renewing custom TLS certificates for Certificates service certificate resources

When you've created a Certificates service certificate resource used by an API gateway, you can use the Certificates service to renew the TLS certificate by creating a new certificate version. The new certificate version has the same OCID as the original certificate, so you don't have to modify API gateways to use a new certificate resource. The API Gateway service automatically updates API gateways to use the new version. Note that there are some restrictions on the certificates that the Certificates service can renew. See Renewing a Certificate.

Using the API

For information about using the API and signing requests, see REST API documentation and Security Credentials. For information about SDKs, see SDKs and the CLI.

Use the:

  • CreateCertificate operation to create a new API Gateway certificate resource.
  • DeleteCertificate operation to delete an existing API Gateway certificate resource.
  • UpdateCertificate operation to change the details of an existing API Gateway certificate resource.
  • GetCertificate operation to see details of an existing API Gateway certificate resource.
  • ListCertificates operation to list all the certificates in a compartment.
  • ChangeCertificateCompartment operation to change the compartment to which an existing API Gateway certificate resource belongs.

Was this article helpful?