Microsoft Entra: Set up OIDC authentication

Overview

This guide explains how to configure Microsoft Entra (AD) as an identity provider (IdP) for F5 NGINX Instance Manager. By implementing OIDC for authentication, administrators can simplify user management in NGINX Instance Manager. Instead of creating and managing users individually, administrators can create user groups in NGINX Instance Manager that align with groups in their Identity Provider. Access and permissions for users are determined by the roles assigned to their respective user groups. Users from the Identity Provider who are not part of a group with an assigned role will not have access to NGINX Instance Manager.

We strongly recommend Open ID Connect (OIDC) as the preferred authentication method for the NGINX Instance Manager. OIDC brings several benefits, including Single Sign-On (SSO) and simplified user management through user groups.

To configure Microsoft Entra as an OIDC IdP, follow these steps:

Configure Microsoft Entra:

1. Create an Application Registration for NGINX Instance Manager.
2. Add owners (users) and their email addresses to Microsoft Entra.
3. Create groups in Microsoft Entra and assign user membership.

Configure NGINX Instance Manager:

1. Add user groups to NGINX Instance Manager, using the same group names as in Microsoft Entra.
2. Configure NGINX Plus in NGINX Instance Manager to use Microsoft Entra as the designated identity provider.

Requirements

To successfully follow the instructions in this guide, you must complete the following requirements:

1. Create a Microsoft Entra premium account. If you have a standard account, you’ll need to upgrade.
2. Install Instance Manager on a server that also has NGINX Plus R25 or a newer version installed. Make sure the server hosting NGINX Plus has a fully qualified domain name (FQDN).
3. 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.

Configure Microsoft Entra

Complete the steps in the section to configure Microsoft Entra for use with NGINX Instance Manager.

Register Application

To register an application with Microsoft Entra:

1. Go to the Azure portal and log in.

2. Select Microsoft Entra from the list of Azure services.

3. On the left navigation menu, under the Manage section, select App registrations.

4. Select New registration.

5. Provide the following details:

   • Enter a name for the application in the Name field, such as “NGINX Instance Manager”.
   • Select Account in this organizational directory only from the list of account types.
   • Under the Redirect URI section, choose Web and enter the redirect URI, for example, https://<my-nginx-instance-manager>/_codexch.

   

6. Select Register.

7. On the confirmation page, make a note of the following information. You’ll need to provide this information later to complete the setup:

   • Application (client) ID
   • Directory (tenant) ID

Create Client Secret

Important:
Make sure to save the value of the client secret in a secure location for future reference. Once you navigate away from the page, the value cannot be retrieved again.

To create a client secret:

1. On the left navigation menu, under the Manage section, select Certificates & secrets.
2. Select New client secret.
3. In the Description box, type a description for the client secret.
4. Select Add. The client secret will be added to the list with a unique secret string value and ID.
5. Copy the value for the client secret.

Add Owners

Important:
Make sure to add at least one user with administrative privileges. Failure to do so may lock admin users out of NGINX Instance Manager. If that happens, revert to Basic Auth to restore access.

To add owners (users):

1. On the left navigation menu, under the Manage section, select Owners.
2. Select Add owners.
3. Search for the user you want to add, then select Select. Repeat this step for each user you want to add.

Add Group Claim to Token

Note:
The only supported group claim format for groups created in Microsoft Entra is Microsoft Entra group ObjectId.

To include the user’s group membership information in the token for authentication and authorization, follow these steps:

1. On the left navigation menu, under the Manage section, select Token configuration.
2. Select Add groups claim.
3. Select Groups assigned to the application.
4. Select Add.

Assign Group to Application

Note:
By default, tokens expire after 60 minutes. You can find instructions on configuring token expiration in the Microsoft Entra topic Configurable token lifetime properties.

Adding a group to the registered application will give all group members the same access.

1. On the left navigation menu, under the Manage section, select Overview.
2. In the Essentials section, select the link next to Managed application in local directory.
3. In the Getting Started section, select Assign users and groups.
4. Select Add user/group.
5. On the Add Assignment form, under the Users and groups section, select None Selected.
6. In the search box in the Users and groups drawer, type the name of the group you want to associate with the application.
7. Select the group from the list, and select Select.
8. Finally, select Assign.

Configure NGINX Instance Manager

Create Roles in NGINX Instance Manager

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.

Create User Groups in NGINX Instance Manager

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.

Configure NGINX Plus with Microsoft Entra as Identity Provider

Configure NGINX Plus to use Microsoft Entra as the identity provider.

1. Install the NGINX JavaScript module (njs) on your NGINX Instance Manager server by running the appropriate command. This module is required for handling the interaction between NGINX Plus and Microsoft Entra (IdP).

   • CentOS, RHEL:

     sudo yum install nginx-plus-module-njs
     

   • Debian, Ubuntu:

     sudo apt install nginx-plus-module-njs
     

2. Open the /etc/nginx/nginx.conf file in a text editor and add the following directive to the top-level (“main”) section to load the NGINX JavaScript module:

   load_module modules/ngx_http_js_module.so;
   

3. Open the /etc/nms/nginx/oidc/openid_configuration.conf file in a text editor. Replace the following variables in the file with the values you saved when configuring Microsoft Entra. Save the changes:

   • {client_key}: Replace with the Application (client) ID obtained when registering the application.
   • {tenant_key}: Replace with the Directory (tenant) ID obtained when registering the application.
   • {client_secret}: Replace with the encoded client secret that was generated when creating the client secret.
   Example openid_configuration.conf

   # NGINX Instance Manager - OpenID Connect configuration
   # Created for v. 2.0
   # (c) NGINX, Inc. 2021
   
   # Enable when using OIDC with Microsoft Entra
   map $http_authorization $groups_claim {
       "~^Bearer.*" $jwt_claim_roles;
       default $jwt_claim_groups;
   }
   map $jwt_audience $jwt_aud_client {
       default  $jwt_audience;
       ~^api://(.+)$ $1;
   }
   map $http_authorization $user_email {
       "~^Bearer.*" '$jwt_aud_client@$oidc_domain';
       default $jwt_claim_email;
   }
   map $host $oidc_authz_endpoint {
       default "https://login.microsoftonline.com/{tenant_key}/oauth2/v2.0/authorize";
   }
   map $host $oidc_token_endpoint {
       default "https://login.microsoftonline.com/{tenant_key}/oauth2/v2.0/token";
   }
   map $host $oidc_jwt_keyfile {
       default "https://login.microsoftonline.com/{tenant_key}/discovery/v2.0/keys";
   }
   

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

   Example nms-http.conf

   # NGINX Instance Manager - Instance Manager configuration
   # Created for v. 2.0
   # (c) NGINX, Inc. 2021
   
   # OIDC: use email as a unique identifier
   proxy_set_header Nginx-Management-Suite-User $user_email;
   proxy_set_header Nginx-Management-Suite-Groups $groups_claim;
   proxy_set_header Nginx-Management-Suite-ExternalId $jwt_claim_sub;
   
   # OIDC authentication
   include /etc/nms/nginx/oidc/openid_connect.conf;
   

5. Verify that the configuration file does not contain any errors:

   sudo nginx -t
   

6. Reload NGINX and apply the configuration:

   sudo nginx -s reload
   

Try It Out

1. Open a web browser and go to the FQDN of your NGINX Instance Manager host. You will be redirected to the Microsoft Entra login page.
2. Enter your Microsoft Entra email address and password to log in.