# 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.&#x20;

**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.&#x20;
{% 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:&#x20;

<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`.&#x20;
{% 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.&#x20;
{% 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:&#x20;

<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:&#x20;

<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.&#x20;
{% 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&#x20;

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.


---

# 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://doc.wearepatchworks.com/product-documentation/registration/sso/azure-ad-entra.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.