Azure AD / Entra

Last updated 26 days ago

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.

Your Azure AD / Entra administrator requires a Patchworks account with administrator permissions to complete this setup.

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

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.

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.

Step 2 Click the Azure AD / Entra button:

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

You'll find the tenant ID for your organisation in the Azure AD / Entra admin portal, under identity | overview.

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

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.

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

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.

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.

When copying URLs from your Patchworks provider details, click anywhere on the required link to copy it to your clipboard:

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:

When copying URLs from your Patchworks provider details, click anywhere on the required link to copy it to your clipboard:

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.