Azure AD OAuth2

How to connect Azure Active Directory (AD) Single Sign-On (SSO) with OAuth2 in UI Bakery

Prerequisites

• An Azure account with an active subscription.

• Administrator rights on Microsoft Entra ID (former Active Directory).

• A UI Bakery application up and running.

---

Create an Azure AD Application

Step 1: Create a New Application

1. Click on "Microsoft Entra ID" from the sidebar.

2. Choose "App registrations" and then click on "New registration".

Step 2: Configure the Application

1. Name your application.

2. Set the supported account types.

3. Set the redirect URI to https://YOUR_INSTANCE/auth/oauth2/callback

4. Click "Register" to create the application.

---

Configure OAuth2 in Azure

Step 1: Obtain Client ID and Secret

1. Go to the "Overview" tab of your newly created Azure application.

2. Note down the "Application (client) ID".

Step 2: Generate a Client Secret

1. Navigate to "Certificates & secrets".

2. Click on "New client secret" and follow the prompts.

---

Integrate Azure with UI Bakery

Step 1: Update environment variables

# Can be found in Overview tab
UI_BAKERY_OAUTH_CLIENT_ID=<your-application-id>
# do not mess it up with secret id, it should be secret value
UI_BAKERY_OAUTH_SECRET=<your-secret-value>
UI_BAKERY_OAUTH_SCOPE=User.Read
UI_BAKERY_OAUTH_EMAIL_KEY=upn
UI_BAKERY_OAUTH_GET_CLAIMS_FROM_TOKEN=true
# Replace <your-tenant-id> with Directory (tenant) ID from overview tab
# For multitenant integration use "common" instead of tenant ID
UI_BAKERY_OAUTH_AUTH_URL=https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/authorize
UI_BAKERY_OAUTH_TOKEN_URL=https://login.microsoftonline.com/<your-tenant-id>/oauth2/v2.0/token
UI_BAKERY_BRANDING_AUTH_SSO_BTN_TEXT=Login with Microsoft

Step 2: Restart your UI Bakery instance

Docker compose setup may be restarted with the following command:

docker compose down && docker compose up -d

---

UI Bakery can read group and role claims from either the OAuth access token or the ID token.

• Use the access token when it contains the required claims and is intended for UI Bakery.

• Use the ID token when it contains the required claims but the access token is issued for Microsoft Graph or another downstream API.

To read claims from the ID token, configure Microsoft Entra ID to include the required group or role claims in the ID token, then set:

UI_BAKERY_OAUTH_GET_CLAIMS_FROM_TOKEN=idToken
UI_BAKERY_SSO_ROLE_CLAIM=groups

In this mode, UI Bakery uses the ID token for user identity and role synchronization. The Microsoft Graph access token remains available for downstream requests

Set up group claims for role synchronization (Optional)

If you need to enable role synchronization, then groups claim must be included in the access token. To achieve this, follow these steps:

1. Add groups claim in "Token configuration" section. Select groups types according to your requirements.

2. In the "Expose an API" section, configure Application ID URI with default value and create a new scope. Set the scope name to groups and configure the necessary settings

3. In the "API permissions" section, click Add a permission, select the APIs my organization uses tab, and search for the previously created scope by typing your app registration name or id.

4. Update the following environment variables and then restart your instance:

   UI_BAKERY_SSO_ROLE_CLAIM=groups
   # replace api://YOUR_APP_ID with "Application ID URI" from "Expose an API" section
   UI_BAKERY_OAUTH_TOKEN_URL_ADDITIONAL_PARAMS={"scope": "api://YOUR_APP_ID/groups"}

---

Test the Integration

1. Attempt to log in to your UI Bakery application with `Login with Microsoft` button.

2. You should be redirected to the Azure AD login page.

3. After successful authentication, you should be redirected back to your UI Bakery application.

---

Troubleshooting

If you encounter issues during the integration, consider checking the following:

1. Make sure the Client ID and Client Secret are correctly configured in UI Bakery.

2. Validate the Redirect URI settings on both Azure and UI Bakery.

3. Check Azure logs for authentication errors.