Single sign-on

Admin, SSO (/admin/sso).

Plugboard supports generic OIDC and SAML 2.0. Anything that speaks either works: Microsoft Entra ID, Google Workspace, Okta, ADFS, or your state department’s federation.

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.

OIDC

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

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

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

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

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

Audiences

One identity provider can serve three different groups, and a school that only licenses it for staff simply never starts the other two.

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

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.

Pending flows expire after ten minutes.

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.

This is the single most common cause of an SSO outage, and it is entirely avoidable.

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

Symptom	Cause
No “Sign in with” button	SSO is not enabled, or the configuration is incomplete
Redirect URI mismatch at the provider	The URI registered does not match exactly. 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
Parents cannot sign in	The parent audience is not enabled, or PORTAL_USERNAME_ENTRY is off and no SSO audience is configured for them