Get started with OIDC

Overview

We recommend using OpenID Connect (OIDC) as the preferred authentication method for NGINX Instance Manager. OIDC offers several advantages, including Single Sign-On (SSO) for users and simplified user management for administrators through user groups. OIDC also enables easy scalability and streamlined user access management.

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

Do you need to configure a specific IdP?
To learn how to configure 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 Instance Manager

When using OIDC for authentication, administrators don’t need to create and manage users in NGINX Instance Manager. Instead, they create user groups in NGINX Instance Manager that match groups in their IdP. The roles assigned to the user group set the access level and permissions for users based on their group membership. Users who aren’t in a group with an assigned role won’t have access to NGINX Instance Manager.

To grant users access using OIDC, follow these steps:

1. Create a role in NGINX Instance Manager.
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 in NGINX Instance Manager are a critical part of role-based access control (RBAC). By creating roles, you define the access levels and permissions for different user groups that correspond to groups in your Identity Provider (IdP).

NGINX Instance Manager 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.

Follow these steps to create a role and set its permissions:

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

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

3. From the left navigation menu, select Roles.

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 the role.

6. To add permissions:

   1. Select Add Permission.
   2. Choose the NGINX Instance Manager module you’re creating the 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 Get started with RBAC.
   4. Select Add Additional Access to choose 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

Suppose you need to create an “app-developer” role. This role allows users to create and edit applications but not delete them or perform administrative tasks. You would name the role app-developer, select the relevant features, and grant permissions that align with the application development process while restricting administrative functions.

Next steps

After creating a role, assign it to a user group within NGINX Instance Manager 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 Instance Manager and your IdP work together seamlessly, group names must exactly match between the two systems. If the group names don’t match, the OIDC integration will fail, preventing users from accessing NGINX Instance Manager. For example, if you have a group called “app-developers” in your IdP, you must create a user group called “app-developers” in NGINX Instance Manager. The group claim must also be part of the token your IdP generates. Refer to your IdP’s documentation for guidance on adding group claims.

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

1. In a web browser, go to the FQDN for your NGINX Instance Manager 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. On the Create Group form, provide the following information:

   • Group Name (required): The group name or Object ID. This must exactly match the name used in the IdP.
   • Display Name: A friendly name for the group.
   • Description: A brief description of the group.

6. Select one or more roles from the Roles list to assign to the group.

   Important:
   At least one user group must have the admin role assigned.

7. Select Save to create the group.

Example scenario

Imagine you’ve created a role called “app-developer” for users who develop, create, and modify applications but don’t need to perform administrative tasks. You want this role to correspond to a group in your IdP named “app-developers.”

In this case, select the “app-developer” role when creating the “app-developers” user group in NGINX Instance Manager. Users in the “app-developers” group from the IdP will inherit the “app-developer” role in NGINX Instance Manager.

Next steps

Now that you’ve created a user group and assigned a role in NGINX Instance Manager, continue to the configure OIDC section. These instructions will help you integrate with your IdP and ensure 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 IdP. Failure to do so can result in admin users being locked out of NGINX Instance Manager. If this occurs, you can restore access by reverting back to basic authentication.

When you configure OIDC for NGINX Instance Manager, basic authentication will be disabled for all users, including the default admin user. To ensure uninterrupted access, create a user group in NGINX Instance Manager that corresponds to a group in your 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 Instance Manager:

1. Install Instance Manager on a server that also has NGINX Plus R21 or newer installed. Ensure 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 required for managing communications between NGINX Plus and the identity provider.

3. Configure an IdP to provide authentication services. This includes setting up authentication policies, scopes, and client credentials within your IdP.

Enable OIDC

To enable OIDC, follow these steps to update the OIDC configuration file:

1. Open /etc/nms/nginx/oidc/openid_configuration.conf in a text editor and replace the default placeholder values with the relevant information for your IdP. (For more information on the variables, refer to the OIDC configuration values.) Save the changes.

2. Open /etc/nginx/conf.d/nms-http.conf in a text editor and uncomment the OIDC settings that begin with #OIDC. Comment out the basic authentication settings. Save the changes.

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

4. Reload NGINX and apply the new configuration with sudo nginx -s reload.

OIDC configuration values

The sections below provide detailed descriptions of the OIDC configuration values.

Metadata from well-known endpoints

• $oidc_authz_endpoint: The URL of the IdP’s OAuth 2.0 Authorization endpoint.
• $oidc_jwt_keyfile: The URL of the IdP’s JSON Web Key Set (JWKS) document.
• $oidc_logout_endpoint: The URL of the IdP’s end_session endpoint.
• $oidc_token_endpoint: The URL of the IdP’s OAuth 2.0 Token endpoint.
• $oidc_userinfo_endpoint: The URL of the IdP’s UserInfo endpoint.
• $oidc_host: The URL of the IdP’s application (e.g., https://{my-app}.okta.com).
• $oidc_scopes: List of OAuth 2.0 scope values supported by the server (e.g., openid+profile+email+offline_access).

Custom configuration for well-known endpoints

For custom settings, adjust parameters such as $oidc_authz_path_params_enable, $oidc_logout_query_params, and others to match your IdP’s needs.

Set up specific IdPs for OIDC

For specific IdP setup instructions, refer to the following:

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