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.
Edit the Cluster Settings
- 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.