Skip to Content

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 example https://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:

ProviderIssuer URL
Microsoft Entra IDhttps://login.microsoftonline.com/<tenant-id>/v2.0
Google Workspacehttps://accounts.google.com
Oktahttps://<your-company>.okta.com
Auth0https://<your-tenant>.auth0.com/
Keycloakhttps://<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:

  1. 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.
  2. At your DNS provider, add a TXT record with that name and value. The value is unique to your organization.
  3. 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

SituationWhat happens
Someone who has signed in with SSO beforeSigned in to their account, even if their email address changed at your provider
A new address, no ZəkaHouse account yetAn 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 organizationLinked to that account on first sign-in
An address that already has an account, but not in your organizationRefused. Invite the person to your organization first, then they sign in with SSO
An address your provider has not verified, or outside your domainsRefused

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 pageWhat to check
Your email domain is not allowedThe address is outside Allowed email domains
Your identity provider did not confirm your email addressVerify the address at your provider; for Entra ID, verify your domain (step 3)
Your account does not existTurn on Create accounts automatically, or invite the person
Accounts can only be created for email domains your organization has verifiedVerify the domain (step 3), or invite the person
An account with this email already existsInvite that account to your organization, then sign in with SSO
SSO is not configured correctlyCheck 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 browserStart 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_KEY so 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.