Create an Oracle Cloud API Gateway machine¶
Create an Oracle Cloud API Gateway machine so Certificate Manager - SaaS can discover and provision the TLS certificates that the API gateways in one Oracle Cloud Infrastructure (OCI) compartment serve on their custom domains. Certificate Manager - SaaS connects to the OCI API Gateway API directly and signs each request with an OCI API signing key.
Before you begin¶
- The System Administrator, PKI Administrator, or Resource Owner role. If you have the Resource Owner role, you must own or belong to at least one team.
- An OCI user for Certificate Manager - SaaS, with an API signing key. The key is an RSA key pair in PEM format, at least 2048 bits, whose public key is uploaded to the user. To set them up, see To prepare Oracle Cloud.
- An Identity and Access Management (IAM) policy that gives the user's group access to API gateways, API Gateway certificates, and API Gateway work requests in the compartment you want to manage.
- The Oracle Cloud identifiers (OCIDs) of your tenancy, the user, and the compartment, and the fingerprint of the API signing key.
- The identifier of the region the API gateways run in, for example
us-ashburn-1.
Note
- Each machine covers one compartment in one region. Child compartments aren't included, even when you enter the tenancy (root) compartment. To manage API gateways in other compartments or regions, create one machine for each.
- Certificate Manager - SaaS manages only API gateways that serve a custom certificate. API gateways that use Oracle's default certificate aren't discovered and can't be provisioned.
- Certificates managed by the OCI Certificates service aren't discovered and are never replaced.
- Certificate Manager - SaaS connects to Oracle Cloud directly, so an Oracle Cloud API Gateway machine doesn't need a VSatellite.
To prepare Oracle Cloud¶
Use a dedicated user and group for Certificate Manager - SaaS, and grant them access only to the compartment the machine manages.
- In the Oracle Cloud Console, select Identity & Security > Users, and create a user only for Certificate Manager - SaaS. Don't reuse a person's account or an administrator account.
-
Generate an RSA key pair in PEM format, for example:
openssl genrsa -out oci_api_key.pem 2048 openssl rsa -in oci_api_key.pem -pubout -out oci_api_key_public.pemKeys created with
ssh-keygen(OpenSSH format) aren't supported. If you encrypt the private key with a passphrase, you enter the passphrase when you create the machine. -
On the user's page, select API Keys > Add API Key, and upload the public key. Copy the fingerprint that the Console shows.
- Create a group that contains only this user.
-
Create a policy for the compartment the machine manages. Replace
<group>and<compartment>with your own values.-
For discovery and provisioning:
Allow group <group> to manage api-gateways in compartment <compartment> Allow group <group> to manage api-certificates in compartment <compartment> Allow group <group> to read api-workrequests in compartment <compartment> -
For discovery only:
Allow group <group> to read api-gateways in compartment <compartment> Allow group <group> to read api-certificates in compartment <compartment>
Note
manage api-gatewaysis the only permission that allows Certificate Manager - SaaS to switch an API gateway's certificate. It also allows the user to delete API gateways and move them to another compartment. Together withmanage api-certificates, it also allows the user to create API gateways. Keep the group limited to this one user.read api-workrequestsis required separately. Themanagepermissions don't include it, and Certificate Manager - SaaS follows every change it makes through an OCI work request.- A policy on a compartment also covers its child compartments. Certificate Manager - SaaS never changes API gateways or certificates outside the machine's compartment, but for a credential limited to a single compartment, choose a compartment without child compartments. For the root compartment, write
in tenancyinstead ofin compartment <compartment>. - No permission on the OCI Certificates service is required.
-
To create an Oracle Cloud API Gateway machine¶
- Sign in to Certificate Manager - SaaS.
- Click Installations > Machines.
- Click New, and then select Oracle Cloud API Gateway.
- On the Properties step, in Name, enter a name for the machine.
- For Owning Team, choose the team that owns the machine. System Administrators and PKI Administrators can choose any team. Resource Owners can choose only a team they own or belong to.
- In Tenancy OCID, enter the OCID of your tenancy. It starts with
ocid1.tenancy.and is shown under Tenancy Information in the Oracle Cloud Console. - In User OCID, enter the OCID of the user that owns the API signing key. It starts with
ocid1.user.. - In API Key Fingerprint, enter the fingerprint of the API signing key's public key, as shown under the user's API keys in the Oracle Cloud Console.
-
In API Signing Private Key, paste the whole RSA private key in PEM format, from its
BEGINline to itsENDline.Note
Certificate Manager - SaaS encrypts the credentials you enter and doesn't display them again. On the machine's Properties tab, they appear masked. To keep a stored credential when you edit the machine, leave its masked value unchanged. Keep your own secure record of the credentials in case you need them again.
-
(Optional) In API Signing Key Passphrase, enter the passphrase of the private key. Leave it empty for an unencrypted key.
-
In Region, enter the region identifier, for example
us-ashburn-1. Use the full identifier, not its short code (such asiad). The field accepts only lowercase letters, digits, and hyphens.Note
Dedicated regions that aren't in the OCI SDK's region list aren't supported.
-
In Compartment OCID, enter the OCID of the compartment to manage. For the root compartment, enter the tenancy OCID.
-
Click Test Access. After the connection succeeds, click Continue. The Discovery step opens.
Note
The test checks the credentials, the region, and access to the compartment's API gateways. It passes for a compartment that has no API gateways, and it doesn't check the certificate or work request permissions. A missing permission shows up during the first discovery or provisioning.
-
(Optional) To skip certificates that have already expired, enable Exclude Expired Certificates.
Discovery covers the machine's compartment only, not its child compartments. It reports each API Gateway certificate once, with one installation for each API gateway that serves it. A certificate from another compartment is also reported when an API gateway in the machine's compartment serves it. A certificate that no active or updating API gateway uses gets one installation, with the API Gateway OCID
(unbound), for example a certificate that only a failed API gateway uses.Discovery skips API gateways that use Oracle's default certificate, and API gateways that are being created, are being deleted, or have failed. It also skips certificates managed by the OCI Certificates service and certificates the machine's credential can't read. The connector log records each skipped certificate.
-
(Optional) To discover certificates on a schedule, enable Schedule. For Repeat every, choose Day, Week, or Month, and then in At, enter the time. For Week, select the days of the week. For Month, enter the days in Day of month. Times are in Coordinated Universal Time (UTC).
- Click Continue. The Provisioning step opens.
-
(Optional) To provision certificates on a schedule, enable Schedule. For Repeat every, choose Day, Week, or Month, and then in At, enter the time. For Week, select the days of the week. For Month, enter the days in Day of month. Times are in Coordinated Universal Time (UTC).
Scheduled provisioning pushes only certificates that are queued for deployment, such as renewed certificates, so renewals install during the window you choose.
-
Click Finish.
What's next?¶
After you create the machine, provision a certificate to it. You can also run discovery on the machine at any time to track the certificates your API gateways serve.