Example - using multiple OAuth policies in an OAuth provider assembly

This example demonstrates the use of multiple OAuth policies in the assembly flow for a native OAuth provider.

The example is based on the default assembly that is generated when you create a native OAuth provider, and is customized with the addition of gatewayscript policies that use OAuth context variables to manipulate the OAuth flow. For details on creating a native OAuth provider, see Configuring a native OAuth provider.

It has the following assembly flow:Screen capture of OAuth provider assembly flow

The following sections describe the OpenAPI source code that underlies each of the policies in the assembly; for the complete assembly code, download multiple_oauth_policies.txt.

Sample policy to add a custom scope

The add_scope policy is a gatewayscript policy that adds a custom scope to the request.

The underlying OpenAPI source YAML is as follows:
- gatewayscript:
     version: 2.0.0
     title: add_scope
     source: |-
       // Add another custom scope to the request
       let scope = context.get("request.parameters.scope.values[0]);
       if (scope)
         context.set("oauth.processing.scope", scope + " custom");

Validate the initial OAuth request

The first process_request policy is an oauth policy that processes the initial request and verifies that the request is valid. The result of the processing is stored automatically in the oauth.processing context variables for use, as required, by the next OAuth policy in the assembly flow.

The underlying OpenAPI source YAML is as follows:
- oauth:
    title: process_request
    version: 2.0.0
    description: >-
      This oauth policy performs all OAuth/OpenID Connect protocol steps
      that are needed for OAuth Validation by default. The inputs and
      outputs of each of the steps are driven by documented context
      variables. Add or remove the Supported OAuth Components as required.
    oauth-provider-settings-ref:
      default: custom-form
    supported-oauth-components:
      - OAuthValidateRequest

Sample policy to modify the scope

The modify_scope policy is a gatewayscript policy that modifies the scope depending on the calling application.

The underlying OpenAPI source YAML is as follows:
- gatewayscript:
    version: 2.0.0
    title: modify_scope
    source: |-
      let admin_id = '1f1a2aa4-db9f-4423-b2f1-e2572b12123a';

      // Check application and modify the scope
      let app = context.get("oauth.processing.client_id");
      let scope = context.get("oauth.processing.scope");
      if (app === admin_id) {
        context.set("oauth.processing.scope", scope + " admin");
      } else {
        context.set("oauth.processing.scope", scope + " customer");
      }

Branch conditionally according to the OAuth path

The path_branch policy is a switch policy that branches according to the different OAuth paths to process the resource owner.

The underlying OpenAPI source YAML is as follows:
- switch:
    version: 2.0.0
    title: path_branch
    case:
      - condition: ($operationPath() = '/oauth2/token')
        execute:
            .
            .
            .
          definition of the user_security and other_grants policies
           .
           .
           .
      - condition: ($operationPath() = '/oauth2/authorize')
        execute:
           .
           .
           .
          definition of the user_password and implicit_authcode policies
           .
           .
           .
      - otherwise:
           .
           .
           .
          definition of the other_endpoints policy
           .
           .
           .

Process the user name and password, and enable grant type component

The following two policies operate on the token endpoint.

  • The user_password policy for password grant type processes the user name and password from the x-www-form-urlencoded body. The authentication method is derived from the User Security settings in the OAuth provider; see Configuring user security for a native OAuth provider.
  • The other_grants policy is an oauth policy that enables the OAuthGenerateAccessToken, OAuthVerifyAZCode, OAuthVerifyRefreshToken, and OAuthCollectMetadata components to perform the operations for client credentials, authorization code, refresh token, and password grant types.
The underlying OpenAPI source YAML is as follows:
- user-security:
    title: user_password
    version: 2.0.0
    description: ''
    factor-id: default
    extract-identity-method: context-var
    user-context-var: request.parameters.username.values
    pass-context-var: request.parameters.password.values
    ei-stop-on-error: false
    user-auth-method: auth-url
    au-stop-on-error: false
    auth-url: 'http://httpbin.org/basic-auth/user/pass'
    user-az-method: authenticated
    az-stop-on-error: true
    auth-response-headers-pattern: (?)x-api*
    auth-response-header-credential: X-API-Authenticated-Credential
- oauth:
    title: other_grants
    version: 2.0.0
    description: >-
      This oauth policy performs all OAuth/OpenID Connect
      protocol steps that are needed for token path by default.
      The inputs and outputs of each of the steps are driven by
      documented context variables. Add or remove the Supported
      OAuth Components as required.
    oauth-provider-settings-ref:
      default: custom-form
    supported-oauth-components:
      - OAuthGenerateAccessToken
      - OAuthVerifyAZCode
      - OAuthVerifyRefreshToken
      - OAuthCollectMetadata

Perform authorization checks, and enable grant type components

These following two policies operate on the authorize endpoint.

  • The user_security policy configuration is derived from the User Security settings in the OAuth provider; see Configuring user security for a native OAuth provider.
  • The implicit_authcode policy is an oauth policy that enables the OAuthGenerateAZCode, OAuthGenerateAccessToken, and OAuthCollectMetadata components to perform the operations for the implicit and authorization code grant types.
The underlying OpenAPI source YAML is as follows:

- user-security:
    title: user_security
    version: 2.0.0
    description: >-
      This user security policy performs EI(basic) and AU(auth
      url) check for oauth assembly. Change the security check
      method as required
    factor-id: default
    extract-identity-method: basic
    ei-stop-on-error: true
    user-auth-method: auth-url
    au-stop-on-error: true
    user-az-method: authenticated
    az-stop-on-error: true
    auth-response-headers-pattern: (?)x-api*
    auth-response-header-credential: X-API-Authenticated-Credential
    auth-url: 'http://httpbin.org/basic-auth/user/pass'
- oauth:
    title: implicit_authcode
    version: 2.0.0
    description: >-
      This oauth policy performs all OAuth/OpenID Connect
      protocol steps that are needed for az code path by
      default. The inputs and outputs of each of the steps are
      driven by documented context variables. Add or remove the
      Supported OAuth Components as required.
    oauth-provider-settings-ref:
      default: custom-form
    supported-oauth-components:
      - OAuthGenerateAZCode
      - OAuthGenerateAccessToken
      - OAuthCollectMetadata

Process all other endpoints

The otherwise condition catches all other endpoints such as the introspect and revoke endpoints. The other_endpoints policy in the otherwise condition is an oauth policy that enables the OAuthIntrospectToken, and OAuthRevokeTokencomponents components to perform the operations for introspect and revoke.

The underlying OpenAPI source YAML is as follows:
- oauth:
    title: other_endpoints
    version: 2.0.0
    description: >-
      This oauth policy performs all OAuth/OpenID Connect
      protocol steps that are needed for all other paths by
      default. The inputs and outputs of each of the steps are
      driven by documented context variables. Add or remove the
      Supported OAuth Components as required.
    oauth-provider-settings-ref:
      default: custom-form
    supported-oauth-components:
      - OAuthIntrospectToken
      - OAuthRevokeToken