End of Sale Notice:

F5 NGINX is announcing the End of Sale (EoS) for NGINX Management Suite API Connectivity Manager Module, effective January 1, 2024.

F5 maintains generous lifecycle policies that allow customers to continue support and receive product updates. Existing API Connectivity Manager Module customers can continue to use the product past the EoS date. License renewals are not available after September 30, 2024.

See our End of Sale announcement for more details.

OpenID Connect

As an Infrastructure Administrator, use this guide to configure OpenID Connect policy to enable Single Sign On for the gateways.

Overview

In API Connectivity Manager, you can apply global policies to API Gateways and Developer Portals to ensure your organization’s security requirements are enforced.

When you add policies at the environment level, they will apply to all proxies hosted within that environment.

See the Learn about Policies topic for an overview of the different policy types and available policies.

About OpenID Connect Policy

OpenID Connect (OIDC) builds on OAuth 2.0 to offer an identity layer and a unified authentication process for securing APIs, native apps, and web applications. Clients can authenticate an end-user’s identity by using an Authorization Server. End-user information is communicated using claims in a security token called an identity token.

The OpenID Connect policy for API Connectivity Manager provides users with a convenient and secure single sign-on experience, allowing them to log in to multiple OAuth-enabled applications with a single set of credentials. This policy can be easily integrated with any compatible identity provider, providing single sign-on access to both API gateways and Developer Portals.

Intended Audience

This guide is intended for API Owners — the individuals or teams who are responsible for designing, creating, and maintaining APIs.

Before You Begin

Before configuring API gateways and Developer Portals as OpenID Connect relying parties (RPs), you need to gather the necessary Identity provider (IDP) details:

IDP’s well-known endpoints
Client ID
Client Secret (needed depending on the OAuth flow)

Note:
The Developer Portal supports both PCKE and AuthCode authorization code flows.

Workflow for Applying Policy

To apply the OpenID Connect (OIDC) policy or make changes to it, here’s what you need to do:

Edit an existing environment or create a new one.
Select the cluster on which to apply the policy.
Check the advanced settings to see if the policy has been applied.
Edit the policy as needed.
Save and publish the changes.

Policy Settings

Field	Type	Possible Values	Description	Required	Default
`authFlowType`	string	`AUTHCODE` `PCKE`	PKCE is an OAuth 2.0 security extension for public clients on mobile devices intended to avoid a malicious programme creeping into the same computer from intercepting the authorisation code.	No	`AUTHCODE`
`authorizationEndpoint`	string	Example: https://accounts.google.com/o/oauth2/v2/auth	URL of the IdP's OAuth 2.0 Authorization Endpoint.	Yes	N/A
`authzParams.key`	string	Between 1 and 128 characters		No	N/A
`authzParams.paramType`	string	QUERY. PATH, HEADER		No	N/A
`authzParams.value`	string	Between 1 and 128 characters		No	N/A
`errorReturnConditions.` `noMatch.` `returnCode`	integer	In range `100-599`	The error code that needs to be used by the nginx data-plane when basic auth is invalid or not supplied.	No	`403`
`errorReturnConditions.` `notSupplied.` `returnCode`	Integer	In range `100-599`	The error code that needs to be used by the nginx data-plane when invalid clientID is supplied.	No	`401`
`jwksURI`	string	Example: https://www.googleapis.com/oauth2/v3/certs		Yes	N/A
`logOffEndpoint`	string	Example: https://oauth2.googleapis.com/revoke		Yes	N/A
`logOutParams.key`	string	Between 1 and 128 characters		No	N/A
`logOutParams.paramType`	string	QUERY, PATH, HEADER		No	N/A
`logOutParams.value`	string	Between 1 and 512 characters		No	N/A
`resolver.enableIPv6`	boolean	true/false		No	false
`resolver.servers.hostname`	string	Between 1 and 253 characters		Yes	N/A
`resolver.servers.port`	integer	In range `1-65535`		Yes	80
`resolver.timeout`	string	Example: 30s Between 2 and 14 characters		No	30s
`resolver.valid`	string	Example: 24s Between 2 and 14 characters		No	30s
`returnTokenToClientOnLogin`	string	id_token, none	Optionally return token as a query param to the app after successful login.	No	N/A
`tokenEndpoint`	string	Example: https://oauth2.googleapis.com/token	URL of the IdP's OAuth 2.0 Token Endpoint.	Yes	N/A
`tokenParams.key`	string	Between 1 and 128 characters		No	N/A
`tokenParams.paramType`	string	QUERY, PATH, HEADER		No	N/A
`tokenParams.value`	string	Between 1 and 512 characters		No	N/A
`uris.loginURI`	string	Example: `/login`	This location is called by frontend for logging-in IDP using OpenID Connect.	No	N/A
`uris.logoutURI`	string	Example: `/logout`	This location is called by UI to handle OIDC logout with IDP as per: https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout	No	N/A
`uris.redirectURI`	string	Example: `/_codexch`	This location is called by the IdP after successful authentication.	No	N/A
`uris.userInfoURI`	string	Example: `/userinfo`	This location is called by frontend to retrieve user info via the IDP.	No	N/A
`userInfoEndpoint`	string	Example: https://openidconnect.googleapis.com/v1/userinfo	URL of the IdP's UserInfo Endpoint.	Yes	N/A
`userRegistration`	string		User registration URLs, can be used to specify customer or workforce registration URLs.	No	N/A
`wellKnownEndpoint`	string	Example: https://accounts.google.com/.well-known/openid-configuration	OIDC .well-known configuration endpoint. The well-known endpoint returns OpenID Connect metadata about the authorization server.	No	N/A

