Set up OIDC for automated services using Microsoft Entra

Overview

Complete the steps in this guide to secure Instance Manager with OpenID Connect (OIDC) using the client credential code flow method and Microsoft Entra (AD) as the identity provider for use with automation, such as in CI/CD pipelines.

Before you begin

First, secure Instance Manager with OpenID Connect (OIDC) using Microsoft Entra (AD) as the identity provider. To do so, complete the steps in the Set up OIDC Authentication with Microsoft Entra guide. After following the steps in that guide, you’ll have a registered application (named “Instance Manager” in the guide’s example) in Microsoft Entra and a client ID and secret that you can use 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.
On the left navigation menu, in the Manage section, select App registrations.
Select New registration.
Complete the following:
- In the Name box, type the name of the application. For example, “Automation”.
- In the list of account types, select Account in this organizational directory only.
- Leave the Redirect URI section unchanged (empty).
Select Register.
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

Expose the Application API

On the left navigation menu, in the Manage section, select Expose an API.
Select Set next to Application ID URI.
Optionally, in the Application ID URI box, type a friendly URI for the application. You can leave the default value (Application ID).
Select Save.

Create an App Role

On the left navigation menu, in the Manage section, select App roles.
Select Create app role.
Complete the new role form. You should use the details from an existing F5 NGINX Management Suite user group, such as the one created in the Create User Groups in Instance Manager step. For example :
- In the Display name box, type a name for the role. For example, “Admin”.
- In the Allowed member types section, select Applications.
- In the Value box, type a value for the role. This needs to match the user-group in NGINX Management Suite. For example, the ID of the name group.
- In the Description box, type 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 in the Before you begin section. (In the example, it was named “Instance Manager”).
On the left navigation menu, in the Manage section, select API Permissions.
Select Add a permission.
In the Request API permissions section, select My APIs.
From the list of APIs, select the app name you created in the Register a New Application for Your Automation steps. (In the example, it was named “Automation”).
In the Application permissions section, select the role you created in the Create an App Role steps. (In the example, it was named “Admin”).
Select Add permissions.

Note:
If the permission created in the preceding step is not granted, try contacting the Microsoft Entra administrator of your tenant about granting it.

Configure NGINX OIDC to use Microsoft Entra IdP

Complete the steps in the Set Up NGINX Plus to Interact with the Identity Provider topic. Please note that you might have already completed these steps as part of the Before you begin section of this guide.

Additionally, you will need to complete the following steps:

Add the domain of your Microsoft Entra tenant to the /etc/nms/nginx/oidc/openid_configuration.conf file. For example, to use the f5.com domain for your Microsoft Entra tenant, update the oidc_domain value in the file as follows:
```
...
map $host $oidc_domain {
    SERVER_FQDN OIDC_DOMAIN;
    # replace with OIDC specific setting
    default "f5.com";
}
...
```

In the same file, uncomment the map sections corresponding to OIDC with Microsoft Entra:

...
# 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, for example:
```
https://login.microsoftonline.com/<your-azure-tenant-id>/oauth2/v2.0/token
```
Provide the following keys:
- client_id: The client ID of the application you created in the Before You Begin section. In the example, we used “Instance manager”.
- client_secret: The client secret of the same application.
- scope: The scope of the application. For example, api://<client ID of app registration with app role(Admin)>/.default.
- grant_type: Use client_credentials.

The response contains an access token. Running a jwt decoder on the access token will return something 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 contains the role ID of the role you created in the Create an App Role steps. (In the example, it was named “Admin”).

By default, tokens expire after 60 minutes. To configure the expiration please see the Microsoft Entra Configurable token lifetimes in the Microsoft identity platform documentation.

Access NGINX Management Suite API Using the Access Token

To access the NGINX Management Suite API using the access token, you must send the access 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

Replacing <access token> with the access token you obtained in the Get an Access Token from Microsoft Entra steps and <nms-ip> with the IP address of your NGINX Management Suite instance.

Last modified August 22, 2024