JWT Assertion

Overview

In API Connectivity Manager, you can apply policies to an API Gateway to further enhance their configuration to meet your requirements.

Policies added at the proxy level are applied to all routes within that proxy.

For an overview of the different policy types and available policies, refer to the consult the Learn about Policies topic.

OAuth2 JWT Assertion

Authentication & authorization policies allow a user to restrict access to their APIs by determining the caller’s identity and access level. There are several API Gateway authentication/authorization policy types supported by API Connectivity Manager: API key authentication, basic authentication, OAuth2 JWT assertion, and OAuth2 token introspection. This guide focuses specifically on OAuth2 JWT Assertion.

JSON Web Tokens (JWTs, pronounced “jots”) are a compact and highly portable means of exchanging identity information. JWTs can be used for client authorization and are a better way to control access to web‑based APIs than traditional API keys. Using JWTs as API keys provides a high‑performance alternative to traditional API keys, combining best‑practice authorization technology with a standards‑based schema for exchanging identity attributes.

API Connectivity Manager API owners can restrict access to their APIs with JWTs. The API Proxy Policy can be configured to grant access to APIs only after validating a client’s JWT.

OAuth2 JWT Assertion Flow.

Anatomy of a JWT

JWTs have three parts: a header, a payload, and a signature. In transmission, they look like the following (line breaks have been added for readability, the actual JWT is a single string):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

A period (.) separates the header, payload, and signature. The header and payload are Base64‑encoded JSON objects. The signature is encrypted using the algorithm specified by the alg header, which we can see when we decode our sample JWT:

Encoded Decoded
Header eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9 {
    "alg": "HS256",
    "typ": "JWT"
}
Payload eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6
IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ=		 {
    "sub": "1234567890",
    "name": "John Doe",
    "iat": 1516239022
}

The JWT standard defines several signature algorithms. The value HS256 in the example refers to HMAC SHA‑256. F5 NGINX Plus supports the HSxxx, RSxxx, and ESxxx signature algorithms that are defined in the standard. The ability to cryptographically sign JWTs makes them ideal to be used for client authorization.

How NGINX Plus Validates a JWT

A JWT is considered to be valid when the following conditions are met:

  1. The signature can be verified with a local or remote JSON Web Key (matching on the kid (“key ID”), if present, and alg (“algorithm”) header fields).
  2. The JWT is presented inside the validity period when defined by one or both of the nbf (“not before”) and exp (“expires”) claims.

Before You Begin

Complete the following prerequisites before proceeding with this guide:

  • API Connectivity Manager is installed, licensed, and running.
  • You have one or more Environments with an API Gateway.
  • You have published one or more API Gateways

How to Access the User Interface

This guide provides instructions for completing tasks using the API Connectivity Manager user interface (UI).

To access the UI, go to the FQDN of your NGINX Instance Manager host and log in. On the Launchpad menu, select “API Connectivity Manager.”

How to Access the REST API

You can use tools such as curl or Postman to interact with the API Connectivity Manager REST API. The API URL follows the format https://<NMS_FQDN>/api/acm/<API_VERSION> and must include authentication information with each call. For more information about authentication options, please refer to the API Overview.

Create an OAuth2 JWT Assertion Policy

Take the steps in this section if you would like to restrict access to APIs to clients with a valid JWT. You can set up an OAuth2 JWT Assertion policy using either the web interface or the REST API.

Send a POST request to add the OAuth2 JWT Assertion policy to the API Proxy.

Method Endpoint
POST /services/workspaces/<SERVICE_WORKSPACE_NAME>/proxies
Local JSON Web Key usage with the policy configuration value jwksKeys[] is recommended for test/debugging environments only. For production environments, jwksURI should be used for remote JSON Web Key retrieval.
While all request body configuration values are presented in the request body structure example below, not all configuration values are compatible. See the configuration value description table for further information. 
{
	"policies": {
		"oauth2-jwt-assertion": [
			{
				"action": {
					"jwksURI": "https://idp.io:8443/oauth/certs",
					"cacheKeysDuration": "12h",
					"jwksKeys": [
						{
							"k": "bXlzZWNyZXQ",
							"kid": "0001",
							"kty": "oct"
						}
					],
					"tokenName": "Authorization",
					"tokenSuppliedIn": "HEADER",
					"errorReturnConditions": {
						"notSupplied": {
							"returnCode": 401
						},
						"noMatch": {
							"returnCode": 403
						}
					}
				}
			}
		]
	}
}
Field Type Possible Values Description Required Default value
jwksURI string Example:
https://idp.io:8443/oauth/certs		 URI endpoint that contains public keys used to verify the JWT signature.

Not required if jwksKeys[] is populated.		 Semi-optional N/A
cacheKeysDuration string Example: 12h Specifies how long the keys will be cached. Keys will be refreshed from the URI endpoint after the duration.

Only valid for jwksURI, not applicable for jwksKeys[]. Follows NGINX configuration time measurement units syntax.		 No "12h"
jwksKeys[] array of JSON Web Keys Example in policy request body. Keys to be used to verify JWT signatures. User should supply key data in valid JSON Web Key format. See related standards for JWK, JWK Set Format, and the jwksKeys parameter.

Not required if jwksURI is populated.		 Semi-optional N/A
tokenName string Example: Authorization The name of the header or query parameter where the JWT will be located in the API request.

In the case of default case of Authorization Header, the JWT token is required to adhere to the Bearer Token usage standard.

Example: Authorization: Bearer <access token> where <access token>} is the Base64 encoded Client JWT.		 No "Authorization"
tokenSuppliedIn string One of: ["HEADER", "QUERY"] Specifies where the access token is supplied in the incoming user request. No "HEADER"
errorReturnConditions
.notSupplied
.returnCode		 int In range 400-599 The error code that is returned from the API Proxy when an JWT is not supplied. No 401
errorReturnConditions
.noMatch
.returnCode		 int In range 400-599 The error code that is returned from the API Proxy when an invalid JWT is supplied. No 403

  1. In the API Connectivity Manager user interface, go to Services > {your workspace}, where “your workspace” is the workspace that contains the API Proxy.

  2. Select Edit Proxy from the Actions menu for the desired API Proxy.

  3. On the Policies tab, select Add Policy from the Actions menu for JSON Web Token Assertion.

  4. Choose the JSON Web Key Set (JWKS) source, for remote JWKS select Enter a URI, for local JWKS select Enter a JWKS.

    • For JWKS Uri enter the JWKS URI as URI location and specify for how long the API Proxy should cache the keys, set to 0 to disable.
    • For JWKS add an array of JSON Web Keys in JSON Web Key Set format. See related standards for JWK, JWK Set Format, and the Keys parameter. Example usage:
    {
    "keys": [
        {
            "k": "bXlzZWNyZXQ",
            "kid": "0001",
            "kty": "oct"
        }
    ]
}

  5. Specify how the token is presented in the request, either in the request Headers or as a Query parameter..

  6. Set custom error return code conditions if an JWT is not supplied or validation fails.

  7. Select Add to apply the OAuth2 JWT Assertion policy to the Proxy. Then select Save & Publish to deploy the configuration to the API Proxy.