OAuth 2.0 Configuration Guide for Microsoft Entra ID

This guide will illustrate how to setup the OAuth 2.0 Client Credential Flow using Microsoft Entra ID as the External Authorization Server.

1. Configure the OAuth resource in Microsoft Entra ID

1.1 Register resource application

1. Navigate to Microsoft Entra ID

2. Click on App Registrations

3. Click on New Registration

4. In the Register an application window:

   1. Name: Enter a name for the application (i.e. ZPE Cloud OAuth Resource)

   2. Supported account types: Select the “Single tenant only” option

   3. Click Register

1.2 Expose API on resource application

1. Click Expose an API on the left-side navigation of the app

2. Click Add next to “Application ID URI”

3. Click Save with the default value that is provided

4. Copy this value as this will be known as the AUDIENCE variable, and will be needed when setting up the Service Account in ZPE Cloud

1.3 Add Scope

1. Click on Add Scope

2. In the Add scope pane:

   1. Scope name: Enter scope name

   2. Who can consent?: Choose which users can consent to the scope (either ‘Admins and users’ or ‘Admins only’

   3. Admin consent display name: Enter the name that will be displayed in the consent screen

   4. Admin consent description: Enter the description that will be displayed in the consent screen

   5. User consent display name: Same as 2.c but for Users

   6. User consent description: Same as 2.d but for Users

   7. State: Set it as enabled

   8. Click on ‘Add scope’

1.4 Collect Microsoft Entra ID configuration needed by ZPE Cloud

1. Navigate to Overview on the left-side navigation of the app

2. Click the Endpoints tab on the Overview page

3. Copy the URL displayed in the OpenID Connect metadata document, and open the link. Locate the jwks_uri and copy its value, this will be known as the PROVIDER_URL

4. Copy the Federation metadata document, and open the link. Locate the entityID and copy its value, this will be known as the ISSUER

5. The OAuth 2.0 token endpoint (v2) will be known as TOKEN_URL

2. Create an OAuth Client in Microsoft Entra ID

2.1 Register OAuth Client Application

1. Navigate to Microsoft Entra ID

2. Click on App Registrations

3. Click on New Registration

4. In the Register an application window:

   1. Name: Enter a name for the application (i.e. ZPE Cloud OAuth Client)

   2. Supported account types: Select the “Single tenant only” option

   3. Click Register

5. Copy the Application (client) ID in the overview, this will be the CLIENT_ID used to configure the Service Account on the Cloud side

2.2 Configure the Client Secret

1. Click on Certificates & secrets on the left-side navigation of the app

2. Click on ‘New client secret’

3. On the ‘Add a client secret’ pane:

   1. Description: Enter a description for the secret

   2. Expires: Set an expiration time for the secret

   3. Click Add

4. Copy the Secret Value, this will be used for the authentication. This will be the CLIENT_SECRET

3. Create a Service Account in ZPE Cloud

Note

For OAuth 2.0, service accounts start in the default group. Upon authentication, membership is updated to match the latest group sent by your Identity Provider via Claims and Grants; otherwise, the account membership is the company's default group. See more details on the Add App Roles section below.

1. Login as an Administrator

2. Navigate to USERS::SERVICE ACCOUNTS

3. Click on Add

4. In the ‘Add’ pane:

   1. Authentication Method: OAuth 2.0

   2. Name: Enter a name for the service account (i.e. entra-id-oauth)

   3. Provider URL: PROVIDER_URL

   4. Issuer: ISSUER

   5. Audience: AUDIENCE

   6. Client ID: CLIENT_ID

   7. Click Save

1. Copy the Service Account Name, this will be known as SERVICE_ACCOUNT_NAME

2. Navigate to GROUPS::GENERAL, choose what group the service account should belong to, the group name will be known as GROUP_NAME

4. Add App Roles in the OAuth Resource application

1. Navigate to the OAuth Resource application created in previous steps

2. Click App Roles on the left-side navigation of the app

3. Click on ‘Create app role’

4. In the ‘Create app role’ pane:

   1. Display name: ‘groups’

   2. Allowed member types: Applications

   3. Value: SERVICE_ACCOUNT_NAME::GROUP_NAME

   4. Description: Service account name followed by the group name

   5. Do you want to enable this app role? Enable checkbox

   6. Click on Apply

5. Configure Application Permissions in the OAuth Client application

1. Navigate to the OAuth Client application created in previous steps

2. Click on API Permissions on the left-side navigation of the app

3. Click on Add a permission

4. Click on APIs my organization uses

5. Search for the OAuth Resource application

6. Select it

7. Select “Application permissions” on ‘What type of permission does your application require?’

8. Select the Role you added on Step 4

9. Click on Add permissions

10. Click on “Grant Admin Consent” button to grant the permissions

11. Click Yes

6. Retrieve Access Token and Access ZPE Cloud

Using the CLIENT_ID and CLIENT_SECRET, we are able to authenticate the client application with Microsoft Entra ID

curl -X POST -d "client_id={CLIENT_ID}" -d "client_secret={CLIENT_SECRET}" -d "scope={AUDIENCE}/.default" -d "grant_type=client_credentials" "{TOKEN_URL}"

If the authentication is successful, it should return something like this:

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":3599,"access_token":"{TOKEN}"}

Using the TOKEN that was returned by Entra ID, we are able to access any ZPE Cloud endpoint that is authorized by the group that the service account belongs to

curl "https://api.zpecloud.com/user?limit=1" -H "Authorization: Bearer {TOKEN}"