Single sign-on

TL;DR

1. Prove your email domain

1. In the Single sign-on tab, under Email domains, type the domain your members use, such as acme.com, and press Add domain.
2. Plotwork shows a TXT record to publish:

3. Publish it at your DNS host, then press Verify. Plotwork looks it up through Cloudflare's DNS over HTTPS. A record that is not found yet is not an error: DNS can take a few minutes to change, so press Verify again later.

A domain can be verified by one organisation only. Public mail domains such as gmail.com and outlook.com cannot be added. You can add up to 20 domains, and leaving the record in place after it is verified is fine but not needed.

2. Register Plotwork at your provider

Under Identity provider, choose the protocol your provider app speaks: OpenID Connect or SAML 2.0. Saving the other protocol later replaces the provider and turns single sign-on off until you turn it on again, so nobody is held to a provider that has not been tried.

With OpenID Connect

Register a web application at your provider. The tab shows the redirect URI to give it:

Then copy three values back into the tab under Identity provider:

Press Save provider. Plotwork checks the issuer before it saves anything: the address must be HTTPS, the provider must offer the authorization code flow with PKCE and sign ID tokens with RS256 or ES256, and the issuer must be your own tenant. An issuer shared by every tenant, such as Microsoft's /common, is refused. If a check fails, the tab says which one.

With SAML 2.0

Create a SAML app at your provider. The tab shows three values for it, each with a copy button. They are your organisation's own, so an assertion made for another organisation never signs anyone in to yours:

Set the provider to send the person's email address as the NameID, to sign the assertion (or the whole response) with SHA-256, and not to encrypt the assertion. Then give Plotwork the provider's metadata, either its address under Metadata URL or the XML pasted under Or paste the metadata XML, and press Save provider. Plotwork reads the metadata before it saves anything: it needs the provider's entity ID, a sign-in URL on the redirect binding, and an RSA signing certificate of at least 2048 bits. If a check fails, the tab says which one.

When the NameID is not the address, such as an opaque persistent ID, put the name of the attribute that carries the address under Email attribute. Leave it empty to read the NameID.

When your provider rotates its signing certificate, save the provider again with the same metadata URL (or the new XML). The tab lists each certificate with its fingerprint and expiry date.

Plotwork accepts only sign-ins it started: a response must answer the request Plotwork sent, in the same browser, within ten minutes. Starting from the app tile at your provider (IdP-initiated sign-in) is refused; people start from Plotwork's sign-in page.

Step-by-step pages for the three providers most teams use, for both protocols:

3. Turn it on

The Sign-in rules section has three switches and a role:

Turning the connection off, removing the provider, or removing the last verified domain turns Require single sign-on off at the same moment, so nobody is locked out by a half-finished set-up.

4. How people sign in

1. On the sign-in page, a person types their work address.
2. If the address is on a verified domain of an organisation with single sign-on on, the page offers Continue with single sign-on, with Email me a code instead beside it.
3. Their browser goes to your provider, they sign in there, and they come back signed in to Plotwork.

The first time, Plotwork links the provider's account to the Plotwork account with the same address, or makes one. After that the link wins: if the person's address changes at the provider, they still sign in to the same Plotwork account.

If a sign-in fails, the sign-in page says why in words:

5. Require single sign-on and the way back in

With Require single sign-on on, a member or an admin whose address is on a verified domain and who signed in with an emailed code sees "Single sign-on required" on the organisation's pages, with a button that signs them in through your provider and brings them back.

The owner is never held to it. If your provider is down or set up wrongly, the owner signs in with an emailed code, opens the Single sign-on tab and fixes it. Every such sign-in is recorded in the audit log as a break-glass sign-in, so your security team sees it.

API keys and connected agents are not held to Require single sign-on: they reach the organisation through membership, which is checked on every call. Removing a member stops every key of theirs at once.

6. What is recorded

Every change and every sign-in goes to the organisation's audit log:

7. Provisioning with SCIM

SCIM lets your identity provider manage your members for you. Set it up in the Provisioning with SCIM section of the tab:

Then turn provisioning on at your provider for creating, updating and deactivating users, and for pushing groups. Step-by-step pages for Okta and Microsoft Entra ID are below.

Under Groups and roles, choose the role each group gives: Admin, Member, Reader or No role. While no group gives a role, SCIM never changes anyone's role. Once one does, each provisioned person's role follows their groups: the highest role their groups give, or Member when none of theirs gives one. The owner is never changed or removed.

Plotwork supports filtering users by userName and externalId, groups by displayName, paging with startIndex and count, and PATCH. It does not support bulk operations, sorting or password changes.

See also