Single Sign-On (SSO)
With single sign-on, your members sign in to ZəkaHouse with the account they already use at work or school, through your organization’s own identity provider. ZəkaHouse speaks OpenID Connect, so it works with Microsoft Entra ID, Google Workspace, Okta, Auth0, Keycloak and any other provider that supports it.
SSO is part of the Enterprise plan. Setting it up needs administrator access both to your ZəkaHouse organization and to your identity provider.
1. Register ZəkaHouse at your identity provider
At your provider, create an OpenID Connect web application (a confidential client using the authorization code flow):
- Redirect (callback) URL: copy it from Settings → SSO in ZəkaHouse. It is your organization’s address followed by
/auth/sso/callback, for examplehttps://academy.learn.example/auth/sso/callback. If members also sign in on your own custom domain, register that domain’s callback URL as well. - Scopes:
openid email profile.
Then note three values: the issuer URL, the client ID and the client secret. Typical issuer URLs:
| Provider | Issuer URL |
|---|---|
| Microsoft Entra ID | https://login.microsoftonline.com/<tenant-id>/v2.0 |
| Google Workspace | https://accounts.google.com |
| Okta | https://<your-company>.okta.com |
| Auth0 | https://<your-tenant>.auth0.com/ |
| Keycloak | https://<host>/realms/<realm> |
Microsoft Entra ID: add the optional email claim to the ID token, and list and verify your email domains (steps 2 and 3). Entra does not say whether an email address is verified, so ZəkaHouse accepts Entra addresses only in domains you have verified.
2. Turn SSO on in ZəkaHouse
Open Settings → SSO and fill in:
- Issuer URL, Client ID and Client secret from step 1. The secret is stored encrypted and never shown again; to keep it when you change other settings, leave the field empty.
- Allowed email domains: for example
school.edu. Only addresses in these domains can sign in. Leave it empty to accept any address your provider has verified. - Create accounts automatically: when on, a person who signs in for the first time gets a ZəkaHouse account and joins your organization as a member, if their email domain is verified (step 3).
Turn SSO on and save. ZəkaHouse checks your provider’s details as you save, so a wrong issuer URL is reported straight away. Your login page now shows Sign in with SSO.
3. Verify your email domains
Listing a domain does not prove you own it. Before ZəkaHouse creates accounts for addresses in a domain, you prove ownership with a DNS record, the same way as for a custom domain:
- Save your settings. Settings → SSO then shows each listed domain as Not verified, with a TXT record name (for example
_learnhouse-verification.school.edu) and a TXT record value. - At your DNS provider, add a TXT record with that name and value. The value is unique to your organization.
- Press Check DNS. A domain whose record is found shows Verified. DNS changes can take a few minutes to appear, so check again if it is not found straight away.
Existing members of your organization can sign in with SSO before this step. Only new accounts wait for it.
Who can sign in
| Situation | What happens |
|---|---|
| Someone who has signed in with SSO before | Signed in to their account, even if their email address changed at your provider |
| A new address, no ZəkaHouse account yet | An account is created, if Create accounts automatically is on and the address’s domain is verified |
| An address that already has an account in your organization | Linked to that account on first sign-in |
| An address that already has an account, but not in your organization | Refused. Invite the person to your organization first, then they sign in with SSO |
| An address your provider has not verified, or outside your domains | Refused |
A session started through SSO only works in your organization. Your provider vouches for people inside your organization, not elsewhere on the platform.
Making SSO the only way in
Under Users → Security → Sign-in methods you can allow only SSO. Members then sign in through your provider only.
Your organization’s administrators keep a backup: they can still sign in with their password or an email link (“Administrator? Sign in with your password” on the login page). If your identity provider is down or set up wrongly, an administrator can still get in and fix it.
Troubleshooting
| Message on the sign-in page | What to check |
|---|---|
| Your email domain is not allowed | The address is outside Allowed email domains |
| Your identity provider did not confirm your email address | Verify the address at your provider; for Entra ID, verify your domain (step 3) |
| Your account does not exist | Turn on Create accounts automatically, or invite the person |
| Accounts can only be created for email domains your organization has verified | Verify the domain (step 3), or invite the person |
| An account with this email already exists | Invite that account to your organization, then sign in with SSO |
| SSO is not configured correctly | Check the issuer URL, client ID and secret; re-enter the secret if it was changed at the provider |
| This sign-in was started in a different browser | Start again from the login page in the same browser |
Self-hosting
- If your identity provider runs on a private network (an on-premises Keycloak, say), list its host name in
LEARNHOUSE_SSO_PRIVATE_HOSTS. Otherwise ZəkaHouse refuses private and internal addresses. - Set
LEARNHOUSE_SSO_ENCRYPTION_KEYso that rotating your JWT secret does not make stored client secrets unreadable. - SAML and on-premises Active Directory: put a self-hosted Keycloak in between. ZəkaHouse talks OpenID Connect to Keycloak, and Keycloak talks SAML or LDAP to your directory.