Adding Login as an API Gateway Back End

To add login back ends to an API deployment specification using the Console:

1. Create or update an API deployment using the Console, select the Create deployment 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.

2. On the Authentication page, specify authentication options:

   1. Configure a token authentication request policy and select OAuth 2.0 introspection endpoint from the Validation Type list.
   2. Configure a validation failure policy and select OAuth2.0 redirect client to identity provider.
   3. For Login path, specify a static login redirect path, such as /auth/callback.

      The static login redirect path must be relative to the deployment path prefix. For example, if the deployment path prefix is /apex and the static login redirect path is /auth/callback, the full callback path is /apex/auth/callback.

   For more information about authentication options, see Adding Authentication and Authorization to API Deployments and Validating Tokens to Add Authentication and Authorization to API Deployments.

3. On the Routes page, create a new route and specify:

   • Path: The static login redirect path that you specified in the OAuth 2.0 validation failure policy. Note that the route path you specify:

     • is relative to the deployment path prefix
     • must be preceded by a forward slash (/)
     • can contain multiple forward slashes, provided they are not adjacent
     • can include alphanumeric uppercase and lowercase characters
     • can include the special characters $ - _ . + ! ' ( ) , % ; : @ & =
     • must not include path parameters or wildcards

     Note that the rules for login back end route paths are different from the rules for logout back end route paths.

   • Methods: One or more methods accepted by the back end. In the case of login back ends, only GET is accepted.

   • Add a single backend or Add multiple backends: Whether to route all requests to the same back end, or to route requests to different back ends.

     These instructions assume you want to use a single back end, so select Add a single backend. Alternatively, if you want to use different back ends, select Add multiple backends.

   • Backend Type: The type of the back-end service as Login.

4. Select Create to create the route.

5. Select Next to review the details you entered for the API deployment.

6. Select Create or Update to create or update the API deployment.

7. Configure the identity provider to include the full callback URL as a valid redirect URL.

   The full callback URL includes the API gateway hostname, deployment path prefix, and static login redirect path. For example:

   https://<gateway-hostname>/<deployment-path-prefix>/auth/callback

   Note that if the deployment path prefix is simply / and the static login redirect path is /auth/callback, the full callback URL is https://<gateway-hostname>/auth/callback (and not https://<gateway-hostname>//auth/callback).

8. Optionally, confirm the API has been deployed successfully by calling it.

To add login back ends 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 a login back end, or create a new API deployment specification.

   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. In the routes section, include a new section for a login back end:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       },
       {
         "path": "<login-route-path>",
         "methods": ["<method-list>"],
         "backend": {
           "type": "OAUTH2_LOGIN_BACKEND"
         }
       }
     ]
   }

   where:

   • <login-route-path> specifies the path for redirects from the identity provider to the login back end. The path must match the static login redirect path configured in the OAuth 2.0 validation failure policy. Note that the route path you specify:

     • is relative to the deployment path prefix
     • must be preceded by a forward slash (/)
     • can contain multiple forward slashes, provided they are not adjacent
     • can include alphanumeric uppercase and lowercase characters
     • can include the special characters $ - _ . + ! ' ( ) , % ; : @ & =
     • must not include path parameters or wildcards

     Note that the rules for login back end route paths are different from the rules for logout back end route paths.

   • <method-list> specifies one or more methods accepted by the login back end, separated by commas. In the case of login back ends, only GET is accepted.

   • "type": "OAUTH2_LOGIN_BACKEND" specifies that the back end is a login back end.

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 deployment 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.

5. Configure the identity provider to include the full callback URL as a valid redirect URL.

   The full callback URL includes the API gateway hostname, deployment path prefix, and static login redirect path. For example:

   https://<gateway-hostname>/<deployment-path-prefix>/auth/callback

   Note that if the deployment path prefix is simply / and the static login redirect path is /auth/callback, the full callback URL is https://<gateway-hostname>/auth/callback (and not https://<gateway-hostname>//auth/callback).

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