> 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:
## 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:
{% 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:
**Step 3**\
Paste your Azure AD / Entra `tenant ID` into the `base URL` field:
{% 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:
...you'll see that three Patchworks URLs have been generated - for example:
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:
{% 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:
**Step 2**\
Enter a `name` for this registration (we recommend `Patchworks` or similar):
**Step 3**\
Move down to the `redirect URI (optional)` section and set the `platform` to `web`:
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:
{% endhint %}
**Step 4**\
Click `register`:
**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:
{% hint style="info" %}
When copying URLs from your Patchworks provider details, click anywhere on the required link to copy it to your clipboard:
{% 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`:
**Step 2**\
Switch to Patchworks and select the `edit` option for your Azure AD / Entra provider setup:
**Step 3**\
Paste the `application (client) ID` into the `client ID` field:
**Step 4**\
Back in the Azure AD / Entra admin portal, select `certificates & secrets` from the navigation bar and then select `new client secret`:
**Step 5**\
Enter a `description` to identify this secret, set the `expiry` according to your organisational policies and click `add`:
**Step 6**\
Copy the value for the new secret:
**Step 7**\
Switch to Patchworks and paste the secret into the `client secret` field:
**Step 8**\
Toggle the `enable` option to `on`:
{% hint style="warning" %}
The SSO implementation won't be operational until this setup is enabled.
{% endhint %}
**Step 9**\
Save changes:
## **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`:
**Step 2**\
Select Microsft Graph, then delegated permissions:
**Step 3**\
Add the following `openid` permissions:
* `email`
* `offline access`
* `openid`
* `profile`
For example:
## 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:
Now log out of Patchworks and paste the `initiate sign-in URL` value into your browser - this should log straight into the Patchworks dashboard.
{% endhint %}
**Step 4**\
Click `register`:
{% 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`:
