Skip to content
plugboard.appRequest a demo

Configuration

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.

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.

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.

FieldWhat goes in it
EnabledThe switch. Off until the rest is filled in
Issuer URLThe provider’s issuer, for example https://accounts.google.com. Discovery is automatic from here
Client IDFrom the application you register
Client secretFrom the same place. Shown as set once saved; leave blank to keep the existing one
Allowed email domainsComma-separated, optional. Empty means any domain the provider will authenticate
Redirect URIRead-only. Copy this and register it with your provider

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

  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.

  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.

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.

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:

ValueCalled what, usually
Entity IDIdentifier, or Entity ID
Reply URLAssertion Consumer Service, or ACS URL

And needs three back:

FieldWhat goes in it
IdP Entity IDFor example https://sts.yourschool.edu/adfs/services/trust
IdP sign-in URLFor example https://sts.yourschool.edu/adfs/ls/
IdP signing certificateThe 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.

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.

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.
  1. 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.
  2. 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.
  3. 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.

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:

StepWhat it checks
Reach the identity providerDiscovery, or the SAML sign-in URL, answered
The provider answeredThe provider sent somebody back rather than an error
Token checked (SAML: Assertion checked)Signature, issuer, audience, nonce or request match, and age
Email address foundThe token or assertion carried an email address
Allowed domainThe address is in your allowed domains
Matching accountA 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.

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.

  • It needs user.manage and 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.

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

AudienceSigns in toNotes
StaffThe technician consoleThe usual case
StudentThe kioskAn alternative to tapping a card
ParentThe parent portalStrongly 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.

  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.

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.

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.

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.

SymptomCause
No “Sign in with” buttonSSO is not enabled, or the configuration is incomplete
Redirect URI mismatch at the providerThe registered URI differs. Scheme, host, path and trailing slash all count
Signs in and immediately bounces backThe email domain is not in the allowed list
Works for you, not for a colleagueThey have no account, or it is deactivated. SSO authenticates; it does not create
Broke right after a domain changeThe redirect URI at the provider is still the old one
invalid_clientThe 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 providerIt was started in another browser or on another device. Start again from the login page, in the browser you will use
Parents cannot sign inThe 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 tileUnsolicited responses are refused. Configure the tile to start a request at Plugboard
SAML fails intermittently behind multiple API replicasThe start and ACS callback must reach the same process; check routing affinity and API restarts
SAML response binding is refusedCheck the signed bearer SubjectConfirmation request ID and exact ACS recipient with the IdP administrator, then start a fresh sign-in