# Azure AD OAuth2

## 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".

<figure><img src="https://837703843-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUX6zPRMFFK0yrTghj7cY%2Fuploads%2Fgit-blob-efe4e2d3a06702d6262904b14b8f92e5caf87cb3%2Fimage%20(7)%20(1).png?alt=media" alt=""><figcaption></figcaption></figure>

### 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.

<figure><img src="https://837703843-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUX6zPRMFFK0yrTghj7cY%2Fuploads%2Fgit-blob-b9e107af4a7e584fddeabc8996c3f9ac1ac0cdb6%2Fimage%20(153).png?alt=media" alt=""><figcaption></figcaption></figure>

***

## 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

<pre class="language-bash"><code class="lang-bash"><strong># Can be found in Overview tab
</strong><strong>UI_BAKERY_OAUTH_CLIENT_ID=&#x3C;your-application-id>
</strong># do not mess it up with secret id, it should be secret value
UI_BAKERY_OAUTH_SECRET=&#x3C;your-secret-value>
UI_BAKERY_OAUTH_SCOPE=User.Read
UI_BAKERY_OAUTH_EMAIL_KEY=upn
UI_BAKERY_OAUTH_GET_CLAIMS_FROM_TOKEN=true
# Replace &#x3C;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/&#x3C;your-tenant-id>/oauth2/v2.0/authorize
UI_BAKERY_OAUTH_TOKEN_URL=https://login.microsoftonline.com/&#x3C;your-tenant-id>/oauth2/v2.0/token
UI_BAKERY_BRANDING_AUTH_SSO_BTN_TEXT=Login with Microsoft
</code></pre>

### Step 2: Restart your UI Bakery instance

Docker compose setup may be restarted with the following command:

```
docker compose down && docker compose up -d
```

***

## Set up group claims for role synchronization (Optional)

If you need to enable [role synchronization](https://docs.uibakery.io/on-premise/sso/role-syncronization), 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:

   ```bash
   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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.uibakery.io/on-premise/sso/openid/azure-ad-oauth2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.