Customizing Trust Stores for TLS Certificate Verification
Find out how to add Certificate Authorities (CAs) and CA bundles to custom trust stores with API Gateway.
The API gateways you create with the API Gateway service verify TLS certificates presented to them using a trust store. The trust store can contain Certificate Authority (CA) root certificates, and CA bundles of root and intermediate certificates. A default CA bundle is added to each API gateway's trust store, containing certificates of well-known public CAs. The default CA bundle enables the API gateway to verify TLS certificates presented by back-end services.
In addition to the default CA bundle, you can choose to add the root certificates of other CAs, and other CA bundles, to an API gateway's trust store. These additional CAs and CA bundles are referred to as custom CAs and custom CA bundles. To add a custom CA or CA bundle to an API gateway's trust store, you have to first create a CA resource or CA bundle resource in the Certificates service. Having created the resource in the Certificates service, you can then add it to the API gateway's trust store. Adding custom CAs and CA bundles enables you to customize the trust store to meet your requirements.
Having added custom CAs and CA bundles to the trust store, TLS connections to the API gateway (including from HTTPS back ends, and from the response cache) are verified using both the default CA bundle, and the custom CAs and CA bundles. In addition, if you have specified mTLS support for an API deployment, the API gateway uses custom CAs and custom CA bundles to verify API client certificates. Note that the API gateway does not use the default CA bundle to verify API client certificates during an mTLS handshake. So if you want an API gateway to support mTLS, you must add custom CAs and CA bundles to the API gateway's trust store
For some customers, it's obligatory for security reasons to use custom trust stores that contain only private CAs, and no public CAs. For other customers, use of custom trust stores is likely to be driven by commercial requirements.
Adding Custom CAs and CA Bundles to an API Gateway's Trust Store
To customize an API gateway's trust store by adding a custom Certificate Authority (CA) or CA bundle, first create a Certificate Authority (CA) resource or CA bundle resource in the Certificates service, and then add it to the API gateway's trust store.
Removing Custom CAs and CA Bundles from an API Gateway's Trust Store
Having added a custom Certificate Authority (CA) or CA bundle to an API gateway's trust store, you might decide that the CA or CA bundle is no longer required.
You can remove some or all custom CAs and CA bundles from an API gateway's trust store, provided there are no mTLS-enabled APIs deployed on the API gateway. If there are one or more mTLS-enabled APIs deployed on the API gateway, there must always be at least one custom CA or CA bundle in the API gateway's trust store.
Using the Console
To remove a custom CA or CA bundle from an API gateway's trust store using the Console:
- In the Console, open the navigation menu and click Developer Services. Under API Management, click Gateways.
- Choose a Compartment you have permission to work in.
- On the Gateways page, click the name of the API gateway from which you want to remove the custom CA or CA bundle, to show the Gateway Details page.
-
On the Gateway Details page, select Certificate Authorities from the Resources list to see the custom CA and CA bundles in the API gateway's trust store.
-
Click the
beside the custom CA or CA bundle you want to remove, and select Remove.Note that you cannot remove all custom CAs and CA bundles from an API gateway's trust store if there are one or more mTLS-enabled APIs deployed on the API gateway.
-
Confirm that you want to remove the custom CA or CA bundle from the API gateway's trust store.
Using the CLI
To remove a custom CA or CA bundle from an API gateway's trust store using the CLI:
- Configure your client environment to use the CLI (Configuring Your Client Environment to use the CLI for API Gateway Development).
-
To remove a custom CA or CA bundle from an API gateway's trust store:
-
Open a command prompt and run
oci api-gateway gateway update
to remove the custom CA or CA bundle from the API gateway's trust store:oci api-gateway gateway update --gateway-id <gateway-ocid> --ca-bundles file:///<filename>
where
<filename>
is the name of a file containing details of just those custom CAs and custom CA bundles to retain in the API gateway's trust store (in addition to the default CA bundle). Any CAs or CA bundles not contained in the file are removed from the trust store.For example:
oci api-gateway gateway update --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --ca-bundles file:///bundles-to-keep.json
Note that you cannot remove all custom CAs and CA bundles from an API gateway's trust store if there are one or more mTLS-enabled APIs deployed on the API gateway.
The response to the command includes:
- The lifecycle state (for example, DELETED, FAILED).
- The id of the work request to remove the custom CAs or CA bundles (details of work requests are available for seven days after completion, cancellation, or failure).
If you want the command to wait to return control until the custom CAs or CA bundles have been removed (or the request has failed), include either or both the following parameters:
--wait-for-state DELETED
--wait-for-state FAILED
For example:
oci api-gateway gateway update --gateway-id ocid1.apigateway.oc1..aaaaaaaab______hga --ca-bundles file:///bundles-to-keep.json --wait-for-state DELETED
-
(Optional) To see the status of the work request that is removing the custom CA or CA bundle, enter:
oci api-gateway work-request get --work-request-id <work-request-ocid>
-
(Optional) To view the logs of the work request that is removing the custom CA or CA bundle, enter:
oci api-gateway work-request-log list --work-request-id <work-request-ocid>
-
(Optional) If the work request that is removing the custom CA or CA bundle fails and you want to review the error logs, enter:
oci api-gateway work-request-error --work-request-id <work-request-ocid>
-
(Optional) To verify that the custom CA or CA bundle has been removed from the API gateway's trust store, enter the following command and confirm that the custom CA or CA bundle is no longer shown:
oci api-gateway gateway get --gateway-id <gateway-ocid>
-
For more information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see CLI Help.
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 UpdateGateway operation to specify just those custom CAs and custom CA bundles to retain in the API gateway's trust store (in addition to the default CA bundle). Any CAs or CA bundles you don't specify are removed from the trust store. Note that you cannot remove all custom CAs and CA bundles from an API gateway's trust store if there are one or more mTLS-enabled APIs deployed on the API gateway.