Single sign-on with Microsoft Entra ID

TL;DR

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:

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:

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:

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:

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

See also