Skip to content
Plugboard docs

Single sign-on

Admin, SSO (/admin/sso).

Plugboard supports OIDC and SAML 2.0, including configurations for Microsoft Entra ID, Google Workspace, Okta, ADFS and education federations. Validate the chosen provider’s settings and sign-in flow before relying on it.

From 0.14.0, Admin, Connectors and guided desk setup show explicit links for Microsoft Entra ID, Google Workspace, Custom OpenID Connect (OIDC) and Other SAML 2.0 provider. They open this sign-in configuration, separate from LDAP password checks and directory account management. On the OIDC form, choose the provider setup instructions, then enter your application’s details. Changing instructions does not replace credentials or save configuration.

There is one organisation OIDC configuration and one SAML configuration; choose the sign-in protocol for your deployment. Adding multiple directory connector instances does not add multiple simultaneous sign-in issuers.

Using the screen

Section titled “Using the screen”

From 0.18.1 the page lists the three sign-in methods down the side: OpenID Connect, SAML 2.0 and Directory sign-in, each with whether it is enabled (or, for directory sign-in, which audiences use it). Select one to configure it. Each method saves on its own and asks you to confirm it is you; unsaved fields stay while you switch between methods. Links ending #saml or #directory-sign-in, or carrying ?provider=entra, google or custom, open the matching method or provider instructions.

Before you start

Section titled “Before you start”

Two things save trouble later:

Know your final hostname. Redirect URIs are absolute. Setting SSO up on a temporary address and moving later means updating the identity provider at the same moment, and forgetting locks everybody out.

Keep a fallback. Set a local fallback password on at least one administrator account under Account. An identity provider outage should not be an outage of your service desk.

If it is already too late, because the provider is down, the administrator has left, or a domain here was saved with a typo, a self-hosted deployment is recoverable from the machine itself with plugboard admin-reset. See nobody can sign in.

OIDC

Section titled “OIDC”

The fields

Section titled “The fields”
Field What goes in it
Enabled The switch. Off until the rest is filled in
Issuer URL The provider’s issuer, for example https://accounts.google.com. Discovery is automatic from here
Client ID From the application you register
Client secret From the same place. Shown as set once saved; leave blank to keep the existing one
Allowed email domains Comma-separated, optional. Empty means any domain the provider will authenticate
Redirect URI Read-only. Copy this and register it with your provider

Save, then sign out and check the login page offers the “Sign in with” button.

Microsoft Entra ID

Section titled “Microsoft Entra ID”
  1. Entra admin centre, Applications, App registrations, New registration.
  2. Name it something recognisable, for example “Plugboard”.
  3. Under Redirect URI, choose Web and paste the redirect URI from the Plugboard SSO page.
  4. Register, then note the Application (client) ID.
  5. Certificates and secrets, New client secret. Copy the value immediately, not the id. It is only shown once.
  6. In Plugboard, set:
    • Issuer: https://login.microsoftonline.com/<your-tenant-id>/v2.0
    • Client ID and secret from steps 4 and 5.
    • Allowed domains: your school’s domain.
  7. Enable and save.

Nothing beyond the default openid profile email scopes is required. If you want SSO for students or parents as well, see audiences below.

Google Workspace

Section titled “Google Workspace”
  1. Google Cloud console, in the project you use for Workspace integrations.
  2. APIs and Services, Credentials, Create credentials, OAuth client ID.
  3. Application type Web application.
  4. Under Authorised redirect URIs, paste the redirect URI from the Plugboard SSO page.
  5. Create, then copy the client ID and client secret.
  6. In Plugboard, set:
    • Issuer: https://accounts.google.com
    • Client ID and secret from step 5.
    • Allowed domains: your school’s domain.
  7. Enable and save.

Okta, ADFS and everything else

Section titled “Okta, ADFS and everything else”

Any compliant provider works. Register a web application, set the redirect URI, and put the issuer, client id and secret into the form. Discovery does the rest.

SAML 2.0

Section titled “SAML 2.0”

For providers where SAML is the only option, or where your identity team already has a SAML pattern they trust.

Plugboard shows you two values to give the provider:

Value Called what, usually
Entity ID Identifier, or Entity ID
Reply URL Assertion Consumer Service, or ACS URL

And needs three back:

