Enable Single Sign-On for Developer Portal

Learn how to enable Single Sign-On for Developer Portal.


This documentation applies to NGINX Management Suite API Connectivity Manager 1.1.0 and later.

Overview

Single sign-on (SSO) can be enabled on the Developer Portal to secure access to the portal and to allow authenticated API consumers to manage resource credentials. Logged-in consumers can then self-manage resource credentials for the APIs.

Single sign-on is enabled by applying an OpenID Connect (OIDC) policy on the Developer Portal cluster. The OIDC policy sets up the portal 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 adds 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

API Connectivity Manager supports the following identity providers:

  • Keycloak
  • Okta
  • Azure AD

Refer to the NGINX Plus Single Sign-On deployment guides to learn how to configure NGINX Plus for use with these identity providers. The guides describe where to find the information from the identity provider that you will need to provide when setting up OIDC in ACM.

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.
(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.
  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.

Known Limitation with the policy

The OIDC policy does not yet support custom DNS for resolution. Only external DNS resolution is supported.