Configure and Test Tenant SSO

Overview

Use this guide to configure tenant single sign-on from Tenant SSO Configuration (/Admin/SsoConfiguration). The current visible admin path is a SAML metadata wizard: enter the email domain, add SchoolBanks as a service provider in the identity provider, upload the identity provider metadata XML, and enable SSO.

The codebase also contains protocol-selection and test actions for OIDC and SAML. Treat Enable OIDC, Enable SAML, OIDC test, and SAML test as API-backed or legacy wizard capabilities unless they are visible in the tenant environment you are operating.

Prerequisites

• Admin access with tenant settings permission.
• A break-glass admin account that can still use password login if tenant SSO blocks normal users.
• The tenant email domain that users enter at sign-in.
• Access to the district identity provider to create a SAML application and export metadata XML.
• Agreement from the identity team on whether IdP MFA is required. In advanced protocol setup, this maps to Require IdP MFA for SSO.

Step-by-step procedure

1. Open Admin > Settings > Tenant SSO Configuration (/Admin/SsoConfiguration).
2. Select Set up SSO.
3. On Set up single sign-on, enter the tenant Email domain, such as example.org.
4. Select Continue.
5. On Add SchoolBanks to your identity provider, copy the Service provider details:
   • Entity ID
   • Assertion Consumer Service URL
   • Audience
   • NameID format
6. In the identity provider, create a SAML application for SchoolBanks using those service provider values.
7. If the identity provider accepts service provider metadata, select Download metadata XML and upload it there.
8. Export the identity provider metadata XML from the identity provider.
9. Return to SchoolBanks and select I have the metadata file.
10. On Upload identity provider metadata, choose the Metadata XML file.
11. Select Save and enable SSO.
12. After Single sign-on enabled appears, copy or open the SSO sign-in URL and test with a non-admin account.
13. Confirm users with the tenant email domain can sign in through SSO and that password login is disabled except for admins.

Variations / branching flows

• Replace metadata: from the enabled SSO page, upload a replacement metadata file and select Replace metadata file.
• Disable SSO: select Disable SSO when the tenant needs to return users to non-SSO sign-in.
• Restart setup: select Start over setup to clear wizard progress and begin again.
• View service provider metadata: use View metadata or Download metadata XML.
• Advanced protocol setup: when the environment exposes the older protocol wizard, choose SAML 2.0 or OpenID Connect, set Require IdP MFA for SSO, run OIDC test or SAML test, then save the configuration.
• SAML sign-in: document and validate SP-initiated SSO. Do not promise IdP-initiated behavior unless the tenant environment has been explicitly tested for it.

Expected outcomes

• The enabled page shows Single sign-on enabled for the expected email domain.
• The SSO sign-in URL launches the tenant SSO flow.
• Users with the configured domain can sign in using their identity provider account.
• Admin password login remains available for operational recovery.
• Last successful and failed SSO login values can be reviewed from the enabled SSO page.

Troubleshooting / edge cases

• If the metadata upload fails, confirm the file is XML metadata from the identity provider, not a certificate export or screenshot.
• If users land on an identity provider error, compare Entity ID, Assertion Consumer Service URL, and Audience against the IdP application.
• If users return to SchoolBanks but cannot be resolved, confirm their email domain, NameID, and required attributes match the tenant configuration.
• If all users are blocked, use a break-glass admin account to disable SSO or replace metadata.
• If Test OIDC connectivity or Test SAML connectivity buttons appear in an environment, use those before saving and keep the diagnostic output with the support ticket.

Related processes

• Configure Tenant Settings and Options
• Manage Roles and Permissions

Assumptions and gaps

• The primary user-facing page currently documents SAML metadata setup. OIDC configuration support exists in controllers, clients, and older wizard partials, but the current visible path should be verified in the tenant environment before writing tenant-specific OIDC instructions.
• MFA execution is controlled by the upstream IdP for SSO users; SchoolBanks local MFA applies to non-SSO login paths.