Field What goes in it
IdP Entity ID For example https://sts.yourschool.edu/adfs/services/trust
IdP sign-in URL For example https://sts.yourschool.edu/adfs/ls/
IdP signing certificate The public certificate the provider signs assertions with

From 0.20.0, sign-in must start from Plugboard’s sign-in button. The returned response must match that request, and its signed bearer SubjectConfirmation must carry the matching InResponseTo and the exact ACS recipient. Assertions are checked for age and reuse as well as signature, issuer and audience. Unsolicited, IdP-initiated responses are refused. Configure any identity-provider launcher tile to start at Plugboard instead of posting an unsolicited assertion.

Test a complete sign-in with the school’s actual IdP after upgrading. Automated signed-XML tests establish the request-binding behaviour; they do not certify every Entra, ADFS or other provider configuration.

Multiple API replicas

Section titled “Multiple API replicas”

Pending SAML requests and consumed assertion IDs are held in the API process. Route sign-in start and the ACS callback to the same process. A callback reaching another replica fails closed, and restarting the API invalidates unfinished sign-ins; the person must start again. Replica-independent SAML needs a shared atomic request/replay store, which this release does not provide.

Audiences

Section titled “Audiences”

One identity provider can serve three groups. A school that licenses it for staff only leaves the other two switched off.

Audience Signs in to Notes
Staff The technician console The usual case
Student The kiosk An alternative to tapping a card
Parent The parent portal Strongly recommended, see below

Each is a separate switch on the SSO page. Be deliberate about which you allow, particularly parents, because the parent portal shows a child’s records and username entry alone proves nothing.

In production, parent portal access should be through SSO. Username-only entry is an opt-in convenience for demonstrations, controlled by PORTAL_USERNAME_ENTRY, and refused by default.

What happens on sign-in

Section titled “What happens on sign-in”
  1. The user clicks “Sign in with”.
  2. Plugboard starts a flow with PKCE and a nonce, fixing the audience at the start so it cannot be changed on the way back.
  3. The provider authenticates and returns to /sso/callback.
  4. Plugboard verifies the token against the provider’s JWKS, checks the issuer, the audience and the nonce, and checks the email domain against your allow list.
  5. A matching account signs in. The return address carries a single-use code, not the session itself, so nothing of value is left in browser history or in your proxy’s access log.

Pending flows expire after ten minutes. The single-use code expires after one minute, and reloading the “Signing you in…” page after it is spent asks the person to start again rather than signing them in twice.

When you change the hostname

Section titled “When you change the hostname”

Redirect URIs are absolute, so a hostname change breaks SSO at the exact moment of cutover unless you plan for it.

  1. Add the new redirect URI at the provider.
  2. Keep both registered during the change.
  3. Change the hostname and PUBLIC_URL.
  4. Confirm sign-in works.
  5. Remove the old redirect URI.

A missed redirect URI is the most common cause of an SSO outage.

Provisioning

Section titled “Provisioning”

SSO controls who can sign in. It does not create accounts or remove them when somebody leaves. For that, turn on SCIM, which makes deprovisioning immediate.

Troubleshooting

Section titled “Troubleshooting”
Symptom Cause
No “Sign in with” button SSO is not enabled, or the configuration is incomplete
Redirect URI mismatch at the provider The registered URI differs. Scheme, host, path and trailing slash all count
Signs in and immediately bounces back The email domain is not in the allowed list
Works for you, not for a colleague They have no account, or it is deactivated. SSO authenticates; it does not create
Broke right after a domain change The redirect URI at the provider is still the old one
invalid_client The client secret is wrong, or you copied the secret id instead of the value
“This sign-in link has already been used or has expired” The single-use code was reloaded, bookmarked or reused. Start again from the login page
Parents cannot sign in The parent audience is not enabled, or PORTAL_USERNAME_ENTRY is off and no SSO audience is configured for them
SAML works from Plugboard but not an IdP launcher tile Unsolicited responses are refused. Configure the tile to start a request at Plugboard
SAML fails intermittently behind multiple API replicas The start and ACS callback must reach the same process; check routing affinity and API restarts
SAML response binding is refused Check the signed bearer SubjectConfirmation request ID and exact ACS recipient with the IdP administrator, then start a fresh sign-in