Set up OIDC for a Developer Portal

Learn how to set up OIDC for a Developer Portal.

Overview

You can set up and enable OpenID Connect (OIDC) for NGINX Management Suite API Connectivity Manager (ACM) for production environments that require secure authentication. An Open ID Connect policy sets up the API proxy to act as a relying party to authenticate users with the OIDC provider.

Before You Begin

Complete the following prerequisites before proceeding with this guide:

Terminology

The following terminology is used in this topic:

Term Description
AuthCode Authorization Code.
IDP Identity Provider stores and verifies a user’s identity as a service.
IDP Authorization Server The IDP Authorization Server authenticates and issues access tokens to users.
OAuth OAuth is an open-standard authorization protocol.
OIDC OpenID Connect is an authentication protocol that add an identity verification layer.
PKCE Proof Key for Code Exchange. When public clients request Access Tokens, some additional security concerns are posed that are not mitigated by the Authorization Code Flow alone. PKCE needs the clients app to provide proof to the authorization server, to verify that the authorization code belongs to the clients app.
URI Uniform Resource Indicator. It is a unique character sequence which distinguishes one resource from another.

Supported OIDC Identity Providers

The NGINX Management Suite modules support the following identity providers:

  • Keycloak
  • Okta
  • Azure AD

Refer to the NGINX Plus deployment guide “Single Sign-On with Auth 0” for more information.

Set up OIDC Policy

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

Edit the Cluster Settings

  1. In the ACM user interface, go to Infrastructure > Workspaces > Environments and select the Manage icon for the cluster that you want to set up.
  2. Select the Global Policies tab.
  3. For OpenID Connect Relying Party select Add Policy from the policy’s Actions menu.
  4. Update Application Settings.

Variable Description
(Optional) Choose an OAuth Flow OAuth flows are authorization and authentication processes. There are two OAuth Flow options to choose from the list.
Select AuthCode or PKCE from the list.
(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 frontend to retrieve user info via the IDP.
(Optional) Login URI Login URI is called by the frontend for logging-in IDP using OpenID Connect.
(Optional) Logout URI Logout URI is called by the UI to handle OIDC logout with IDP. See RPLogout for more information.
  1. 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.
  1. 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)
  1. 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.

  2. Select Add.

  3. Select Save and Submit your changes.

  1. Send a POST request to add the OIDC policy to the cluster.
Method Endpoint
POST /api/v1/infrastructure/workspaces/{{proxyWorkspaceName}}/environments
```json
{
    "name": "test",
    "type": "NON-PROD",
    "functions": [
        "DEVPORTAL"
    ],
    "systemProperties": {
        "acmHostName": "<NMS-FQDN>"
    },
    "proxies": [...],
            "policies": {
                "oidc-authz": [
                    {
                        "action": {
                            "config": {
                                "jwksURI": "https://<IDP Authorization server>/v1/keys",
                                "tokenEndpoint": "https://<IDP Authorization server>/v1/token",
                                "userInfoEndpoint": "https://<IDP Authorization server>/v1/userinfo",
                                "authorizationEndpoint": "https://<IDP Authorization server>/v1/authorize",
                                "logOffEndpoint": "https://<IDP Authorization server>/v1/logout",
                                "authFlowType": "PKCE"
                            }
                        },
                        "data": [
                            {
                                "appName": "Myapp",
                                "clientID": "<clientid>",
                                "scopes": "apigw+openid+profile+email+offline_access"
                            }
                        ]
                    }
                ]
            }
        }
    ]
}
```

Single Sign On (SSO) is enabled on the Dev Portal after configuring the OIDC policy. Application developers can log in through the configured centralized identity provider (IDP). After a successful login, they can create resource credentials for the available APIs.