Using JSON Web Tokens (JWTs) to Add Authentication and Authorization to API Deployments

You can control access to APIs you deploy to API gateways using JSON Web Tokens (JWTs) as described in this topic, or using an 'authorizer function' (as described in Using Authorizer Functions to Add Authentication and Authorization to API Deployments).

A JWT is a JSON-based access token sent in an HTTP request from an API client to a resource. JWTs are issued by identity providers (for example, Oracle Identity Cloud Service (IDCS), Auth0, Okta). When an API client attempts to access a protected resource, it must include a JWT. The resource validates the JWT with an authorization server using a corresponding public verification key, either by invoking a validation end-point on the authorization server or by using a local verification key provided by the authorization server.

A JWT comprises:

  • A header, which identifies the type of token and the cryptographic algorithm used to generate the signature.
  • A payload, containing claims about the end user's identity, and the properties of the JWT itself. A claim is a key value pair, where the key is the name of the claim. A payload is recommended (although not required) to contain certain reserved claims with particular names, such as expiration time (exp), audience (aud), issuer (iss), and not before (nbf). A payload can also contain custom claims with user-defined names.
  • A signature, to validate the authenticity of the JWT (derived by base64 encoding the header and the payload).

You enable an API deployment to use JWTs for authentication and authorization by including two different kinds of request policy in the API deployment specification:

  • An authentication request policy for the entire API deployment that specifies the use of JWTs, including how to validate them and whether unauthenticated end users can access routes in the API deployment.
  • An authorization request policy for each route that specifies the operations an end user is allowed to perform, optionally based on values specified for the scope claim in the JWT.

Before an end user can access an API deployment that uses JWTs for authentication and authorization, they must obtain a JWT from an identity provider.

When calling an API deployed on an API gateway, the API client provides the JWT as a query parameter or in the header of the request. The API gateway validates the JWT using a corresponding public verification key provided by the issuing identity provider. Using the API deployment's authentication request policy, you can configure how the API gateway validates JWTs:

  • You can configure the API gateway to retrieve public verification keys from the identity provider at runtime. In this case, the identity provider acts as the authorization server.
  • You can configure the API gateway in advance with public verification keys already issued by an identity provider (referred to as 'static keys'), enabling the API gateway to verify JWTs locally at runtime without having to contact the identity provider. The result is faster token validation.

As well as using the public verification key from the issuing identity provider to verify the authenticity of a JWT, you can specify that reserved claims in the JWT's payload must have particular values before the API gateway considers the JWT to be valid. By default, API gateways validate JWTs using the expiration (exp), audience (aud), and issuer (iss) claims, along with the not before (nbf) claim if present. You can also specify acceptable values for custom claims. See Identity Provider Details to Use for iss and aud Claims, and for the JWKS URI.

When the JWT has been validated, the API gateway extracts claims from the JWT's payload as key value pairs and saves them as records in the request.auth context table for use by the API deployment.  For example, as context variables for use in an HTTP back end definition (see Adding Context Variables to Policies and HTTP Back End Definitions). If the JWT's payload contains the scope claim, you can use the claim's values in authorization request policies for individual routes to specify the operations an end user is allowed to perform.

You can add authentication and authorization request policies to an API deployment specification by:

  • Using the Console.
  • Editing a JSON file.

Prerequisites for using JWTs

Before you can enable authentication and authorization for API deployments using JWTs:

  • An identity provider (for example, Oracle Identity Cloud Service (IDCS), Auth0) must have already been set up to issue JWTs for users allowed to access the API deployment.
  • If you want to use custom claims in authorization policies, the identity provider must be set up to add the custom claims to the JWTs it issues.

See the identity provider documentation for more information (for example, the Oracle Identity Cloud Service (IDCS) documentation, the Auth0 documentation).

Also note that to validate the JWT using a corresponding public verification key provided by the issuing identity provider:

  • the signing algorithm used to generate the JWT's signature must be one of RS256, RS384, or RS512
  • the public verification key must have a minimum length of 2048 bits and must not exceed 4096 bits

