Automate OIDC with Microsoft Entra

Overview

This guide explains how to secure NGINX Instance Manager with OpenID Connect (OIDC) using the client credentials flow and Microsoft Entra as the identity provider. You can use this setup for automation services, such as in CI/CD pipelines.

Before you begin

Required steps
Before proceeding, first secure NGINX Instance Manager with OpenID Connect (OIDC) using Microsoft Entra as the identity provider. Complete the steps in the Set up OIDC authentication with Microsoft Entra guide. Afterward, you’ll have a registered application (e.g., “NGINX Instance Manager”) in Microsoft Entra, as well as a client ID and secret to configure automation.

Configure Azure

Register a new application for your automation

Log in to the Azure portal.
Select Microsoft Entra from the list of Azure services.
In the left navigation menu, under Manage, select App registrations.
Select New registration.
Complete the following:
- In the Name field, enter the name of the application (e.g., “Automation”).
- Select Accounts in this organizational directory only for account types.
- Leave Redirect URI blank.
Select Register.
On the confirmation page, note the following information for later use:
- Application (client) ID
- Directory (tenant) ID

Expose the application API

In the left navigation menu, under Manage, select Expose an API.
Select Set next to Application ID URI.
Optionally, enter a friendly URI for the application, or leave the default value.
Select Save.

Create an app role

In the left navigation menu, under Manage, select App roles.
Select Create app role.
Fill in the role details. Use the information from an existing user group in NGINX Instance Manager, such as from the Create user groups in Instance Manager step:
- In the Display name field, enter a role name (e.g., “Admin”).
- In Allowed member types, select Applications.
- In the Value field, enter the value for the role. This must match the user group in NGINX Management Suite.
- Provide a description for the role.
Select Save.

Assign the app role to the application

On the App registrations page, select the first application you created (e.g., “Instance Manager”).
In the left navigation menu, under Manage, select API permissions.
Select Add a permission.
In the Request API permissions section, select My APIs.
Select the app name you created for automation (e.g., “Automation”).
Under Application permissions, select the role you created earlier (e.g., “Admin”).
Select Add permissions.

Note:
If the permission is not granted, contact your Microsoft Entra administrator to approve it.

Configure NGINX OIDC to use Microsoft Entra as the IdP

Complete the steps in the Configure NGINX Plus with Microsoft Entra as Identity Provider topic. Note that you may have already completed some of these steps in the Before you begin section of this guide.

Additionally, complete the following steps:

Add your Microsoft Entra tenant domain to the /etc/nms/nginx/oidc/openid_configuration.conf file. For example, if your tenant domain is f5.com, update the oidc_domain setting like this:
```
...
map $host $oidc_domain {
    SERVER_FQDN OIDC_DOMAIN;
    # replace with OIDC specific setting
    default "f5.com";
}
...
```

Uncomment the relevant OIDC sections in the /etc/nginx/conf.d/nms-http.conf file:

...
# 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;
}
...

Get an access token from Microsoft Entra

Send a POST request to the Microsoft Entra token endpoint:

https://login.microsoftonline.com/<your-azure-tenant-id>/oauth2/v2.0/token

Include the following in your request body:
- client_id: The client ID of the application you created.
- client_secret: The client secret for the application.
- scope: The application scope (e.g., api://<client-id>/.default).
- grant_type: Use client_credentials.

The response will contain an access token. Decoding the token should give you a result similar to:

Header:

{
    "alg": "RS256",
    "x5t": "-KI3Q9nNR7bR0fxmeZ0XqbHZGew",
    "kid": "-KI3Q9nNR7bR0fxmeZ0XqbHZGew"
}

Payload:

{
    "aud": "api://f834b49c-a56e-4fde-9caa-641-bOc26fb8a",
    "iss": "https://sts.windows.net/d3dfd2f-6a3b-40d1-9beO-b8f327d81c50/",
    "iat": 1593640000,
    "nbf": 1593640000,
    "exp": 1593643600,
    "aio": "42+E2ZYHBXei7VKmxxHzn7h1",
    "appid": "374cc05e-aaa1-408f-9348-a83d6b4d8ea6",
    "appidacr": "1",
    "idp": "https://sts.windows.net/d3dfd2f-6a3b-40d1-9beO-b8f327d81c5/",
    "oid": "2db3db56-f58b-455a-9ff5-4e1e8b17a171",
    "rh": "0.AQABA_893Ttq0UCb4L0QwQ-DJ9QgcILmngha-4Q",
    "roles":    [
        "28a3143e-4217-485e-9fOf-092abc01239b01"
    ],
    "sub": "2db3db56-f58b-455a-9ff5-4e1e8b17a1a71",
    "tid": "dd3dfd2f-6a3b-40d1-9bee-bfaqw27d81c5e",
    "uti": "EmqiFiTC-kACZqN5vrKd8AQ" ,
}

Note:
The roles claim will contain the role ID of the role you created in the Create an app role step.

Access NGINX Management Suite API using the access token

To access the NGINX Management Suite API using the access token, send the token in the Authorization header of the request as a Bearer token. For example, using curl:

curl -v -k --header "Authorization: Bearer <access-token>" https://<nms-ip>/api/platform/v1/userinfo

Replace <access-token> with the token you obtained from Microsoft Entra and <nms-ip> with the IP address of your NGINX Management Suite instance.

Last modified November 8, 2024