Design and Implementation

Sequence Diagram

Sequence Diagram With Allowlist Policy Chaining (Sample Reference)

Implementation Details

1. This policy fetches the value of the Authorization header from the incoming request, and if the token is in the format: <String>.<String>.<String>, then the type of token is JWT; else Cloud API Management OAuth2 access token.

2. If the token type is Cloud API Management OAuth2, then use the MAPI locator service in Policy, applying the following logic:

   • Set service endpoint OAuth grant types to client_credentials, authorization code, implicit and Password. (As Endpoint configuration doesn't have a way to select grant type credentials).

   • Proceed with Cloud API Management OAuth2 authentication flow and exit.

3. If the token type is third-party JWT, then fetch the API key (client_id) from the JWT payload claim (configurable on the Cloud API Management Endpoint Key & Method Detection page) and validate it. If validation fails, the policy returns an HTTP 403 error and stops processing.

   info

   Starting with Local Edition 6.3.0, the Key Field Identifier supports JSONPath expressions to reference claims nested within the JWT payload (for example, $.params.client_origin_id), in addition to root-level claims. In earlier versions, only root-level claims were supported for client ID detection, and a nested claim reference would fail authentication, resulting in ERR_403_DEVELOPER_INACTIVE error.

4. Policy fetches the mandatory preInput configuration for jwks_uri and makes the call to fetch JWK (JSON Web Key) from JWKS (JSON Web Key Set).

   If an optional http_proxy_server is specified in the pre-input configurations, a call to retrieve JSON Web Key Set (JWKS) is made through a proxy.

5. Depending on the response from the previous call, validate the JWT signature and expiry. If validation fails, the policy returns anHTTP 403 error and stops processing.

6. Depending upon the configuration of standard and non-standard claims, the corresponding API request is accepted or blocked for augmented validation needed in business policies/rules.

7. Policy optionally provides configuration for inject_headers and injects the corresponding headers into the request.

8. Policy optionally provides a configurable capability to block/forward the authorization header to the backend/origin server.

Block Authorization Header Feature

• If block_authorization_header in PreInput Value is true, then after JWT token validation, the "Authorization" header is removed from the request, before it is sent to backend client resources.

• The default value of block_authorization_header is true.

Shared Token SPKey Feature

• At the endpoint, to authenticate the Cloud API Management OAuth2.0 tokens generated from different API Service, add the below parameter in PreInput Value configuration:

  shared_token_spkey:<SPKey of another API Service>
  note

  • There is no need to chain with: com.mashery.proxy.customer.generic.oauth2-shared-token-adapter
  • Provide this PreInput parameter only when OAuth2 tokens generated from another API Service need to be validated at this endpoint.

• If shared_token_spkey is defined in the PreInput Value configuration:

  • Service configuration is loaded using this shared token spkey, and an Oauth2 context is created using this service configuration.

  • The original spkey is stored and replaced by shared spkey.

  • Cloud API Management MAPI look-up is done using this shared spkey. After the MAPI look-up, the original spkey is restored in the service configuration.

  You can find the value of shared_token_spkey easily by taking the 'API Definition' ID from the URL in the browser: (Sample reference)

  

Inject Headers Feature

Refer to the Inject Headers Feature section for JWT Authentication Policy.

Token Validation Rules and Checks

Refer to the Token Validation Rules and Checks section for JWT Authentication Policy.

Business Rules and Assumptions

Refer to the Business Rules and Assumptions section for JWT Authentication Policy.