Using the Console to Add Authentication and Authorization Request Policies

To add authentication and authorization request policies 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 API Gateways and API Deployments.

  2. In the API Request Policies section of the Basic Information page, click the Add button beside Authentication and specify:

    • Authentication Type: Select JWT.
    • Authentication Token: Whether the JWT is contained in a request header or a query parameter.
    • Authentication Token Value: Depending on whether the JWT is contained in a request header or a query parameter, specify:

      • Header Name: and Authentication Scheme: If the JWT is contained in a request header, enter the name of the header (for example Authorization), and the HTTP authentication scheme (only Bearer is currently supported).
      • Parameter Name: If the JWT is contained in a query parameter, enter the name of the query parameter.
    • Enable Anonymous Access: Whether unauthenticated (that is, anonymous) end users can access routes in the API deployment. By default, this option is not selected. If you never want anonymous end users to be able to access routes, don't select this option. Note that if you do select this option, you also have to explicitly specify every route to which anonymous access is allowed by selecting Anonymous as the Authorization Type in each route's authorization policy.
  3. In the Issuers section, specify values that are allowed in the issuer (iss) claim of a JWT being used to access the API deployment:

    • Allowed Issuers: Specify the URL (or a text string) for an identity provider that is allowed in the issuer (iss) claim of a JWT to be used to access the API deployment. For example, to enable a JWT issued by the Oracle Identity Cloud Service (IDCS) to be used to access the API deployment, enter https://identity.oraclecloud.com/ . See Identity Provider Details to Use for iss and aud Claims, and for the JWKS URI.
    • Another Issuer: Click to add additional identity providers (up to a maximum of five).
  4. In the Audiences section, specify values that are allowed in the audience (aud) claim of a JWT being used to access the API deployment :

  5. In the Public Keys section of the Authentication Policy window, specify how you want the API gateway to validate JWTs using public verification keys:

    • To configure the API gateway to validate JWTs by retrieving public verification keys from the identity provider at runtime, select Remote JWKS from the Type list and specify:

      • URI: The URI from which to retrieve the JSON Web Key Set (JWKS) to use to verify the signature on JWTs. For example, https://www.somejwksprovider.com/oauth2/v3/certs. For more information about the URI to specify, see Identity Provider Details to Use for iss and aud Claims, and for the JWKS URI.

        Note the following:

        • The URI must be routable from the subnet containing the API gateway on which the API is deployed.

        • URIs that require authentication or authorization to return the JWKS are not supported.
        • If the API gateway fails to retrieve the JWKS, all requests to the API deployment will return an HTTP 500 response code. Refer to the API gateway's execution log for more information about the error (see Adding Logging to API Deployments).
        • Certain key parameters must be present in the JWKS to verify the JWT's signature (see Key Parameters Required to Verify JWT Signatures).
      • Cache Duration in Hours: The number of hours (between 1 and 24) the API gateway is to cache the JWKS set after retrieving it.
      • Disable SSL Verification: Whether to disable SSL verification when communicating with the identity provider. By default, this option is not selected. Oracle recommends not selecting this option because it can compromise JWT validation. API Gateway trusts certificates from multiple Certificate Authorities issued for Oracle Identity Cloud Service (IDCS), Auth0, Okta.
    • To configure the API gateway to validate JWTs with public verification keys already issued by an identity provider (enabling the API gateway to verify JWTs locally without having to contact the identity provider), select Static Keys from the Type list and specify:

      • Key ID: The identifier of the static key used to sign the JWT. The value must match the kid claim in the JWT header. For example, master_key.
      • Format: The format of the static key, as either a JSON Web Key or a PEM-encoded Public Key.

        • JSON Web Key: If the static key is a JSON Web Key, paste the key into this field.

          For example:

          {
            "kty": "RSA",
            "n": "0vx7agoebGc...KnqDKgw",
            "e": "AQAB",
            "alg": "RS256",
            "use": "sig"
          }
          

          Note that certain parameters must be present in the static key to verify the JWT's signature (see Key Parameters Required to Verify JWT Signatures). Also note that RSA is currently the only supported key type (kty).

        • PEM-Encoded Public Key: If the static key is a PEM-encoded public key, paste the key into this field. For example:

          -----BEGIN PUBLIC KEY-----
          XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH
          -----END PUBLIC KEY-----
          

          Note that the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- markers are required.

      • Another Key: Click to add additional keys (up to a maximum of five).
  6. (Optional) Click Show Advanced Options to specify a time difference to take into account when validating JWTs, and to specify additional claims in JWTs to process:

    • Maximum Clock Skew in Seconds: (Optional) The maximum time difference between the system clocks of the identity provider that issued a JWT and the API gateway. The value you enter here is taken into account when the API gateway validates the JWT to determine whether it is still valid, using the not before (nbf) claim (if present) and the expiration (exp) claim in the JWT. The minimum (and default) is 0, the maximum is 120.
    • Verify Claims: (Optional) In addition to the values for the audience aud and issuer iss claims that you already specified, you can specify names and values for one or more additional claims to validate in a JWT. Note that any key names and values you enter are simply handled as strings, and must match exactly with names and values in the JWT. Pattern matching and other datatypes are not supported. Also note that you can specify a claim can or must appear in the JWT without specifying a value for the claim by entering the claim's name in the Claim Key field, leaving the Claim Values field blank, and selecting Required:

      • Claim Key: (Optional) Specify the name of a claim that can be, or must be, included in a JWT. If the claim must be included in the JWT, select Required. The claim name you specify can be a reserved claim name such as the subject (sub) claim, or a custom claim name issued by a particular identity provider.
      • Claim Values: (Optional) Specify an acceptable value for the claim in the Claim Key field. Click the plus sign (+) to enter another acceptable value. If you specify one or more acceptable values for the claim, the API gateway validates that the claim has one of the values you specify.
      • Required: Select if the claim in the Claim Key field must be included in the JWT.
    • Another Claim: Click to add additional claims (up to a maximum of ten).
  7. Click Save Changes, and then click Next to enter details for individual routes in the API deployment on the Routes page. To specify an authorization policy that applies to an individual route, click Show Route Request Policies, click the Add button beside Authorization, and specify:

    • Authorization Type: How to grant access to the route. Specify:

      • Any: Only grant access to end users that have been successfully authenticated, provided the JWT has a scope claim that includes at least one of the access scopes you specify in the Allowed Scope field. In this case, the authentication policy's Enable Anonymous Access option has no effect.
      • Anonymous: Grant access to all end users, even if they have not been successfully authenticated using the JWT. In this case, you must have selected the authentication policy's Enable Anonymous Access option.
      • Authentication only: Only grant access to end users that have been successfully authenticated using the JWT. In this case, the authentication policy's Enable Anonymous Access option has no effect.
    • Allowed Scope: If you selected Any as the Authorization Type, enter a comma-delimited list of one or more strings that correspond to access scopes in the JWT. Access will only be granted to end users that have been successfully authenticated if the JWT has a scope claim that includes one of the access scopes you specify. For example, read:hello
    Note

    If you don't include an authorization policy for a particular route, access is granted as if such a policy does exist and Authorization Type is set to Authentication only. In other words, regardless of the setting of the authentication policy's Enable Anonymous Access option:

    • only authenticated end users can access the route
    • all authenticated end users can access the route regardless of access scopes in the JWT's scope claim
    • anonymous end users cannot access the route
  8. Click Save Changes, and then click Next to review the details you entered for the API deployment.
  9. Click Create or Save Changes to create or update the API deployment.
  10. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).

