Adding mTLS support to API Deployments

To add an mTLS request policy to an API deployment specification using the Console:

1. Create or update an API deployment using the Console, select the From Scratch option, and enter details on the Basic Information page.

   For more information, see Deploying an API on an API Gateway by Creating an API Deployment and Updating an API Gateway or an API Deployment.

2. In the API Request Policies section of the Basic Information page, under Mutual-TLS, select the Enable mTLs option and optionally specify:

   • Subject Alternative Name (SAN) / Common Name: Values that must appear in one or more of the following fields of the certificate presented by the API client for the API gateway to accept requests from the client:
     • Email Address
     • URL
     • Domain Name

     For example, example.com. You can specify up to 10 values. If you specify values when setting up mTLS for an API deployment, the API gateway will reject requests from API clients presenting certificates that do not contain them. If you don't specify values when setting up mTLS, the API gateway will accept all requests from API clients providing the certificate is valid.

3. Click Review to review the details you entered for the API deployment.
4. Click Create or Save Changes to create or update the API deployment.
5. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).

To add an mTLS request policy to an API deployment specification in a JSON file:

1. Using your preferred JSON editor, edit the existing API deployment specification to which you want to add mTLS support, or create a new API deployment specification (see Creating an API Deployment Specification).

   For example, the following basic API deployment specification defines a simple Hello World serverless function in OCI Functions as a single back end:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

2. To specify an mTLS request policy that applies globally to all the routes in an API deployment:

   1. Insert a requestPolicies section before the routes section, if one doesn't exist already. For example:

      {
        "requestPolicies": {},
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

   2. Add the following mutualTLS policy to the new requestPolicies section to apply globally to all the routes in an API deployment:

      {
        "requestPolicies": {
          "mutualTls":{
            "isVerifiedCertificateRequired": true|false,
            "allowedSans": [<list-of-values>]
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

      where:

      • "isVerifiedCertificateRequired": true|false, is either true or false, indicating whether mTLS is enabled for the API deployment. If not specified, the default is false.
      • "allowedSans": [<list-of-values>] is an optional comma-separated list of values that must appear in one or more of the following fields of the certificate presented by the API client for the API gateway to accept requests from the client:
        • Email Address
        • URL
        • Domain Name

        For example, example.com. You can specify up to 10 values. If you specify values when setting up mTLS for an API deployment, the API gateway will reject requests from API clients presenting certificates that do not contain them. If you don't specify values when setting up mTLS, the API gateway will accept all requests from API clients providing the certificate is valid.

      For example:

      {
        "requestPolicies": {
          "mutualTls":{
            "isVerifiedCertificateRequired": true,
            "allowedSans": [
              "example.com",
              "example.co.uk"
            ]
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

3. Save the JSON file containing the API deployment specification.

4. Use the API deployment specification when you create or update an API deployment in the following ways:

   • by specifying the JSON file in the Console when you select the Upload an existing API option
   • by specifying the JSON file in a request to the API Gateway REST API

   For more information, see Deploying an API on an API Gateway by Creating an API Deployment and Updating an API Gateway or an API Deployment.

5. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).