Single Sign-On
Single sign-on lets people sign in to the console through your organisation’s identity provider instead of a Plenary password. Plenary supports one provider per instance, connected over OpenID Connect (OIDC) or SAML 2.0. The provider proves who the person is; Plenary matches that to a user account, or creates one, and issues its ordinary session. Roles and super user status stay in Plenary. Single sign-on is included in every license and on Plenary Cloud; on the Free plan it is not available.
How a sign-in works
Section titled “How a sign-in works”- The sign-in page shows Continue with single sign-on when a connection is enabled. Clicking it sends the browser to
GET /api/v1/auth/sso/oidc/start(or…/saml/start), which records a ten-minute sign-in attempt and redirects to your provider. - The person signs in at the provider, including whatever second factor the provider enforces. Plenary never asks for its own one-time code on a single sign-on.
- The provider sends the browser back to Plenary:
GET /api/v1/auth/sso/oidc/callbackfor OIDC, or an HTTP POST to/api/v1/auth/sso/saml/acsfor SAML. Plenary verifies the response, finds or creates the account, and redirects to the console with a one-time login code. - The console exchanges the code at
POST /api/v1/auth/sso/exchangefor the same access and refresh tokens a password sign-in returns. See Authentication.
If anything fails, the browser lands on the sign-in page with an error code such as sso_user_not_linked. Every code is listed under Errors.
Signing out of Plenary does not sign the person out of the provider, so the next Continue with single sign-on may complete without a prompt. SAML sign-in must start from Plenary; a response the provider sends on its own (IdP-initiated sign-in) is refused.
Requirements
Section titled “Requirements”- A license, or a Plenary Cloud instance. On the Free plan the settings pane is locked and the sign-in page shows no single sign-on button. See Licensing.
server.public_urlset to thehttps://address people use. The redirect URI, the SAML endpoints, and the address the browser returns to are all built from it. On a self-hosted instance that is inplenary.yaml; see Self-hosted install.- A super user account to configure the connection, and to keep as a fallback. Super users can always sign in with a password, even when single sign-on is required.
Configure the connection
Section titled “Configure the connection”Open Admin Settings → Global Settings → Single Sign-On (on Plenary Cloud, Single Sign-On in the admin menu). Choose the protocol, fill in the provider’s card, set the provisioning rules, then:
- Test connection checks the form without saving it: for OIDC it runs discovery against the issuer, for SAML it fetches or parses the provider’s metadata.
- Save stores the connection. A saved connection is checked the same way whenever it is enabled; a disabled one is stored as typed, so you can fill it in over several saves.
- Turn on Allow SSO sign-in and save again. The button appears on the sign-in page at once.
- Optionally, turn on Require single sign-on in the Password sign-in card and save. Everyone but a super user must now use the provider: the sign-in page folds the password form and the passkey button away behind Sign in with a password instead, and a password or passkey sign-in by anyone else is refused with
sso_required. The switch is available only while Allow SSO sign-in is on, and the requirement lapses with it, so turning the connection off never locks anyone out.
Copy the values on Plenary’s side of the registration from the pane; they are read-only there because they are derived from public_url:
| Value | Where | Used for |
|---|---|---|
| Redirect URI | OIDC card | https://your-instance.plenarycms.io/api/v1/auth/sso/oidc/callback, the URI the provider must allow |
| ACS URL | SAML, Service provider card | https://your-instance.plenarycms.io/api/v1/auth/sso/saml/acs, where the provider posts assertions |
| SP metadata URL | SAML, Service provider card | https://your-instance.plenarycms.io/api/v1/auth/sso/saml/metadata, Plenary’s SAML metadata, also the default entity ID |
| Certificate | SAML, Service provider card | The certificate Plenary signs requests with; Copy Signing certificate or quote the fingerprint |
The SAML certificate is generated the first time you save with SAML selected, enabled or not, so you can register Plenary with the provider before turning the connection on. Regenerate key replaces it immediately; update the provider afterwards or sign-in breaks.
Provisioning
Section titled “Provisioning”The User provisioning card decides what happens to the person the provider vouched for:
| Setting | Meaning |
|---|---|
Create accounts on first sign-in off (linked_only) |
Only existing accounts can sign in. An administrator creates each user first; the first single sign-on links it by verified email. Anyone else is refused with sso_user_not_linked. |
Create accounts on first sign-in on (jit) |
A person with no account gets one, with the role chosen per site under Default site access, no password, and the provider’s identity linked. Free plan user limits still apply. |
| Default site access | A role per site that a created account starts with. Changing it later does not touch existing accounts. |
| Email claim / Name claim (OIDC), Email attribute / Name attribute (SAML) | Where the address and display name come from. Defaults: email and name for OIDC; emailAddress and displayName for SAML. |
| Allowed domains | When set, a sign-in whose address is outside these domains is refused with sso_email_domain_not_allowed. Leave empty to allow any. |
An account is matched in this order:
- By identity. An account already linked to this provider’s identifier for the person. A changed email address at the provider does not matter.
- By verified email. An account whose email equals the asserted address, when the provider vouches for the address. OIDC providers do this with the
email_verifiedclaim (absent counts as verified, which is how Microsoft Entra ID behaves); a SAML assertion always counts as verified. An unverified address never links an account (sso_email_unverified). - By creating one, when Create accounts on first sign-in is on. The account needs an email, a first name, and a last name. OIDC providers supply
given_nameandfamily_name; otherwise Plenary splits the display name at its last space. A single-word name is refused withsso_user_required_fields. The username is the provider’spreferred_usernamewhen it is valid and free, else the part of the email before@.
Single sign-on never changes an existing account and never grants super user status or extra roles. What the account may do is set by an administrator; see Users & Permissions for how linked identities and password-less accounts appear in the user editor.
OpenID Connect providers
Section titled “OpenID Connect providers”Plenary is an OIDC relying party using the authorization code flow with PKCE and a client secret. It needs the provider’s issuer URL (discovery at <issuer>/.well-known/openid-configuration), a client ID, and a client secret. The default scopes are openid profile email; openid is always sent. The ID token’s sub is the person’s identifier. When the ID token lacks the email claim, Plenary reads the UserInfo endpoint.
Register a confidential web application at the provider with Plenary’s redirect URI, then copy the issuer, client ID, and secret into the OIDC card.
- In the Okta admin console, go to Applications → Applications → Create App Integration, choose OIDC - OpenID Connect and Web Application.
- Set Sign-in redirect URIs to Plenary’s redirect URI. Assign the users or groups who may sign in.
- Copy the Client ID and Client secret from the application’s General tab.
- Issuer URL: your Okta org URL, such as
https://example.okta.com, or a custom authorization server such ashttps://example.okta.com/oauth2/default. Both work; the org server is simplest.
Okta sends email, email_verified, given_name, family_name, name, and preferred_username with the default scopes.
Microsoft Entra ID
Section titled “Microsoft Entra ID”- In the Entra admin center, go to Identity → Applications → App registrations → New registration. Under Redirect URI choose Web and enter Plenary’s redirect URI.
- Under Certificates & secrets, create a client secret and copy its Value (not its ID).
- Copy the Application (client) ID and Directory (tenant) ID from the overview.
- Issuer URL:
https://login.microsoftonline.com/<tenant-id>/v2.0. Use the tenant ID, notcommon, so discovery names one issuer.
Entra ID omits email_verified; Plenary treats the address of a tenant-administered account as verified. Use Allowed domains to limit sign-in to your tenant’s domains. If the email claim is missing from tokens, add it as an optional claim under Token configuration, or set Email claim to preferred_username when your users’ UPNs are their email addresses.
Google Workspace
Section titled “Google Workspace”- In the Google Cloud console, go to APIs & Services → Credentials → Create credentials → OAuth client ID, application type Web application, and add Plenary’s redirect URI under Authorized redirect URIs.
- Copy the client ID and client secret.
- Issuer URL:
https://accounts.google.com.
Any Google account can complete the flow unless you restrict it. Set Allowed domains to your Workspace domains, and leave Create accounts on first sign-in off unless everyone in those domains should get an account.
Keycloak
Section titled “Keycloak”- In the realm, go to Clients → Create client, type OpenID Connect, and turn on Client authentication.
- Set Valid redirect URIs to Plenary’s redirect URI.
- Copy the secret from the client’s Credentials tab.
- Issuer URL:
https://keycloak.example.com/realms/<realm>.
Keycloak sends email_verified from the user’s Email verified flag. People with an unverified address cannot link an existing account until it is verified in Keycloak.
- In the AD FS management console, add an Application Group of type Server application accessing a web API, with Plenary’s redirect URI, and generate a shared secret.
- Add Plenary’s redirect URI (or
https://your-instance.plenarycms.io) as the Relying party identifier of the web API, and allow theopenid,profile, andemailscopes. - Issuer URL:
https://adfs.example.com/adfs.
AD FS does not send email or given_name by default; add issuance transform rules that map the LDAP E-Mail-Addresses, Given-Name, and Surname attributes to those claim names, or set Email claim to the claim your rules emit. AD FS also omits email_verified, which Plenary treats as verified.
SAML 2.0 providers
Section titled “SAML 2.0 providers”Plenary is a SAML 2.0 service provider using the HTTP-Redirect binding for signed authentication requests and the HTTP-POST binding for responses. It needs the provider’s metadata, by URL (refetched hourly) or pasted as XML. The Name ID is the person’s identifier; the default format is emailAddress, and when no email attribute is present an email-format Name ID is used as the address. Attributes are matched by their Name or FriendlyName, case-insensitively; the defaults are emailAddress and displayName. Given and family names are read from the common attribute names (givenName, sn, urn:oid:2.5.4.42, urn:oid:2.5.4.4, and the claims/givenname and claims/surname URIs).
Save once with SAML selected to get Plenary’s certificate and metadata, register them with the provider, then enter the provider’s metadata and enable the connection.
Microsoft Entra ID
Section titled “Microsoft Entra ID”- In the Entra admin center, go to Identity → Applications → Enterprise applications → New application → Create your own application, choose Integrate any other application you don’t find in the gallery, and open Single sign-on → SAML.
- Under Basic SAML Configuration, set Identifier (Entity ID) to Plenary’s SP entity ID (the SP metadata URL by default) and Reply URL to the ACS URL. Alternatively, Upload metadata file with the document from the SP metadata URL.
- Copy the App Federation Metadata Url from the SAML Certificates section into IdP metadata URL.
- Entra ID names attributes by full URI and sets no friendly names. Set Email attribute to
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressand Name attribute tohttp://schemas.microsoft.com/identity/claims/displayname. Given and family names arrive on the defaultclaims/givennameandclaims/surnameURIs. - Assign the users or groups who may sign in.
- Go to Applications → Applications → Create App Integration and choose SAML 2.0.
- Set Single sign-on URL to Plenary’s ACS URL and Audience URI (SP Entity ID) to the SP entity ID. Set Name ID format to EmailAddress and Application username to Email.
- Under Attribute Statements, add
emailAddressfromuser.email,displayNamefromuser.displayName,givenNamefromuser.firstName, andsnfromuser.lastName. - On the application’s Sign On tab, copy the Metadata URL into IdP metadata URL, and assign users.
- In the AD FS management console, choose Relying Party Trusts → Add Relying Party Trust, claims aware, and import the data from Plenary’s SP metadata URL.
- Add issuance transform rules of type Send LDAP Attributes as Claims mapping E-Mail-Addresses to E-Mail Address, Display-Name to Name, Given-Name to Given Name, and Surname to Surname. Add a Transform an Incoming Claim rule from E-Mail Address to Name ID with format Email.
- IdP metadata URL:
https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml. - Set Email attribute to
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddressand Name attribute tohttp://schemas.xmlsoap.org/ws/2005/05/identity/claims/name.
Settings API
Section titled “Settings API”| Method | Path | Does |
|---|---|---|
GET |
/api/v1/settings/single-sign-on |
Read the connection |
PUT |
/api/v1/settings/single-sign-on |
Replace the connection |
POST |
/api/v1/settings/single-sign-on/test |
Check a connection without saving it; answers {"ok": true} |
POST |
/api/v1/settings/single-sign-on/saml/regenerate-key |
Replace the SAML signing key pair; returns the connection |
All need a super user session. PUT, test, and regenerate-key also need a license (403 license_feature_sso on the Free plan). On Plenary Cloud these endpoints work as on a licensed instance.
curl -s "https://your-instance.plenarycms.io/api/v1/settings/single-sign-on" \ -H "Authorization: Bearer $PLENARY_ACCESS_TOKEN"{ "enabled": true, "protocol": "oidc", "sso_required": false, "provisioning": { "mode": "jit", "default_site_roles": [{ "site_key": "default", "role_key": "editor" }] }, "allowed_email_domains": ["example.com"], "oidc": { "issuer_url": "https://example.okta.com", "client_id": "0oa1b2c3d4e5f6g7h8i9", "client_secret_configured": true, "client_secret_hint": "x9Qk", "scopes": ["openid", "profile", "email"], "claims": { "email": "email", "name": "name" }, "redirect_uri": "https://your-instance.plenarycms.io/api/v1/auth/sso/oidc/callback" }, "saml": { "idp_metadata_url": "", "idp_metadata_xml": "", "sp_entity_id": "https://your-instance.plenarycms.io/api/v1/auth/sso/saml/metadata", "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress", "attributes": { "email": "emailAddress", "name": "displayName" }, "acs_url": "https://your-instance.plenarycms.io/api/v1/auth/sso/saml/acs", "metadata_url": "https://your-instance.plenarycms.io/api/v1/auth/sso/saml/metadata", "sp_certificate": "", "sp_certificate_fingerprint": "" }, "available_protocols": ["oidc", "saml"]}| Field | Meaning |
|---|---|
enabled |
Whether the sign-in page offers the connection. The provider card is validated only while this is on. |
protocol |
oidc or saml. Both cards are stored; only the selected one is used. |
sso_required |
Require single sign-on. While the connection is enabled, POST /api/v1/auth/login refuses everyone but a super user with 403 sso_required, and the sign-in page hides the password form behind Sign in with a password instead. Inert while the connection is disabled or on the Free plan. |
provisioning.mode |
linked_only or jit. |
provisioning.default_site_roles |
[{ "site_key", "role_key" }], one entry per site. Each must name an existing site and a role on it. |
allowed_email_domains |
Lower-cased domains; empty allows any. |
oidc.client_secret |
Write-only. Send it only to change it; an empty string clears it. Responses carry client_secret_configured and a four-character client_secret_hint. |
oidc.scopes |
Defaults to ["openid", "profile", "email"]; openid is added if missing. |
oidc.redirect_uri, saml.acs_url, saml.metadata_url, saml.sp_certificate, saml.sp_certificate_fingerprint |
Read-only, derived from server.public_url and the stored key pair. Ignored on PUT. |
saml.idp_metadata_url, saml.idp_metadata_xml |
One of them is required while SAML is enabled. The URL must be https. |
saml.sp_entity_id |
Defaults to the SP metadata URL. |
saml.name_id_format |
Defaults to urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. |
available_protocols |
What this server can connect over. |
A PUT is merged over the stored connection: leave out oidc, saml, provisioning, or allowed_email_domains to keep them. An enabled connection is built before it is stored, and refused with 422 sso_connection_invalid and a reason when discovery or the metadata fails. Errors are listed under Settings errors.
Seed from plenary.yaml
Section titled “Seed from plenary.yaml”A self-hosted instance can start with its connection in the configuration file. The block is imported once, when no connection has been saved yet, and ignored afterwards; the console owns it from then on. Default site roles are not imported.
single_sign_on: enabled: true protocol: oidc provisioning: mode: jit allowed_email_domains: [example.com] oidc: issuer_url: https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0 client_id: YOUR_CLIENT_ID client_secret: YOUR_CLIENT_SECRET scopes: [openid, profile, email] claims: { email: email, name: name }For SAML, use protocol: saml with a saml block carrying idp_metadata_url or idp_metadata_xml, and optionally sp_entity_id, name_id_format, and attributes: { email, name }. The signing key pair is generated the first time the connection is saved in the console.
Sign-in API
Section titled “Sign-in API”| Method | Path | Does |
|---|---|---|
GET |
/api/v1/auth/sso/providers |
{ "providers": [{ "key": "oidc", "type": "oidc" }], "sso_required": false }. Empty providers when nothing is enabled or on the Free plan. |
GET |
/api/v1/auth/sso/{key}/start |
Browser navigation; redirects to the provider. key is oidc or saml. |
GET |
/api/v1/auth/sso/oidc/callback |
Where the OIDC provider returns the browser. |
POST |
/api/v1/auth/sso/saml/acs |
Where the SAML provider posts the response. |
GET |
/api/v1/auth/sso/saml/metadata |
Plenary’s SAML metadata, available whenever SAML is the selected protocol. |
POST |
/api/v1/auth/sso/exchange |
{ "code": "plsc_…" } for the token pair. |
The callback and the ACS redirect to https://your-instance.plenarycms.io/cms/login/callback?code=plsc_… on success and to …/cms/login?error=<code> on failure. The login code lasts 60 seconds, works once, and only from the IP address the callback saw. The start, callback, and ACS routes share a limit of 60 requests per IP address per 15 minutes; the exchange has its own 60.
Errors
Section titled “Errors”On the sign-in page, as ?error=<code>:
| Code | Meaning |
|---|---|
sso_state_invalid |
The sign-in took longer than 10 minutes, was already completed, or the connection changed in between. Start again. |
sso_idp_error |
The provider refused or failed the sign-in, or could not be reached. Its own message is in the server log. |
sso_token_invalid |
The provider’s response did not verify: wrong signature, nonce mismatch, expired, or unsigned. Check the provider’s metadata or the client secret. |
sso_idp_initiated_unsupported |
The SAML response answered no request from Plenary. Start from Plenary’s sign-in page. |
sso_email_unverified |
The address matches an account, but the provider does not vouch for it. |
sso_email_domain_not_allowed |
The address is outside Allowed domains. |
sso_user_not_linked |
No account is linked to this identity and accounts are not created on first sign-in, or the matching account is already linked to a different identity at this provider. |
sso_user_inactive |
The account is deactivated. |
sso_user_required_fields |
The provider did not supply an email, a first name, and a last name for a new account. |
From the API: sso_provider_not_found and sso_provider_disabled (404) on start and the metadata route, sso_code_invalid and sso_user_inactive (401) on the exchange, sso_required (403) on a password sign-in by anyone but a super user while Require single sign-on is on, license_feature_sso (403) on every route on the Free plan, and the sso_* validation codes (422) on the settings endpoints. See Errors.
Related
Section titled “Related”- Authentication: sessions, tokens, and the exchange endpoint.
- Users & Permissions: linked identities and SSO-only accounts in the user editor.
- Settings: the other Global Settings groups.
- Licensing: what the Free plan includes.