You can set up an OIDC policy by using either the web interface or the REST API.

Applying the Policy

See Also:

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.

To apply the OpenID Connect policy using the REST API, send an HTTP POST request to the Environments endpoint.

Method	Endpoint
POST	`/api/v1/infrastructure/workspaces/{proxyWorkspaceName}/environments`

JSON request

{
  "policies": {
    "oidc-authz": [
      {
        "action": {
          "authFlowType": "PKCE",
          "authorizationEndpoint": "https://<IDP Domain>/v1/Authorize",
          "jwksURI": "https://<IDP Domain>/v1/keys",
          "logOffEndpoint": "https://<IDP Domain>/v1/logout",
          "tokenEndpoint": "https://<IDP Domain>/v1/Token",
          "userInfoEndpoint": "https://<IDP Domain>/v1/userinfo",
          "uris": {
            "loginURI": "/login",
            "logoutURI": "/logout",
            "redirectURI": "/_codexch",
            "userInfoURI": "/userinfo"
          },
          "returnTokenToClientOnLogin": "none",
          "forwardTokenToBackend": "access_token",
          "errorReturnConditions": {
            "noMatch": {
              "returnCode": 403
            },
            "notSupplied": {
              "returnCode": 401
            }
          }
        },
        "data": [
          {
            "clientID": "myclientID1234",
            "scopes": "email+openid+profile"
          }
        ]
      }
    ]
  }
}

This JSON defines an OpenID Connect (OIDC) authorization policy. It specifies the URL endpoints for the authorization, token, and user info services, as well as the URIs for login, logout, and redirect activities. It also defines that the client ID and scopes are “myclientID1234” and “email+openid+profile”, respectively. Additionally, it specifies how to handle errors, such as returning a 403 code when there is no match and a 401 code when the data is not supplied.

In a web browser, go to the FQDN for your NGINX Instance Manager host and log in. Then, from the Launchpad menu, select API Connectivity Manager.
On the left menu, select Infrastructure.
From the list of workspaces, select the workspace for your cluster’s environment.
From the list of environments, select the environment for your cluster.
From the list of clusters, locate the cluster you want to add the policy to. On the Actions menu (represented by an ellipsis, ...), select Edit Advanced Config.
On the left menu, select Global Policies.
Locate the OpenID Connect Relying Party policy in the list of policies. On the Actions menu (represented by an ellipsis, ...), select Add Policy.
In the API Connectivity Manager user interface, go to Infrastructure > Workspaces > Environments and select the Edit Advanced Config from the Actions menu for the cluster you want to set up.
Select the Global Policies tab.
For OpenID Connect Relying Party select Add Policy from the policy’s Actions menu.
Update Application Settings.

Variable	Description
(Optional) Choose an OAuth Flow	OAuth flows are authorization and authentication processes.
(Optional) App Name	Name the application.
Client ID	Client ID is a public identifier for the client that is required for all OAuth flows.
Client Secret	Client Secret is used by the client to exchange an authorization code for a token. It should be an empty value with `""` when PKCE is enabled.
Scopes	List of the OAuth 2.0 scope values that this server supports. For example, `openid+profile+email+offline_access`.
(Optional) Sign-Out Redirect URI	Signout Redirect URI refers to the URI the user gets redirected to after a successful logout.
(Optional) Redirect URI	Redirect URI is called by the IDP after successful authentication.
(Optional) User Info URI	User Info URI is called by the front end to retrieve the user’s info via the IDP.
(Optional) Login URI	Login URI is called by the front end for logging-in IDP using OpenID Connect.
(Optional) Logout URI	Logout URI is called by the front end to handle OIDC logout with the IDP. See RPLogout for more information.

Update Authorization Server Settings

Specify all Endpoints to update authorization server settings.

Variable	Description
Keys	URL of the IDP’s JSON Web Key Set document.
Token	URL of the IDP’s OAuth 2.0 Token Endpoint.
Authorization	URL of the IDP’s OAuth 2.0 Authorization Endpoint.
User Info	URL of the IDP’s UserInfo Endpoint.
LogOff URI	URL of the IDP’s end_session endpoint.

Update General Settings

Variable	Description
(Optional) Select the token to return to the client upon login	Options: - id_token - none
(Optional) Select the token to forward to the backend application	Options: - access_token - id_token - both - none
Add User Registration	- add URL - add type
Add Authorization Parameter	- add parameter key - add value - add type (Query or Path)
Add Token Parameter	- add parameter key - add value - add type (Query or Path)
Add Logout Parameter	- add parameter key - add value - add type (Query or Path)

Update Custom Error Handling.

You can customize how the proxy should handle the following error conditions:

when Client ID is not supplied
when there is no match for the Client ID

Specify the HTTP error code in the box next to the error condition. The specified error code will be displayed when the related error condition is true.

Select Add.
Select Save and Submit your changes.