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:

ACM is installed, licensed, and running. See ACM Install Guide.
You have one or more Environments with API Gateway or Dev Portal clusters.

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.

In the ACM 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.

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.