Skip to content

Provision certificates to Oracle Cloud API Gateway

Provision a certificate from Certificate Manager - SaaS to an API gateway in Oracle Cloud API Gateway. API Gateway certificates can't be changed after they're created, so every provisioning creates a new certificate resource in Oracle Cloud Infrastructure (OCI) and switches the API gateway to it.

Warning

After Certificate Manager - SaaS switches an API gateway to the new certificate, it deletes the certificate the gateway served before, if no other API gateway in the compartment uses it. On an API gateway's first renewal, that's usually the certificate you uploaded before you used Certificate Manager - SaaS.

Before you begin

  • An Oracle Cloud API Gateway machine that you created and whose status is Verified.
  • The certificate to provision in the Certificate Manager - SaaS inventory, with its private key.
  • The System Administrator or PKI Administrator role, or the Resource Owner role and membership in the machine's owning team.
  • A certificate with an RSA key of 2048 to 4096 bits and its full issuing chain, that hasn't expired. API Gateway doesn't accept other key types.
  • A certificate that covers every DNS name and IP address of the certificate that the API gateway serves now. Certificate Manager - SaaS refuses a certificate that would drop a name, because the switch would break Transport Layer Security (TLS) for clients that use it. A wildcard name such as *.example.com covers api.example.com, but not example.com or v1.api.example.com. If the current certificate has a wildcard name, the new certificate needs the same wildcard name.
  • An API gateway in the machine's compartment that already serves a custom certificate, not Oracle's default certificate.
  • An API gateway without a FULL resource lock, that hasn't failed and isn't being created or deleted. If it's being updated, Certificate Manager - SaaS waits for the update to finish.
  • A free API Gateway certificate slot in the region. Certificate Manager - SaaS creates the new certificate before it deletes the old one. OCI limits the number of API Gateway certificates in each region, and a compartment quota can lower the limit. The default limit depends on your OCI payment method and can be low. If the region is at its limit, ask Oracle to raise it before you provision.

To provision a certificate to Oracle Cloud API Gateway

  1. Sign in to Certificate Manager - SaaS.
  2. Click Installations > Machines.
  3. Click the more options button at the end of the machine's row, and then select Provision.
  4. In Search a certificate by name, expiration or fingerprint, enter part of the certificate's name, expiration date, or fingerprint, and then select the certificate from the results. Confirm that it's the right certificate by checking Subject DN, Validity, and Certificate SHA1 Fingerprint.

    The rest of the Provision a certificate dialog appears after you select a certificate.

  5. (Optional) Under Certificate Information, in Certificate Name, enter a display name for the certificate resource in Oracle Cloud. If you leave it empty, Certificate Manager - SaaS derives a name from the certificate, for example venafi-api.example.com-2027-01-15-0123abcd.

    Certificate OCID is read-only. Certificate Manager - SaaS fills it in with the OCID of the certificate resource it creates.

  6. Under Installation Endpoint, in API Gateway OCID, replace (unbound) with the OCID of the API gateway that serves the certificate.

    Note

    To install the certificate in Oracle Cloud without attaching it to an API gateway, keep (unbound). No API gateway changes, and nothing is deleted. The certificate still uses a certificate slot. Each renewal of an (unbound) installation adds another unattached certificate and deletes none, so the certificates build up. Delete the ones you don't need in the Oracle Cloud Console.

    API Gateway Name is read-only. It's empty until the machine's next discovery fills it in with the API gateway's display name. Discovery also updates it when the API gateway is renamed in Oracle Cloud.

  7. (Optional) To save the installation without pushing the certificate now, disable Push certificate on save.

  8. Click Save. To save and then provision another certificate, click Save & New.

After you save, Certificate Manager - SaaS uploads the certificate, its chain, and its private key to Oracle Cloud as a new API Gateway certificate, and waits until it's active. It then switches the API gateway to the new certificate and waits until OCI confirms that the API gateway is active again. Only then does it delete the certificate that the API gateway served before. An installation appears on the machine's Installations tab. To provision on a schedule instead of right away, set up a machine provisioning schedule.

The installation's Certificate OCID is the OCID of the new certificate resource. Every renewal creates a new certificate resource, so the OCID changes each time.

Important

Add only one installation for each API gateway. Two installations on the same API gateway would each switch it to their own certificate, and one installation's cleanup could delete the other's certificate.

Note

  • If the switch fails or doesn't finish within the time limit, Certificate Manager - SaaS deletes nothing. Provisioning again is safe. It reuses the certificate resource that the earlier attempt created, then finishes or confirms the switch. After a timeout, OCI can still complete the switch on its own, and the API gateway then serves the new certificate. Both certificates are valid.
  • If the API gateway goes into a failed state in Oracle Cloud during the switch, it might serve neither certificate. Certificate Manager - SaaS deletes nothing. Fix the API gateway in the Oracle Cloud Console, and then provision again.
  • Certificate Manager - SaaS doesn't delete the replaced certificate while another API gateway in the compartment uses it, or if the certificate is locked or in another compartment. When a certificate shared by several API gateways is renewed, provisioning to the last of them deletes it. A replaced certificate that stays in the machine's compartment and that no active or updating API gateway uses is discovered with the API Gateway OCID (unbound). Delete the ones you don't need in the Oracle Cloud Console. Nothing retries the cleanup.
  • If the region's certificate limit is reached, provisioning fails. Raise the API Gateway certificate limit or the compartment quota, or delete unused certificates. Certificate Manager - SaaS never deletes a certificate in use to make room.