> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/registration/sso/azure-ad-entra.md).

# Azure AD / Entra

## Introduction

With an `Azure AD / Entra` SSO integration, users log into the Patchworks dashboard from Azure AD / Entra. Your Azure AD / Entra administrator determines who has access to Patchworks and these users will see a Patchworks app in their Azure AD / Entra dashboard.

Selecting this app directs the authenticated user to the Patchworks dashboard, where they are logged in directly. Azure AD / Entra users never see or require a password to access the Patchworks dashboard.

{% hint style="info" %}
Your Azure AD / Entra administrator requires a Patchworks account with administrator permissions to complete this setup.
{% endhint %}

This guide details the setup required to integrate Patchworks with Azure AD / Entra. For clarity, the setup is documented in five stages:

* [Stage 1: Patchworks - add Azure AD / Entra provider & generate URLs](#stage-1-patchworks-add-azure-a-d-entra-provider-and-generate-urls)
* [Stage 2: Azure AD / Entra - add new app registration & apply URLs](#stage-2-azure-a-d-entra-add-new-app-registration-and-apply-urls)
* [Stage 3: Patchworks - apply Azure AD / Entra credentials & enable](#stage-3-patchworks-apply-azure-a-d-entra-credentials-and-enable)
* [Stage 4: Azure AD / Entra - API permissions](#stage-4-azure-a-d-entra-api-permissions)
* [Stage 5: Test the connection](#stage-5-test-the-connection)

## Demo

The steps detailed in this guide are shown in this demonstration video:

<figure><img src="/files/TqifOMsb5lMCO7isYPzT" alt=""><figcaption></figcaption></figure>

## Prerequisites

* Your Patchworks user account must be associated with [administrator permissions](/product-documentation/users-roles-and-permissions/roles-and-permissions-summary.md).
* You must have administrator access to your Azure dashboard.
* The Azure AD / Entra tenant ID for your organisation.

## Stage 1: Patchworks - add Azure AD / Entra provider & generate URLs

In this stage, we add a new SSO provider in Patchworks using your Azure AD / Entra `tenant ID` . This generates a set of URLs that we'll go on to apply in Azure AD / Entra.

**Step 1**\
In a new browser tab or window, log into the [Patchworks dashboard](https://app.wearepatchworks.com/) and select `my company admin` from general settings:

<div align="left"><figure><img src="/files/2oNRZkiZMlNWdnmubU6r" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
If you don't see this option, it's most likely that your user account is not associated with administrator permissions. In this case, please contact your system administrator.
{% endhint %}

**Step 2**\
Click the `Azure AD / Entra` button:

<div align="left"><figure><img src="/files/bWpR9XwJvafLKkoKvNJP" alt=""><figcaption></figcaption></figure></div>

**Step 3**\
Paste your Azure AD / Entra `tenant ID` into the `base URL` field:

<div align="left"><figure><img src="/files/1mLALgiaLvV0Arsd4lUq" alt="" width="563"><figcaption></figcaption></figure></div>

{% hint style="info" %}
You'll find the `tenant ID` for your organisation in the Azure AD / Entra admin portal, under `identity` | `overview`.
{% endhint %}

**Step 4**\
Click the `create` button to confirm.

**Step 5**\
An Azure AD / entra provider is added - click this entry:

<div align="left"><figure><img src="/files/RONrIcPS7t7Mmxgx2BNk" alt=""><figcaption></figcaption></figure></div>

...you'll see that three Patchworks URLs have been generated - for example:

<div align="left"><figure><img src="/files/7er72HbXZTJAszS6hyUv" alt=""><figcaption></figcaption></figure></div>

These URLs are needed to complete your Azure AD / Entra setup in the next stage. For reference, these are:

| Patchworks URL          | Azure AD / Entra usage                     |
| ----------------------- | ------------------------------------------ |
| Initiate sign-in url    | `Branding & properties` \| `Home page URL` |
| Callback url (auth url) | `App registration` \| `Redirect URIs`      |
| Logout url              | Not required for Azure AD / Entra          |

{% hint style="info" %}
Note that URLs shown in our screenshots are for a development environment -`dev.app.wearepatchworks.com`. Yours will always be for a production environment -`app.wearepatchworks.com`.
{% endhint %}

**Step 6**\
Optionally, you can click the `edit` option here and set a specific name for this implementation:

<div align="left"><figure><img src="/files/WH3R2mFuIClDby1k829h" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
This isn't mandatory but using specific names can be useful if you're adding multiple implementations of the same type. Remember to save your change if you do update the name.
{% endhint %}

**Step 7**\
Leave this page open and switch to your Azure AD / Entra admin portal for the next stage.

## Stage 2: Azure AD / Entra - add new app registration & apply URLs

In this stage, we register a Patchworks app in the Azure AD / Entra admin portal and apply Patchworks URLs generated for this provider at the end of the previous stage.

**Step 1**\
In your Azure AD / Entra admin portal, navigate to `identity` | `app registrations` and select the `new registration` option:

<div align="left"><figure><img src="/files/1mLZ3m2qORPCTWZbIIL6" alt=""><figcaption></figcaption></figure></div>

**Step 2**\
Enter a `name` for this registration (we recommend `Patchworks` or similar):

<div align="left"><figure><img src="/files/cDzVAnYguqLZcQMrccUk" alt=""><figcaption></figcaption></figure></div>

**Step 3**\
Move down to the `redirect URI (optional)` section and set the `platform` to `web`:

<div align="left"><figure><img src="/files/HR9DmXMHTnoBmXsb8Sdd" alt=""><figcaption></figcaption></figure></div>

For the URL, paste the `callback URL` value from your Azure AD / Entra provider setup in Patchworks.

{% hint style="info" %}
When copying URLs from your Patchworks provider details, click anywhere on the required link to copy it to your clipboard:

<img src="/files/KLSp63X5PmuvpYQ3I0Bu" alt="" data-size="original">
{% endhint %}

**Step 4**\
Click `register`:

<div align="left"><figure><img src="/files/yKSXoQBB1C74o1K7u28D" alt=""><figcaption></figcaption></figure></div>

**Step 5**\
Select `branding & properties` from the navigation menu. For the `home page URL`, paste the `initiate sign-in URL` value from your Azure AD / Entra provider setup in Patchworks:

<div align="left"><figure><img src="/files/M3AHTW1HqoqAhKbbQ8vn" alt=""><figcaption></figcaption></figure></div>

{% hint style="info" %}
When copying URLs from your Patchworks provider details, click anywhere on the required link to copy it to your clipboard:

<img src="/files/s7ezQlKvkJnd56zQHRA9" alt="" data-size="original">
{% endhint %}

**Step 6**\
Save changes.

## Stage 3: Patchworks - apply Azure AD / Entra credentials & enable

In this stage, we take client credentials generated in Azure AD / Entra, apply them to our Azure AD / Entra provider setup in Patchworks, and enable this SSO implementation.

**Step 1**\
Still in the Azure AD / Entra admin portal, select `overview` from the navigation bar, then copy the `application (client) ID`:

<div align="left"><figure><img src="/files/EKBpexcW9xAKZKbg2wf7" alt=""><figcaption></figcaption></figure></div>

**Step 2**\
Switch to Patchworks and select the `edit` option for your Azure AD / Entra provider setup:

<figure><img src="/files/dLUGEQyeSXyKTxtdnLW0" alt=""><figcaption></figcaption></figure>

**Step 3**\
Paste the `application (client) ID` into the `client ID` field:

<div align="left"><figure><img src="/files/SGXuJ6MBjhBncsREgwmz" alt=""><figcaption></figcaption></figure></div>

**Step 4**\
Back in the Azure AD / Entra admin portal, select `certificates & secrets` from the navigation bar and then select `new client secret`:

<div align="left"><figure><img src="/files/68wfNaxykaoMe6UDtGwL" alt=""><figcaption></figcaption></figure></div>

**Step 5**\
Enter a `description` to identify this secret, set the `expiry` according to your organisational policies and click `add`:

<div align="left"><figure><img src="/files/F8NytLXzOHorJXLMdnxf" alt="" width="563"><figcaption></figcaption></figure></div>

**Step 6**\
Copy the value for the new secret:

<div align="left"><figure><img src="/files/IDhj55CMHUIMDMfIFTtK" alt=""><figcaption></figcaption></figure></div>

**Step 7**\
Switch to Patchworks and paste the secret into the `client secret` field:

<div align="left"><figure><img src="/files/KC9n699tYJABc6WnVWR2" alt=""><figcaption></figcaption></figure></div>

**Step 8**\
Toggle the `enable` option to `on`:

<div align="left"><figure><img src="/files/FZxsUCC8XNCBPLlyy6dh" alt=""><figcaption></figcaption></figure></div>

{% hint style="warning" %}
The SSO implementation won't be operational until this setup is enabled.
{% endhint %}

**Step 9**\
Save changes:

<div align="left"><figure><img src="/files/2Nt9vvIZPaBK87qjpfjX" alt=""><figcaption></figcaption></figure></div>

## **Stage 4: Azure AD / Entra - API permissions**

In this stage, we define the required API permissions for the new Azure AD / Entra app.

**Step 1**\
Switch back to the Azure AD / Entra admin portal, select `API permissions` from the navigation bar, then select `add a permission`:

<div align="left"><figure><img src="/files/Asa65dBpf3w1a6ajRKrR" alt=""><figcaption></figcaption></figure></div>

**Step 2**\
Select Microsft Graph, then delegated permissions:

<div align="left"><figure><img src="/files/PWk2X906pc9qODVwz26p" alt=""><figcaption></figcaption></figure></div>

**Step 3**\
Add the following `openid` permissions:

* `email`
* `offline access`
* `openid`
* `profile`

For example:

<div align="left"><figure><img src="/files/xRODu0HXve6m6t5GM5Jx" alt="" width="563"><figcaption></figcaption></figure></div>

## Stage 5: Test the connection

To quickly test that a successful connection has been made between Patchworks and Azure AD / Entra, switch back to the Patchworks dashboard, and copy the `initiate sign-in URL` value:

<figure><img src="/files/ibcTBydrM2bG9T5TL8Ri" alt=""><figcaption></figcaption></figure>

Now log out of Patchworks and paste the `initiate sign-in URL` value into your browser - this should log straight into the Patchworks dashboard.