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.
This guide details the setup required to integrate Patchworks with Azure AD / Entra. For clarity, the setup is documented in five stages:
Demo
The steps detailed in this guide are shown in this demonstration video:

Prerequisites
Your Patchworks user account must be associated with administrator permissions.
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 and select my company admin
from general settings:

Step 2
Click the Azure AD / Entra
button:

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

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:
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
Step 6
Optionally, you can click the edit
option here and set a specific name for this implementation:

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

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
:

The SSO implementation won't be operational until this setup is enabled.
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.
Last updated