Editing a JSON File to Add Authentication and Authorization Request Policies

To add authentication and authorization request policies 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 authentication and authorization functionality, or create a new API deployment specification (see Creating an API Deployment Specification).

    At a minimum, the API deployment specification will include a routes section containing:

    • A path. For example, /hello
    • One or more methods. For example, GET
    • A definition of a back end. For example, a URL, or the OCID of a function in Oracle Functions.

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

    {
      "routes": [
        {
          "path": "/hello",
          "methods": ["GET"],
          "backend": {
            "type": "ORACLE_FUNCTIONS_BACKEND",
            "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
          }
        }
      ]
    }
  2. Add an authentication request policy that applies to all routes in the API deployment specification:

    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 authentication policy to the new requestPolicies section.

      {
        "requestPolicies": {
          "authentication": {
            "type": "<type-value>",
            "isAnonymousAccessAllowed": <true|false>,
            "issuers": ["<issuer-url>", "<issuer-url>"],
            <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>">,
            "tokenAuthScheme": "<authentication-scheme>",
            "audiences": ["<intended-audience>"],
            "publicKeys": {
              "type": <"REMOTE_JWKS"|"STATIC_KEYS">,
              <public-key-config>
            },
            "verifyClaims": [
              {"key": "<claim-name>",
               "values": ["<acceptable-value>", "<acceptable-value>"],
               "isRequired": <true|false>
              }
            ],
            "maxClockSkewInSeconds": <seconds-difference>
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }

      where:

      • <type-value> is the authentication type. To use JWTs for authentication, specify JWT_AUTHENTICATION.
      • "isAnonymousAccessAllowed": <true|false> optionally indicates whether unauthenticated (that is, anonymous) end users can access routes in the API deployment specification. If you never want anonymous end users to be able to access routes, set this property to false. If you don't include this property in the authentication policy, the default of false is used. Note that if you do include this property and set it to true, you also have to explicitly specify every route to which anonymous access is allowed by setting the type property to "ANONYMOUS" in each route's authorization policy.
      • <issuer-url> is the URL (or a text string) for an identity provider that is allowed in the issuer (iss) claim of a JWT to be used to access the API deployment. For example, to enable a JWT issued by the Oracle Identity Cloud Service (IDCS) to be used to access the API deployment, enter https://identity.oraclecloud.com/ . You can specify one or multiple identity providers (up to a maximum of five). See Identity Provider Details to Use for iss and aud Claims, and for the JWKS URI.
      • <"tokenHeader"|"tokenQueryParam">: <"<token-header-name>"|"<token-query-param-name>"> indicates whether it is a request header that contains the JWT (and if so, the name of the header), or a query parameter that contains the access token (and if so, the name of the query parameter). Note that you can specify either "tokenHeader": "<token-header-name>" or "tokenQueryParam": "<token-query-param-name>">, but not both.
      • <tokenAuthScheme> is the name of the authentication scheme to use if the JWT is contained in a request header. For example, "Bearer".
      • <intended-audience> is a value that is allowed in the audience (aud) claim of a JWT to identify the intended recipient of the token. For example, the audience could be, but need not be, the API gateway's hostname. You can specify one audience or multiple audiences (up to a maximum of five). See Identity Provider Details to Use for iss and aud Claims, and for the JWKS URI.
      • "type": <"REMOTE_JWKS"|"STATIC_KEYS"> indicates how you want the API gateway to validate JWTs using public verification keys. Specify REMOTE_JWKS to configure the API gateway to retrieve public verification keys from the identity provider at runtime. Specify STATIC_KEYS to configure the API gateway with public verification keys already issued by an identity provider (enabling the API gateway to verify JWTs locally without having to contact the identity provider).
      • <public-key-config> provides the details of JWT validation, according to whether you specified "REMOTE_JWKS" or "STATIC_KEYS" as the value of "type": as follows:

        • If you specified "type": "REMOTE_JWKS" to configure the API gateway to validate JWTs by retrieving public verification keys from the identity provider at runtime, provide details as follows:

                "publicKeys": {
                  "type": "REMOTE_JWKS",
                  "uri": "<uri-for-jwks>",
                  "maxCacheDurationInHours": <cache-time>,
                  "isSslVerifyDisabled": <true|false>
                }
          

          where:

          • "uri": "<uri-for-jwks>" specifies the URI from which to retrieve the JSON Web Key Set (JWKS) to use to verify the signature on JWTs. For more information about the URI to specify, see Identity Provider Details to Use for iss and aud Claims, and for the JWKS URI. Note the following:
            • The URI must be routable from the subnet containing the API gateway on which the API is deployed.
            • URIs that require authentication or authorization to return the JWKS are not supported.
            • If the API gateway fails to retrieve the JWKS, all requests to the API deployment will return an HTTP 500 response code. Refer to the API gateway's execution log for more information about the error (see Adding Logging to API Deployments).
            • Certain key parameters must be present in the JWKS to verify the JWT's signature (see Key Parameters Required to Verify JWT Signatures).
          • "maxCacheDurationInHours": <cache-time> specifies the number of hours (between 1 and 24) the API gateway is to cache the JWKS set after retrieving it.
          • "isSslVerifyDisabled": <true|false> indicates whether to disable SSL verification when communicating with the identity provider. Oracle recommends not setting this option to truebecause it can compromise JWT validation. API Gateway trusts certificates from multiple Certificate Authorities issued for Oracle Identity Cloud Service (IDCS), Auth0, and Okta.

          For example:

                "publicKeys": {
                  "type": "REMOTE_JWKS",
                  "uri": "https://www.somejwksprovider.com/oauth2/v3/certs",
                  "maxCacheDurationInHours": 3,
                  "isSslVerifyDisabled": false
                }
          
        • If you specified "type": "STATIC_KEYS", the details to provide depend on the format of the key already issued by the identity provider:

          • If the static key is a JSON Web Key, specify "format": "JSON_WEB_KEY", specify the identifier of the static key used to sign the JWT as the value of the "kid" parameter, and provide values for other parameters to verify the JWT's signature.

            For example:

                            
                  "publicKeys": {
                    "type": "STATIC_KEYS",
                    "keys": [
                      {
                        "format": "JSON_WEB_KEY",
                        "kid": "master_key",
                        "kty": "RSA",
                        "n": "0vx7agoebGc...KnqDKgw",
                        "e": "AQAB",
                        "alg": "RS256",
                        "use": "sig"
                      }
                    ]

            Note that certain parameters must be present in the static key to verify the JWT's signature (see Key Parameters Required to Verify JWT Signatures). Also note that RSA is currently the only supported key type (kty).

          • If the static key is a PEM-encoded public key, specify "format": "PEM", specify the identifier of the static key used to sign the JWT as the value of "kid", and provide the key as the value of "key".

            For example:

                            
                  "publicKeys": {
                    "type": "STATIC_KEYS",
                    "keys": [
                      {
                        "format": "PEM",
                        "kid": "master_key"
                        "key": -----BEGIN PUBLIC KEY-----XsEiCeYgglwW/KAhSSNRVdD60QlXYMWHOhXzSFDZCLf1WXxKMZCiMvVrsBIzmFEXnFmcsO2mxwlL5/8qQudomoP+yycJ2gWPIgqsZcQRheJWxVC5ep0MeEHlvLnEvCi9utpAnjrsZCQ7plfZVPX7XORvezwqQhBfYzwA27M2FgOOs8DOIYfqQ1Ki3DMqEppFnjLcjgQtknbTlT7YgG6tzobwig8M2KIrPjJ0BmbJAFH-----END PUBLIC KEY-----
                      }
                    ]

            Note that the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- markers are required.

      • verifyClaims optionally specifies additional claim names and values for one or more additional claims to validate in a JWT (up to a maximum of ten).
        • "key": "<claim-name>" is the name of a claim that can be, or must be, included in a JWT. The claim name you specify can be a reserved claim name such as the subject (sub) claim, or a custom claim name issued by a particular identity provider.
        • "values": ["<acceptable-value>", "<acceptable-value>"] (optionally) indicates one or more acceptable values for the claim.
        • "isRequired": <true|false> indicates whether the claim must be included in the JWT.

        Note that any key names and values you enter are simply handled as strings, and must match exactly with names and values in the JWT. Pattern matching and other datatypes are not supported

      • maxClockSkewInSeconds: <seconds-difference> optionally specifies the maximum time difference between the system clocks of the identity provider that issued a JWT and the API gateway. The value you specify is taken into account when the API gateway validates the JWT to determine whether it is still valid, using the not before (nbf) claim (if present) and the expiration (exp) claim in the JWT. The minimum (and default) is 0, the maximum is 120.

      For example, the following authentication policy specifies an OCI function that will validate the access token in the Authorization request header:

      {
        "requestPolicies": {
          "authentication": {
            "type": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "issuers": ["https://identity.oraclecloud.com/"],
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "audiences": ["api.dev.io"],
            "publicKeys": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ]
            },
            "verifyClaims": [
              {
                "key": "is_admin",
                "values": ["service:app", "read:hello"],
                "isRequired": true
              }
            ],
            "maxClockSkewInSeconds": 10
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }
  3. Add an authorization request policy for each route in the API deployment specification:

    1. Insert a requestPolicies section after the first route's backend section, if one doesn't exist already. For example:

      {
        "requestPolicies": {
          "authentication": {
            "type": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "issuers": ["https://identity.oraclecloud.com/"],
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "audiences": ["api.dev.io"],
            "publicKeys": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ]
            },
            "verifyClaims": [
              {
                "key": "is_admin",
                "values": ["service:app", "read:hello"],
                "isRequired": true
              }
            ],
            "maxClockSkewInSeconds": 10
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
               "type": "ORACLE_FUNCTIONS_BACKEND",
               "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {}
          }
        ]
      }
    2. Add the following authorization policy to the requestPolicies section:

      {
        "requestPolicies": {
          "authentication": {
            "type": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "issuers": ["https://identity.oraclecloud.com/"],
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "audiences": ["api.dev.io"],
            "publicKeys": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ]
            },
            "verifyClaims": [
              {
                "key": "is_admin",
                "values": ["service:app", "read:hello"],
                "isRequired": true
              }
            ],
            "maxClockSkewInSeconds": 10
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "authorization": {
                "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS">, 
                "allowedScope": [ "<scope>" ]
              }
            }
          }
        ]
      }

      where:

      • "type": <"AUTHENTICATION_ONLY"|"ANY_OF"|"ANONYMOUS"> indicates how to grant access to the route:

        • "AUTHENTICATION_ONLY": Only grant access to end users that have been successfully authenticated. In this case, the "isAnonymousAccessAllowed" property in the API deployment specification's authentication policy has no effect.
        • "ANY_OF": Only grant access to end users that have been successfully authenticated, provided the JWT's scope claim includes one of the access scopes you specify in the allowedScope property. In this case, the "isAnonymousAccessAllowed" property in the API deployment specification's authentication policy has no effect.
        • "ANONYMOUS": Grant access to all end users, even if they have not been successfully authenticated. In this case, you must explicitly set the "isAnonymousAccessAllowed" property to true in the API deployment specification's authentication policy.
      • "allowedScope": [ "<scope>" ] is a comma-delimited list of one or more strings that correspond to access scopes included in the JWT's scope claim. In this case, you must set the type property to "ANY_OF" (the "allowedScope" property is ignored if the type property is set to "AUTHENTICATION_ONLY" or "ANONYMOUS"). Also note that if you specify more than one scope, access to the route is granted if any of the scopes you specify is included in the JWT's scope claim.

      For example, the following request policy defines a /hello route that only allows authenticated end users with the read:hello scope to access it:

      {
        "requestPolicies": {
          "authentication": {
            "type": "JWT_AUTHENTICATION",
            "isAnonymousAccessAllowed": false,
            "issuers": ["https://identity.oraclecloud.com/"],
            "tokenHeader": "Authorization",
            "tokenAuthScheme": "Bearer",
            "audiences": ["api.dev.io"],
            "publicKeys": {
              "type": "STATIC_KEYS",
              "keys": [
                {
                  "format": "JSON_WEB_KEY",
                  "kid": "master_key",
                  "kty": "RSA",
                  "n": "0vx7agoebGc...KnqDKgw",
                  "e": "AQAB",
                  "alg": "RS256",
                  "use": "sig"
                }
              ]
            },
            "verifyClaims": [
              {
                "key": "is_admin",
                "values": ["service:app", "read:hello"],
                "isRequired": true
              }
            ],
            "maxClockSkewInSeconds": 10
          }
        },
        "routes": [
          {
            "path": "/hello",
            "methods": ["GET"],
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            },
            "requestPolicies": {
              "authorization": {
                "type": "ANY_OF",
                "allowedScope": [ "read:hello" ]
              }
            }
          }
        ]
      }
    3. Add an authorization request policy for all remaining routes in the API deployment specification.
    Note

    If you don't include an authorization policy for a particular route, access is granted as if such a policy does exist and the type property is set to "AUTHENTICATION_ONLY". In other words, regardless of the setting of the isAnonymousAccessAllowed property in the API deployment specification's authentication policy:

    • only authenticated end users can access the route
    • all authenticated end users can access the route regardless of access scopes in the JWT's scope claim
    • anonymous end users cannot access the route
  4. Save the JSON file containing the API deployment specification.
  5. 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 API Gateways and API Deployments.

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

