Release candidate
...
Administration
SSO settings

Configuring SSO with Microsoft Entra ID (Azure AD)

13min

Before configuring SSO, make sure that in config.env the APP_URL parameter matches the current Passwork domain, example — APP_URL=https://passwork.example.com

The following Passwork server is used for the example — passwork.example.com

Adding the trust relationship of the verifying party

Authorize with Microsoft Entra ID and go to — Enterprise applications:

Document image


Open — Manage → All applications and create a New application:

Document image


In the Browse Microsoft Entra Gallery, select — Create your own application:

Document image


Perform the following steps:

  1. Fill in the Display Name (example: passwork-sp);
  2. What are you looking... — Integrate any other application you don't find in the gallery (Non-gallery)
Document image


Once created, go to Manage → Single sign-on and open SAML:

Document image


Open Basic SAML Configuration, click on Edit.

Authorize in the Passwork web interface and go to Settings and Users → SSO Settings, copy the authentication endpoint addresses from SP (Passwork) to IDP (Microsoft Entra ID):

  1. Identifier (Entity ID) — https://passwork.example.com/api/v1/sso/metadata
  2. Reply URL — https://passwork.example.com/api/v1/sso/acs
  3. Logout Url — https://passwork.example.com/api/v1/sso/sls

Configuring rules for processing requests from SP (Passwork) in IDP (Microsoft Entra ID)

Depending on the kind of user login you want in Passwork, you can customize the processing rules so that the user format can be as follows:

Please select the desired user login format in Passwork and customize.

In Set up Single Sign-On with SAML, open — Attributes & Claims:

Document image


By default, after the application is created in Microsoft Entra ID, the user format after authentication in Passwork is generated by [email protected].

No additional changes need to be made. Example of a created default statement:

Document image


Open the Unique User Identifier (Name ID) and make the following changes:

  1. Source — Transformation;
  2. Transformation — ExtractMailPrefix();
  3. Parameter 1 — Attribute;
  4. Attribute name — user.userprincipalname.
Document image


Save changes and go to Attributes & Claims.

Configuring rules for processing additional attributes to be transferred to SP

Go to Attributes & Claims and Add new claim:

  1. Adding a new optional statement for displayName:
    1. Name — displayName;
    2. Source — Attribute;
    3. Source attribute — user.displayname;
  2. Save the additional statement that was created.
Document image

  1. Adding a new optional statement for emailAddress:
    1. Name — emailAddress;
    2. Source — Attribute;
    3. Source attribute — user.mail;
  2. Save the additional statement that was created.
Document image


Configuring and completing Single Sign-On (SSO) settings in Passwork

Filling in values "User attributes"

Authenticate in the Passwork web interface, go to — Settings and Users → SSO Settings and fill in the mapping attributes:

  • Attribute for email — emailAddress;
  • Attribute for full name — displayName;

Filling in values "Identity Provider → Passwork"

In Set up Single Sign-On with SAML → Set up passwork-sp, copy the addresses of the authentication endpoints:

Document image


Open — Settings and Users → SSO Settings and fill in the values:

  • Identifier (Entity ID) — https://sts.windows.net/ba50022d-xxxx-xxxx-xxxx-1145c6c9ed97/
  • Reply URL — https://login.microsoftonline.com/ba50022d-xxxx-xxxx-xxxx-1145c6c9ed97/saml2
  • Logout URL — https://login.microsoftonline.com/ba50022d-xxxx-xxxx-xxxx-1145c6c9ed97/saml2

Filling in value "Certificate"

In Set up Single Sign-On with SAML → SAML Certificates, obtain an SSL certificate in base64 format:

Document image


Open the exported SSL certificate using Notepad, copy and place it in the appropriate field — Settings and Users → SSO Settings.

Filling in value "Advanced settings"

At the moment Passwork does not provide an algorithm for processing additional identification during SSO integration, including different types of biometrics.

In case of identification error as a result of exchange with iDP (Microsoft Entra ID), the following content should be placed in JSON format:

json


Open the authentication window in the Passwork web interface and log in via SSO to verify the correct configuration:

Document image




Updated 28 Feb 2025
Doc contributor
Doc contributor
Did this page help you?
PREVIOUS
Configuring SSO with AD FS
NEXT
Background tasks
Docs powered by Archbee