OIDC - Microsoft Entra (Azure AD)

Notes

• OpenID Connect towards Microsft Entra was introduced in 6.5.0.
• OpenID Connect towards Microsft Entra with group/role-assignment was introduced in 6.6.0.

Introduction

The Varnish Controller supports OpenID Connect logins through Keycloak, but also direct login with OpenID Connect (OIDC) towards Microsoft Entra (Azure Active Directory). Direct OIDC login requires configuration of Microsoft Entra to retrieve the right URLs and details for the Varnish Controller.

Creating an organization

Before we start configuring in Microsoft Entra, we need to create an organization in the Varnish Controller. As a system administrator navigate to Organizations in the left hand side of the screen. Create a new organization (or select an existing one).

For now give the organization a name and hit Create. The organization name is used in the login screen later when your users are logging in into the Varnish Controller. After creation, you are redirected to the edit page of this organization. We need to find the ID of the organization, this is used in the next step.

Setting up Microsoft Entra (Azure AD)

Creating our application

Login at the Azure Portal and navigate to Microsoft Entra ID. In the left hand menu under the Manage item navigate to App Registrations. At this page we create a new registration:

1. We need to give our application a name, give it a distinctive name to identify later what application this is used for. In our example we use Varnish Controller - Login Example.
2. We use the Single tenant option for authentication as we only want users from our Directory to be able to login.
3. We need to select Web in the dropdown and enter a redirect URL for our application, enter the following URL: <API_GW>/api/v1/orgs/<ORG_ID>/callback. Replace <API_GW_HOST> with the public URL of the API-GW and <ORG_ID> with the ID of the organization that will be used for authentication.

You will be redirected to your newly created Application.

Changing Authentication settings

1. Navigate under Manage to Authentication
2. Click on Add URI
3. Enter the following URL: <UI_HOST>/api/v1/orgs/<ORG_ID>/callback. Replace <UI_HOST> with the public URL of the API-GW and <ORG_ID> with the ID of the organization that will be used for authentication.
4. Under Implicit grand and hybrid flows we need to check the checkbox for Access tokens
5. Press the Save button

Creating a new scope

For the Varnish Controller to be able to parse information out of the access token we need to add our own scope. If this step is skipped, the Varnish Controller is not able to parse the authentication details and will be unable to create the IDP account.

1. Navigate under Manage to Expose an API
2. Click on Add a scope
3. A window will be shown on the right
4. Press Save and continue

1. We will give our scope the name Varnish-Controller
2. At the question Who can constent?, select Admins and users
3. In the next field we enter Varnish Controller access
4. In the next field we enter Allows the app to have Varnish Controller access
5. The State should be Enabled
6. Press Add scope at the bottom of the screen

Configuring API permissions

Next we need to setup the API permissions to allow the Varnish Controller to refresh the authentication tokens and retrieve the required information of the user trying to login.

1. Navigate under Manage to API permissions
2. Press on Add a permission
3. Click on Microsoft Graph

Adding OpenID Connect permissions

1. Click on Delegated permissions
2. Enable all checkboxes for OpenId permissions; email, offline_access, openid and profile should be enabled.
3. Click Add permissions at the bottom of the screen

Adding Varnish-Controller permission

1. Click on Add a permission again
2. This time we go to the tab My APIs
3. Click on the Application you have created, in our case Varnish Controller - Login Example

1. Select the Varnish-Controller permission
2. At the bottom of the screen press Add permissions

Token configuration

1. Navigate under Manage to Token configuration
2. Click on Add optional claim
3. Select the Access for the token type
4. Enable email and preferred_username
5. At the bottom of the page click on Add

Creating the Client Secret

The Varnish Controller will communicate with the Azure API, this API connection needs a Client Secret to allow the Varnish Controller to make authentication requests. This client secret is only shown once! Store it somewhere safe!

1. Navigate under Manage to Certificates & secrest
2. In the tab Client secrets click on New client secret
3. Enter a description fo the client secret, on our case Varnish Controller
4. Select an expiry date that accommodates your internal policies. After this period a new client secret should be manually generated and configured in the Varnish Controller in order to support OIDC authentication.
5. At the bottom of the page, click on Add
6. Copy the value of the client secret in the Value column. This Value is only shown once!

Retrieving the Client ID and OpenID Connect endpoint

Now it is time to retrieve the final details of our connection. We have the client secret from the previous step, now we need the client ID and the OIDC manifest URL.

1. Navigate to Overview
2. Copy the Application (client) ID and save it
3. Click on Endpoints
4. Copy the OpenID Connect metadata document URL and save it

Configuring the Organization

Login into the Varnish Controller again and edit the organization that we created in the beginning.

1. Open the IDP Configuration
2. As the Base URL enter the OpenID Connect metadata document URL we just copied
3. As the Client ID enter the Application (client) ID we just copied
4. As the Client Secret enter the Client Secret we generated previously
5. The scopes should be filled with offline_access <CLIENT_ID>/.default. Replace the <CLIENT_ID> with the Application (client) ID we just copied.
6. Click on Save

Configure Roles (Optional)

A group’s UID can be mapped to a role within the controller.

Essential Reads

• Introduction to Roles.
• Introduction to IDP configuration for Roles.

UID Configuration

In Entra, access is typically configured using Groups. The first step is to locate the UID so it can be properly configured within the controller.

The object ID for the group needs to be used in the UID configuration. Create the group if it doesn’t already exist.

1. Create Group (Optional)

If a group doesn’t already exist, it needs to be created.

2. Retrieve the Object ID(UID)

Save the Object ID for configuration within the controller, once everything is setup.

3. Apply Group Claims

Enabling group claims allows the controller to retrieve UIDs associated with the groups key.

1. Navigate to Token Configuration
2. Add Optional Group Claims

4. Configure

Once the UID is identified, the next step is to configure it within the controller. In the IDP settings, there are three key fields:

1. Identifier - Specifies which claim key the controller should use to locate the UID.
2. UID Role Mapping - Defines how the UID is mapped to specific roles within the system.
3. Require role - This ensures that a user can log in only if their UID matches an entry in the role configuration. Otherwise the user will receive a basic permission set.

The UID needs to be mapped to a specific role within the controller.

Now everything should be configured!

Logging in with Microsoft Entra

Ensure you are not already logged in into the Varnish Controller.

1. On the login screen, click on Log in with identity provider.
2. Enter the name of the organization we have configured for the Microsoft Entra login.
3. Click on Continue, this will open a new window.

A new window will appear from Microsoft. Enter your Microsoft Entra login details and login. Microsoft will ask for consent for the permissions we have configured (The Varnish-Controller access, the email address and the preferred_username). Accept these permission requests. The user is now successfully created and authenticated through Microsoft Entra.