Identity Provider Details to Use for iss and aud Claims, and for the JWKS URI

The identity provider that issued the JWT determines the allowed values you have to specify for the issuer (iss) and the audience (aud) claims in the JWT. Which identity provider issued the JWT also determines the URI from which to retrieve the JSON Web Key Set (JWKS) to verify the signature on the JWT. Note that URIs that require authentication or authorization to return the JWKS are not supported.

Use the following table to find out what to specify for JWTs issued by the Oracle Identity Cloud Service (IDCS), Okta, and Auth0 identity providers.

Identity Provider

Issuer (iss) claim

Audience (aud) claim

Format of URI from which to retrieve the JWKS

IDCS https://identity.oraclecloud.com/

Customer-specific.

See Validating Access Tokens in the Oracle Identity Cloud Service documentation.

https://<tenant-base-url>/admin/v1/SigningCert/jwk

To obtain the JWKS without logging in to Oracle Identity Cloud Service, see Change Default Settings in the Oracle Identity Cloud Service documentation.

Okta https://<your-okta-tenant-name>.com

Customer-specific.

The audience configured for the Authorization Server in the Okta Developer Console. See Additional validation for access tokens in the Okta documentation.

https://<your-okta-tenant-name>.com/oauth2/<auth-server-id> /v1/keys

See the Okta documentation.

Auth0 https://<your-account-name>.auth0.com/

Customer-specific.

See Audience in the Auth0 documentation.

https://<your-account-name>.auth0.com/.well-known/jwks.json

Key Parameters Required to Verify JWT Signatures

To verify the signature on a JWT, API gateways require the following key parameters are present in either the JWKS returned from a URI or the static JSON Web Key you specify.

Key Parameter Notes
kid The identifier of the key used to sign the JWT. The value must match the kid claim in the JWT header. For example, master_key.
kty The type of the key used to sign the JWT. Note that RSA is currently the only supported key type.
use or key_ops

If the use parameter is present, then it must be set to sig. If the key-ops parameter is present, then verify must be one of the valid values.

n The public key modulus.
e The public key exponent.
alg The signing algorithm (if present) must be set to one of RS256, RS384 or RS512.