Getting Started with OIDC

Overview

We highly recommend using Open ID Connect (OIDC) as the preferred authentication method for the NGINX Management Suite. OIDC offers several advantages, including a Single Sign-On (SSO) experience for users and simplified user management for administrators through the use of user groups. OIDC allows for easy scalability and streamlined administration of user access.

NGINX Management Suite’s implementation of OpenID Connect (OIDC) is designed to work with any Identity Provider (IdP) that supports the OIDC protocol. The instructions provided below are general and can be applied to any IdP.

Do you need to configure a specific IdP?
To learn how to configure OpenID Connect (OIDC) with a specific identity provider, refer to the linked topics in the Set Up Specific IdPs for OIDC section at the bottom of this page.

Create Roles and User Groups in NGINX Management Suite

When using OIDC for authentication, administrators don’t need to create and manage users in NGINX Management Suite. Instead, they can make user groups in NGINX Management Suite that match groups in their Identity Provider. The roles assigned to the user group set the access level and permissions for users according to their group membership. Users from the Identity Provider who aren’t in a group with an assigned role won’t have access to NGINX Management Suite.

To grant users access using OIDC, simply follow these steps:

1. Create a role in NGINX Management Suite,
2. Create a user group and assign a role to it. Important: The group name must exactly match a group name in your IdP.
3. Set up OIDC.

Create a Role

Roles within NGINX Management Suite are a critical component of role-based access control (RBAC). By defining roles, you specify access levels and permissions for different user groups that map to groups in your Identity Provider (IdP).

NGINX Management Suite comes pre-configured with an administrator role called admin. Additional roles can be created as needed.

The admin user or any user with CREATE permission for the User Management feature can create a role.

Here’s how to create a role and set its permissions:

1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in.

2. Select the Settings (gear) icon in the upper-right corner.

3. Select Roles from the left navigation menu.

4. Select Create.

5. On the Create Role form, provide the following details:

   • Name: The name to use for the role.
   • Display name: An optional, user-friendly name to show for the role.
   • Description: An optional, brief description of what the role is.

6. To add permissions:

   1. Select Add Permission.

   2. Choose the NGINX Management Suite module you’re creating a permission for from the Module list.

   3. Select the feature you’re granting permission for from the Feature list. To learn more about features, refer to Getting Started with RBAC.

   4. Select Add Additional Access to add a CRUD (Create, Read, Update, Delete) access level.

      • Choose the access level(s) you want to grant from the Access list.

   5. Select Save.

7. Repeat step 6 if you need to add more permissions for other features.

8. When you’ve added all the necessary permissions, select Save to create the role.

Example Scenario

Imagine you need to create an “app-developer” role. This role permits users to create and edit applications without allowing them to delete or perform administrative tasks. You would name the role ‘app-developer,’ select one or more features, and grant permissions that align with the requirements of application development, avoiding features and permissions that enable deletion or other administrative functions.

Next Steps

After creating a role, you’ll want to assign it to a user group within NGINX Management Suite that matches a group in your IdP. Proceed to the Create a User Group with an Assigned Role section for detailed instructions.

Create a User Group with an Assigned Role

Group names must match with your IdP
To ensure that NGINX Management Suite and your Identity Provider (IdP) work together seamlessly, group names must exactly match between the two systems. If the group names do not correspond, the OIDC integration will not work, preventing users from accessing the NGINX Management Suite. For instance, if you have a group named “app-developers” in your IdP, you must create a user group named “app-developers” in NGINX Management Suite. The group claim must also be part of the token your IdP generates. For guidance on how to add group claims, refer to your IdP’s documentation.

Users from an external identity provider can’t be assigned roles directly in NGINX Management Suite, but they inherit roles through group memberships.

Here’s how to create a user group and assign roles to it:

1. In a web browser, go to the FQDN for your NGINX Management Suite host and log in.

2. Select the Settings (gear) icon in the upper-right corner.

3. From the left navigation menu, select User Groups.

4. Select Create.

5. In the Create Group form, provide information for the group:

   • (Required) Group Name: The name or Object ID of the group. It’s essential to carefully follow these guidelines:

     • The value must exactly match the group name or Object ID used in the identity provider.
     • A group can be linked to only one identity provider.
     • You must add a group claim to your token within your identity provider.

   • Display Name: Enter a friendly name for the group.

   • Description: Provide a brief summary of the group.

6. (Required) Choose one or more roles from the Roles list to assign to the group.

   Important:
   To ensure full access to the NGINX Management Suite platform, you must assign the admin role to at least one user group. This role grants users comprehensive privileges and permissions within the platform.

7. Select Save to create the group.

Example Scenario

