Sign-in & SSO
Settings, Sign-in & 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.
Settings, Connectors and the setup wizard 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.
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”- Entra admin centre, Applications, App registrations, New registration.
- Name it something recognisable, for example “Plugboard”.
- Under Redirect URI, choose Web and paste the redirect URI from the Plugboard SSO page.
- Register, then note the Application (client) ID.
- Certificates and secrets, New client secret. Copy the value immediately, not the id. It is only shown once.
- 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.
- Issuer:
- 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”- Google Cloud console, in the project you use for Workspace integrations.
- APIs and Services, Credentials, Create credentials, OAuth client ID.
- Application type Web application.
- Under Authorised redirect URIs, paste the redirect URI from the Plugboard SSO page.
- Create, then copy the client ID and client secret.
- In Plugboard, set:
- Issuer:
https://accounts.google.com - Client ID and secret from step 5.
- Allowed domains: your school’s domain.
- Issuer:
- 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.
Testing sign-in
Section titled “Testing sign-in”Each of OpenID Connect and SAML 2.0 has a Test sign-in button beside Save. It runs a real sign-in against your identity provider and reports each check, without signing anybody in to Plugboard. It works whether or not the method is switched on, so you can prove a configuration before anyone depends on it.
- Saved settings or the form. When the form matches what is saved, the button tests the saved settings. When you have changed something, it reads Test these settings and tests what is on the page. Nothing is saved either way.
- A different issuer needs its secret. Testing a different issuer or client ID needs the client secret typed into the form. The saved secret is only ever sent to the issuer and client it was saved for, so without one the page asks for the client secret beside its field and sends nothing.
Running a test
Section titled “Running a test”- Press Test sign-in (or Test these settings). The first time on a device, a notice explains what happens next; choose Open sign-in window.
- Your identity provider opens in a pop-up window. Sign in there as the person you want to test. You stay signed in to Plugboard as yourself.
- The window ends on a “Test finished” page you can close. The result appears beside the button.
If the browser blocks the pop-up, the page says so with an open it here link that opens the same sign-in in another tab. Cancel stops waiting. A test that is not finished within ten minutes times out; start it again. A test must be finished in the browser that started it.
Reading the result
Section titled “Reading the result”The result says Sign-in works. or Sign-in did not work., with a plain sentence about what happened and what to change. Under it, a checklist shows each step and whether it passed:
| Step | What it checks |
|---|---|
| Reach the identity provider | Discovery, or the SAML sign-in URL, answered |
| The provider answered | The provider sent somebody back rather than an error |
| Token checked (SAML: Assertion checked) | Signature, issuer, audience, nonce or request match, and age |
| Email address found | The token or assertion carried an email address |
| Allowed domain | The address is in your allowed domains |
| Matching account | A staff account has that address and is active |
When sign-in works, the result names the account it matched and adds a line for each portal the same address would also open, such as the parent portal. For SAML it also says which attribute the email address came from.
Warnings appear in amber when something works but deserves a look: the provider did not say the email address is verified, its clock is more than a minute off, or a SAML entity ID is not saved, so sign-ins are not checked against it.
When the provider itself refused, its own error text is quoted under the result (“It said: …”), because that is usually the fastest clue.
The provider side can work while the last step fails. If nobody at that address has a staff account, or the account is deactivated, the result says Sign-in did not work. and names the reason.
What a test never does
Section titled “What a test never does”A test issues no session, no portal session and no sign-in code, and does not create, change or link any account. The configuration under test is not saved. A test and a real sign-in cannot stand in for each other: a response produced for one is refused by the other.
Who can run it, and limits
Section titled “Who can run it, and limits”- It needs
user.manageand whole-school authority: an administrator with every permission, not limited to a campus or a department. This is the same rule as saving these settings. - The result is shown only to the administrator who started the test.
- Starting a test, opening its sign-in window and reading results are each rate limited per minute. A school keeps at most five tests open at once; a sixth closes the oldest.
- Pending tests are held in the API process, like pending sign-ins. Behind several API replicas, the test’s return must reach the same process.
- The demo refuses tests, because a draft issuer is a request to an address a visitor chose.
Each finished test writes Single sign-on tested to the audit log, with the protocol, whether it tested saved settings or the form, whether it worked and the step that failed. It never records an email address, a claim or a secret.
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”- The user clicks “Sign in with”.
- Plugboard starts a flow with PKCE and a nonce, fixing the audience at the start so it cannot be changed on the way back.
- The provider authenticates and returns to
/sso/callback. - 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.
- 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.
A sign-in must finish in the browser that started it. Plugboard ties the flow to that browser with a cookie when it starts, for OIDC and SAML alike, so a sign-in link carried to another browser or device does not complete.
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.
- Add the new redirect URI at the provider.
- Keep both registered during the change.
- Change the hostname and
PUBLIC_URL. - Confirm sign-in works.
- 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 |
| Sign-in fails after finishing at the provider | It was started in another browser or on another device. Start again from the login page, in the browser you will use |
| 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 |