# Single sign-on with Microsoft Entra ID

> Page: https://docs.plotwork.dev/single-sign-on-entra-id. Index of every page: https://docs.plotwork.dev/llms.txt

Connect an Enterprise organisation to Microsoft Entra ID (formerly Azure Active Directory) with OpenID Connect or SAML 2.0. Prove your email domain in Plotwork first, as the [single sign-on guide](https://docs.plotwork.dev/single-sign-on.md) describes.

## TL;DR

| Plotwork field | Where it comes from in Entra ID |
|---|---|
| Issuer URL | `https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0` |
| Client ID | The app registration's Overview, Application (client) ID |
| Client secret | Certificates & secrets, Client secrets, the Value column (not the Secret ID) |
| Redirect URI to give Entra ID | `https://api.plotwork.dev/auth/sso/callback`, as a Web platform redirect |
| SAML: Identifier (Entity ID) and Reply URL to give Entra ID | The Entity ID and the ACS URL on Plotwork's Single sign-on tab |
| SAML: Metadata URL | The enterprise application's Single sign-on page, SAML Certificates, App Federation Metadata Url |

## 1. Register the app

1. In the Microsoft Entra admin center, open Identity, then Applications, then App registrations, and press New registration.
2. Fill in the form:

| Entra ID field | Value |
|---|---|
| Name | `Plotwork` |
| Supported account types | Accounts in this organizational directory only (single tenant) |
| Redirect URI | Platform Web, address `https://api.plotwork.dev/auth/sso/callback` |

3. Press Register.

## 2. Make a client secret

1. In the app registration, open Certificates & secrets, then Client secrets, and press New client secret.
2. Give it a description and an expiry, and press Add.
3. Copy the Value at once: Entra ID shows it only now. The Secret ID is not the secret.

Note the expiry. When the secret expires, sign-in stops; make a new one and paste it into Plotwork before then.

## 3. Send the address in the ID token

1. Open API permissions and check that Microsoft Graph has the delegated permissions `openid`, `email` and `profile`. Add the ones that are missing, and grant admin consent.
2. Open Token configuration, press Add optional claim, choose ID as the token type, tick `email`, and press Add.

Entra ID puts the address in the `email` claim only for a person whose account has a mail address. An account with no mailbox has none, so for a token from your tenant with no `email` claim, Plotwork reads the user principal name instead: the `upn` claim, then `preferred_username`. Either way the address must be on a domain your organisation verified in Plotwork.

## 4. Copy the values into Plotwork

1. On the app registration's Overview, copy the Application (client) ID and the Directory (tenant) ID.
2. In Plotwork, open your organisation's Single sign-on tab and fill in Identity provider:

| Plotwork field | Value |
|---|---|
| Issuer URL | `https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0` |
| Client ID | The Application (client) ID |
| Client secret | The Value you copied |

3. Press Save provider, then turn on Sign in with single sign-on.

Plotwork refuses the shared issuers `/common`, `/organizations` and `/consumers`: they would let any Microsoft tenant's people in. Use your own tenant's issuer, as above.

## Or connect with SAML 2.0

1. In the Microsoft Entra admin center, open Identity, then Applications, then Enterprise applications, press New application, then Create your own application. Name it `Plotwork`, choose Integrate any other application you don't find in the gallery (Non-gallery), and press Create.
2. Open Single sign-on and choose SAML.
3. In Plotwork's Single sign-on tab, choose SAML 2.0 under Identity provider, then edit Basic SAML Configuration in Entra ID:

| Entra ID field | Value |
|---|---|
| Identifier (Entity ID) | The Entity ID from Plotwork. Make it the default. |
| Reply URL (Assertion Consumer Service URL) | The ACS URL from Plotwork |
| Sign on URL, Relay State, Logout Url | Leave empty |

4. Under Attributes & Claims, edit Unique User Identifier (Name ID): set Name identifier format to Email address and Source attribute to `user.mail`. If your people's mail is empty and their user principal name is their address, use `user.userprincipalname` instead.
5. Under SAML Certificates, keep Signing Option at Sign SAML assertion and Signing Algorithm at SHA-256, and copy the App Federation Metadata Url.
6. In Plotwork, paste it under Metadata URL, leave Email attribute empty, and press Save provider. Then turn on Sign in with single sign-on.
7. Under Users and groups, assign the people or groups who should sign in.

If you keep a Name ID that is not an address, put `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` under Email attribute in Plotwork: Entra ID sends the mail address in that claim by default.

Entra ID rotates the signing certificate before it expires. When it does, save the provider in Plotwork again with the same metadata URL.

## Provisioning with SCIM

1. In Plotwork's Single sign-on tab, under Provisioning with SCIM, press Make token and copy the token and the SCIM base URL.
2. In the Microsoft Entra admin center, open the Plotwork enterprise application (for an OIDC app registration, make a Non-gallery enterprise application for provisioning), then Provisioning, and press Get started.
3. Set Provisioning Mode to Automatic and fill in Admin Credentials:

| Entra ID field | Value |
|---|---|
| Tenant URL | The SCIM base URL from Plotwork |
| Secret Token | The token from Plotwork |

4. Press Test Connection, then Save.
5. Under Mappings, open Provision Microsoft Entra ID Users and check that `userPrincipalName` (or `mail`) maps to `userName` and `Switch([IsSoftDeleted], , "False", "True", "True", "False")` maps to `active`. Remove mappings to attributes Plotwork does not keep if you like: it ignores them.
6. Under Users and groups, assign the people and groups to provision, set Provisioning Status to On, and save. Entra ID runs a cycle about every 40 minutes; Provision on demand runs one person at once.
7. In Plotwork, choose the role each pushed group gives under Groups and roles.

## Troubleshooting

| What you see | What to check |
|---|---|
| "The issuer could not be used: the issuer names every tenant" | Replace `common` or `organizations` in the issuer with your Directory (tenant) ID. |
| "Your address is not on a domain your organisation verified" | The person's mail address in Entra ID, or their user principal name when they have no mail address, is on another domain. Check the optional claim in step 3. |
| "Your identity provider sent a sign-in Plotwork could not trust" | The Client ID in Plotwork is not this app's, or the issuer is another tenant's, or the token named no address at all. Check that `openid`, `email` and `profile` are granted in step 3. |
| Sign-in stopped working one day | The client secret expired. Make a new one and save it in Plotwork. For SAML, the signing certificate rotated: save the provider again with the same metadata URL. |
| Provisioning logs show 400 for a user | The `userName` Entra ID sends is not an address on a domain you verified in Plotwork. Map `mail` to `userName`, or verify the domain. |
| "Your identity provider sent a sign-in Plotwork could not trust" with SAML | The Identifier or the Reply URL is not Plotwork's, or token encryption is on under Token encryption. Turn it off. |

## See also

| Page | Why |
|---|---|
| [Single sign-on](https://docs.plotwork.dev/single-sign-on.md) | Domains, the switches, Require single sign-on and the way back in |
| [Single sign-on with Okta](https://docs.plotwork.dev/single-sign-on-okta.md) | The same for Okta |
| [Single sign-on with Google Workspace](https://docs.plotwork.dev/single-sign-on-google-workspace.md) | The same for Google Workspace |