Imagine you’ve created a role called “app-developer” that lets people develop, create, and modify applications, but not delete them or perform administrative tasks. You want this role to correspond to a group in your IdP named “app-developers.”

In this case, you’d select the “app-developer” role when creating the “app-developers” user group in NGINX Management Suite. Users from the Identity Provider who belong to the “app-developers” group will then inherit the “app-developer” role and the associated permissions in NGINX Management Suite.

Next Steps

Now that you have created a user group and assigned a role in NGINX Management Suite, continue to the Configure OIDC section of this document. These instructions will help you complete the integration with your Identity Provider and ensure your user groups and permissions work as expected.

Configure OIDC

Before You Begin

Warning:
Before switching from Basic Authentication to OIDC, make sure to add at least one admin user to your identity provider. Failure to do so can result in admin users being locked out of NGINX Management Suite. If this occurs, you can restore access by reverting back to Basic Authentication.

When you configure OIDC authentication for NGINX Management Suite, Basic Authentication will be disabled for all users, including the default admin user. To ensure uninterrupted access, you need to create a user group in NGINX Management Suite that corresponds to a group in your Identity Provider (IdP) and assign the appropriate roles.

• Follow the instructions above to grant users access before proceeding.

Requirements

The following requirements must be met before you can use OIDC with NGINX Management Suite:

1. Install Instance Manager on a server that also has NGINX Plus R21 or a newer version installed. Make sure the server hosting NGINX Plus has a fully qualified domain name (FQDN).

2. Install the NGINX JavaScript module (njs) on the same server as Instance Manager. This module is necessary for managing communications between NGINX Plus and the identity provider.

3. Configure an Identity Provider (IdP) to provide authentication services. This involves setting up the necessary authentication policies, scopes, and client credentials within your IdP.

Enable OIDC

To enable OIDC functionality, you must update the placeholder default values in the OIDC configuration file (openid_configuration.conf). Follow these steps:

1. Open the OIDC configuration file /etc/nms/nginx/oidc/openid_configuration.conf using a text editor and update the default placeholder values with the relevant information for your identity provider. (To learn more about the variables, refer to the OIDC Settings below.) Save the changes.

2. Using a text editor, open the /etc/nginx/conf.d/nms-http.conf configuration file and uncomment the OIDC settings starting with #OIDC. Comment out the Basic Authentication settings. Save the changes.

3. If you have additional modules installed, such as API Connectivity Manager, you need to modify their specific configuration files as well.

   Open the API Connectivity Manager configuration file /etc/nms/nginx/locations/nms-acm.conf in an app-developer and uncomment the OIDC settings starting with #OIDC. Comment out the settings for Basic Authentication. Save the changes.

4. Run the command sudo nginx -t to validate the configuration and ensure there are no errors.

5. Finally, reload NGINX and apply the new configuration by running the command sudo nginx -s reload.

OIDC Configuration Values

Select the links below to view the OIDC configuration values and descriptions.

map $host $oidc_authz_endpoint {
    default "https://{my-app}.okta.com/oauth2/{version}/authorize";
}
map $host $oidc_authz_path_params {
    default '{ "my-app": "{my-app}", "version": "v1" }';
}

 map $host $oidc_authz_query_params {
 default '{
     "response_type": "code",
     "scope"        : "$oidc_scopes",
     "client_id"    : "$oidc_client",
     "redirect_uri" : "$redirect_base$redir_location",
     "nonce"        : "$nonce_hash",
     "state"        : 0
 }';

map $host $oidc_logout_endpoint {
    default "https://{my-app}.okta.com/oauth2/{version}/logout";
}
map $host $oidc_authz_path_params {
    default '{ "my-app": "{my-app}", "version": "v1" }';
}

 map $host $oidc_logout_query_params {
    # example 1. AWS Cognito Logout & prompt a user to sign in as another user.
    default '{
        "response_type": "code",
        "client_id"    : "$oidc_client",
        "redirect_uri" : "$redirect_base$redir_location",
        "state"        : "STATE",
        "scope"        : "$oidc_scopes"
    }';

    # example 2. AWS Cognito Logout & redirect back to client.
    default '{
        "client_id"    : "$oidc_client",
        "logout_uri"   : "$redirect_base/_logout"
    }';

map $host $oidc_token_endpoint {
    default "https://{my-app}.okta.com/oauth2/{version}/token";
}
map $host $oidc_authz_path_params {
    default '{ "my-app": "{my-app}", "version": "v1" }';
}

map $host $oidc_token_query_params {
    default '{ "example": "data" }';
}

Set Up Specific IdPs for OIDC

Select from the following options to set up OIDC for a specific identity provider:

• Set up Microsoft Entra as an OIDC identity provider
• Set up Keycloak as an OIDC Identity Provider