Using Keycloak as provider for Azure AD SSO authentication & role authorization: Part 1 SSO Integration

During one of my recent assignments, there was a requirement where a Next JS based UI application needed
- to provide a Single Sign On interface using Azure AD but using Keycloak as the IDP tool.
- to be able to extract roles from the Azure AD groups to which the login user belongs to (covered here)

This article will cover how Keycloak can be used for SSO with Azure AD. The second part of this series will cover how Keycloak roles can be mapped with Azure AD groups.

Why this article?

While implementing this solution, I found there was scarce information depitcing exact steps on how to setup Keycloak IDP to achieve this — both in Keycloak documentation and in general — so hopefully this help others who wants to achieve similar goals.

Scenario Overview

The above diagram shows the roles and responsibilities for each component / actor involved.

Assumptions

1. One has an active Azure account with email id registered
2. One has an active Keycloak setup as administrator
3. Keycloak version 24.x

Keycloak SSO with Azure AD

Configure Azure App Registration

• Login to Azure portal and search for “App registrations”
• Here we need to create a new app registration for “Flow Management portal” and click on “New registration”

• Fill out the necessary details as below and click on “Register”.
  - Name: User-facing display name for this application
  - Supported account types: Accounts in this organizational directory only (Default Directory only — Single tenant)
  - Redirect URI: Choose “Web” and leave the URI field blank. This comes later from the Keycloak setup.

• On the app registration details page, note the of the Application (client) ID as this will be required in Keycloak configuration.

• Next, we need to create a client secret to use this client from Keycloak. For that, click on “Certificates and secrets” and add “new client secret”. Make sure to copy the secret value and note it down. It will be used later in the Keycloak setup.

• Next, we go to the registered app and click “Endpoints” (as highlighted in the snapshot below). Next, copy and note down the URL for the “OpenID Connect metadata document”.
  This is used to import openID config later in Keycloak.

• Next we need to set up Keycloak to use the above app registration (covered in the next section)

Setup Keycloak to use Azure App Registration

For our usecase, Keycloak is the authenticating server, and Azure AD is the identity provider.

Keycloak provides two ways for user authentication via identity provider:

• Identity Providers: The users are redirected to the identity provider’s authentication page, e.g. login with Microsoft Single Sign-on.
• User Federation: Users from the identity provider are copied and synced to Keycloak, which currently only supports Kerberos and LDAP providers. This option could be used when users need to be replicated in Keycloak.

We will consider Identity Providers configuration using OpenID Connect.

• First, let’s create a realm for this purpose and choose after the realm is selected.

• Next, we are going to create the OpenID Connect configuration with the Azure App Registration details already created above.

• In the detail page, fill out the details as required below:
  * Enter the alias of your choice.Enable Use discovery endpoint, if not already enabled
  * Input the Discovery URL from Azure (copied before) into the Discovery endpoint
  * Input the Client ID. This is the application (client) ID copied from Azure app registration.
  * Input Client Secret. This is the application secret copied from Azure app registration

• Next, copy the redirect URL. This needs to be updated in the Azure app registration.
• Go back to the Azure registered app, and click “Add a Redirect URL” → “Add a platform” → “Web”.
  Input the redirect URL in the required field and click Configure.

• To make sure, this integration works, we need to see whether the default account URL redirects to Azure AD SSO as we configured.
  For this, go to Keycloak interface, choose your realm and go to “Clients” from the left panel and click on “account-console”.

• Click on Settings tab
  * for “Valid Redirect URIs”, fill the appropriate redirect URI for your UI app
  * for “Web origins”, fill * for all origins (for production, use private secured client network)
  * click Save.

NOTE: make sure that in your realm you have included the manage-account role.

Verification of Keycloak SSO integration with Azure AD

• To verify this Keycloak-Azure SSO integration works, click on the “account-console” URL and it should take you to below page:

• Click on “Azure AD SSO” button and it will bring you to this Microsoft login page.

• Login with you Microsoft SSO credentials and it will ask for your permission to access the app for the first time.

• After clicking on “Accept”, you should be able to see below profile page, confirming this integration works successfully.

Final part of this article covers Azure AD groups to Keycloak roles claims and can be found here.