Skip to content

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.

  1. 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.
  2. 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.
  3. The provider sends the browser back to Plenary: GET /api/v1/auth/sso/oidc/callback for OIDC, or an HTTP POST to /api/v1/auth/sso/saml/acs for SAML. Plenary verifies the response, finds or creates the account, and redirects to the console with a one-time login code.
  4. The console exchanges the code at POST /api/v1/auth/sso/exchange for 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.

  • 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_url set to the https:// 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 in plenary.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.

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:

  1. 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.
  2. 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.
  3. Turn on Allow SSO sign-in and save again. The button appears on the sign-in page at once.
  4. 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.

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:

  1. By identity. An account already linked to this provider’s identifier for the person. A changed email address at the provider does not matter.
  2. 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_verified claim (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).
  3. 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_name and family_name; otherwise Plenary splits the display name at its last space. A single-word name is refused with sso_user_required_fields. The username is the provider’s preferred_username when 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.

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.

  1. In the Okta admin console, go to Applications → Applications → Create App Integration, choose OIDC - OpenID Connect and Web Application.
  2. Set Sign-in redirect URIs to Plenary’s redirect URI. Assign the users or groups who may sign in.
  3. Copy the Client ID and Client secret from the application’s General tab.
  4. Issuer URL: your Okta org URL, such as https://example.okta.com, or a custom authorization server such as https://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.

  1. In the Entra admin center, go to Identity → Applications → App registrations → New registration. Under Redirect URI choose Web and enter Plenary’s redirect URI.
  2. Under Certificates & secrets, create a client secret and copy its Value (not its ID).
  3. Copy the Application (client) ID and Directory (tenant) ID from the overview.
  4. Issuer URL: https://login.microsoftonline.com/<tenant-id>/v2.0. Use the tenant ID, not common, 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.

  1. 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.
  2. Copy the client ID and client secret.
  3. 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.

  1. In the realm, go to Clients → Create client, type OpenID Connect, and turn on Client authentication.
  2. Set Valid redirect URIs to Plenary’s redirect URI.
  3. Copy the secret from the client’s Credentials tab.
  4. 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.

  1. 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.
  2. Add Plenary’s redirect URI (or https://your-instance.plenarycms.io) as the Relying party identifier of the web API, and allow the openid, profile, and email scopes.
  3. 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.

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.

  1. 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.
  2. 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.
  3. Copy the App Federation Metadata Url from the SAML Certificates section into IdP metadata URL.
  4. 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/emailaddress and Name attribute to http://schemas.microsoft.com/identity/claims/displayname. Given and family names arrive on the default claims/givenname and claims/surname URIs.
  5. Assign the users or groups who may sign in.
  1. Go to Applications → Applications → Create App Integration and choose SAML 2.0.
  2. 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.
  3. Under Attribute Statements, add emailAddress from user.email, displayName from user.displayName, givenName from user.firstName, and sn from user.lastName.
  4. On the application’s Sign On tab, copy the Metadata URL into IdP metadata URL, and assign users.
  1. 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.
  2. 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.
  3. IdP metadata URL: https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml.
  4. Set Email attribute to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress and Name attribute to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name.
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.

Terminal window
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.

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.

plenary.yaml
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.

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.

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.