--- title: "Single sign-on (SSO)" url: "/docs/sso" canonical_url: "https://crunchjunkie.io/docs/sso" markdown_url: "https://crunchjunkie.io/docs/sso.md" language: "en" type: "doc" summary: "Let your team sign in with your company identity provider (Microsoft Entra, Google Workspace, Okta) over OpenID Connect." site: "CrunchJunkie" llms_txt: "https://crunchjunkie.io/llms.txt" --- # Single sign-on (SSO) Source: https://crunchjunkie.io/docs/sso Let your team sign in with your company identity provider (Microsoft Entra, Google Workspace, Okta) over OpenID Connect. ## What SSO gives you Single sign-on lets everyone on your team sign in to CrunchJunkie with your existing company identity provider — Microsoft Entra ID (Azure AD), Google Workspace, Okta, or any OpenID Connect provider — instead of a separate password. New teammates are provisioned into your workspace automatically the first time they log in. SSO is available on the Pro, Agency and Scale plans and is configured by a workspace owner or admin under Settings → SSO. Without an active Pro, Agency or Scale plan, single sign-on pauses: your team signs in with a password or Google instead, and anyone who has only ever used SSO can set a password through Forgot password. That password is temporary. Once the plan is active again and SSO works, it is removed, sessions that signed in with it end within about a minute, and the person signs in with SSO again; we email them once when this happens. A password someone had before is kept. While someone signs in with such a temporary password, their email address can't be changed. API keys belong to the workspace, not to a password, so they are not removed: when a temporary password is removed, the admin audit log lists the API keys that person created in the meantime, and an owner or admin can review them under Settings → API and revoke any that aren't needed. An owner or admin can still switch SSO off, remove domains or delete the connection, and SSO works again once the plan is active. SSO is an extra way in until you require it: with Require SSO switched on (see "Require SSO" below), members on your verified domains can sign in only through your identity provider. We support OpenID Connect today, which covers the large majority of enterprise IdPs. If your provider speaks SAML only, ask us — SAML is available on request on the Scale plan. ## Register CrunchJunkie in your IdP In your identity provider, create a new OIDC (OpenID Connect) application. Set the redirect URI to the value shown in Settings → SSO — it looks like https://app.crunchjunkie.io/api/auth/sso/callback. Request the standard scopes openid, email and profile. Your IdP will give you three things: an issuer URL, a client ID and a client secret. Paste them into Settings → SSO and save. The secret is stored encrypted and never shown back to you — to change it, just save a new one. Two common setups. Google Workspace: in the Google Cloud console create an OAuth client ID of type "Web application", add the redirect URI there, and use https://accounts.google.com as the issuer URL. Microsoft Entra ID: register an app, add the redirect URI as a "Web" platform, and use https://login.microsoftonline.com//v2.0 as the issuer URL. If your IdP answers "redirect_uri_mismatch", the address registered there differs from the one shown in Settings → SSO — copy it again, character for character. ## Verify your email domains SSO routes a login by the user's email domain, so you tell us which domains belong to you and prove you own them. Add a domain (e.g. acme.com) in Settings → SSO and we'll show a DNS TXT record — add it to that domain's DNS, then click Verify. A domain routes no logins until it's verified, and each domain can belong to only one workspace, so no one else can claim yours. A domain left unverified for 30 days is released, so an unfinished claim can't block the domain's real owner; to verify it after that, add it again for a new TXT record. Add it as a new TXT record on the domain itself (host @, or left empty), next to the TXT records you already have — SPF and other verification records stay as they are. Paste the complete value, including the code after the equals sign: some DNS panels cut a pasted value at the "=". DNS changes can take a few minutes to show; if Verify fails, wait and try again. ## Turn it on Once at least one domain is verified, enable SSO. From then on, a user opens the login page, clicks "Continue with single sign-on (SSO)" — or goes straight to app.crunchjunkie.io/auth/sso — enters their work email, and is sent to your IdP; after they authenticate there (including any second factor your IdP requires), they land on CrunchJunkie's Home page, signed in. The first time someone from a verified domain signs in, they're added to your workspace automatically. Behind the scenes we validate the identity provider's signed token (its signature, issuer, audience and a per-login nonce) before trusting the email — so only a genuine response from your IdP can sign anyone in. And your IdP can only sign in addresses on the domains you verified: an address on any other domain is refused, even when the token itself is genuine. You can disable SSO at any time, which immediately stops routing logins to your IdP (existing password logins are unaffected). Turning SSO on does not switch passwords off: people who already have a password can keep using it, until you switch on Require SSO (next section). While SSO is on, members of your workspace whose address is on one of its verified domains stay with your identity provider. They can change their email only to another address on those domains. To move someone to any other address, an owner or admin opens Settings → Team, clicks the member's menu and chooses Change sign-in email (an admin can do this for members and read-only seats, the owner for anyone): a confirmation link goes to the new address, the change happens when it is clicked (within 24 hours), the previous address gets a notice, and both steps are recorded in our audit log. And while SSO works, Forgot password sends these members no password link, whether or not they have a password: they get an email that points them to single sign-on instead. The workspace owner is the exception: they keep Forgot password, as their way back in if your identity provider locks them out (see Require SSO below). If the workspace's plan lapses, the rules for temporary passwords above apply. While SSO is on, members of your workspace whose address is on one of its verified domains stay with your identity provider. They can change their email only to another address on those domains. To move someone to any other address, an owner or admin opens Settings → Team, clicks the member's menu and chooses Change sign-in email (an admin can do this for members and read-only seats, the owner for anyone): a confirmation link goes to the new address, the change happens when it is clicked (within 24 hours), the previous address gets a notice, and both steps are recorded in our audit log. And while SSO works, Forgot password sends these members no password link, whether or not they have a password: they get an email that points them to single sign-on instead. If the workspace's plan lapses, the rules for temporary passwords above apply. While SSO is on for a domain, the sign-up form creates no password account for its addresses: the address gets an email with the link to sign in with SSO instead, and the form answers as it always does, so it doesn't reveal whether the address has an account, and no link to confirm an address on that domain is sent. And if someone opened an account for an address before its owner ever confirmed it, that account's password and sessions are removed the first time the real person signs in with SSO, or with a Google account that proves the address (Gmail or Google Workspace), so nobody can set up an account for a colleague's address in advance. Its two-factor settings, API keys and other linked logins are removed too, unless the Google login that proves the address is the only one linked: then the same person set them up, keeps them, and gets an email saying the password was removed. Someone who confirmed their address earlier keeps their password. ## Require SSO With SSO on, passwords and "Continue with Google" keep working alongside it. To make your identity provider the only way in, an owner or admin switches on Require SSO in Settings → SSO. From then on, members whose email address is on one of your verified domains can sign in only with SSO, so your IdP's two-factor rules and its offboarding apply to every sign-in. Their password and Google sign-in are refused with "Your company requires signing in with SSO", and a session they didn't start with SSO ends within about a minute, at their next page or request. Members with an address on another domain, such as an outside consultant on gmail.com, are not affected, and neither is anyone outside your workspace. Someone invited to your workspace at an address on your domains joins by signing in with SSO. It can be switched on only once SSO is switched on with a verified domain, the workspace has an active Pro, Agency or Scale plan, and someone has signed in through your connection at least once, which proves the set-up works. Before it goes on, a confirmation lists every member it covers and every member it leaves alone, with the counts, the pending invites to your domains and the active API keys those members created. Switching it on and off is recorded in our audit log. Switching SSO off, or removing its last verified domain, switches Require SSO off too; switching it on again takes a new confirmation. While the workspace has no active plan, SSO pauses and Require SSO pauses with it, so nobody is locked out. If your identity provider is down, the workspace owner can still sign in with their password and two-factor authentication: an authenticator code or one of their recovery codes. Google stays refused. That is why Require SSO can only be switched on when the owner has both, why the owner can't turn two-factor off while it's on, and why ownership can only move to someone who has both (or whose address isn't on your domains). Every such sign-in is logged, and the owner gets an email each time. While your SSO is on, the owner can always use Forgot password, with or without Require SSO. Nobody can change the owner's sign-in email for them, so the owner role can't be taken over that way; if the owner loses both their password and their authenticator, contact us. API keys keep working: they belong to the workspace, not to a person's session, and integrations would break if they stopped. Review the ones listed in the confirmation under Settings → API. AI assistants (MCP) act as the person, so for these members the connector works only while their latest connection was made after signing in with SSO; an assistant connected from a password or Google sign-in, before or after Require SSO was switched on, stops working until they connect it again after signing in with SSO. Require SSO decides how people sign in; it doesn't remove anyone. A session started with SSO keeps working while it's in use and ends after 7 days without activity, so to cut someone off at once, remove them under Settings → Team: that ends their access to the workspace and revokes the API keys they created. Changing your identity provider while Require SSO is on (a new issuer, client ID or secret) keeps it on: the new settings have to work at once, and if they don't, the owner signs in with their password and two-factor authentication to fix them or switch Require SSO off. The change is recorded in our audit log. After any such change, switching Require SSO on again waits until someone has signed in with SSO through the new settings. Deleting the SSO connection switches Require SSO off, and that is recorded too. ## If a sign-in fails A failed attempt returns to the login page with a short message. What each one means: "isn't available for that email domain" — the domain isn't verified, SSO isn't enabled for it, or the workspace has no active Pro, Agency or Scale plan. The message is the same in each case, so the sign-in page tells no one a workspace's plan; meanwhile sign in with your password or Google (no password yet? use Forgot password to set one). "Couldn't reach your company's identity provider" — the issuer URL in Settings → SSO is wrong or the IdP is down. "Couldn't verify the response" or "didn't return a sign-in token" — the client ID or client secret doesn't match the IdP app. "Expired or was opened in a different browser" — the attempt took longer than ten minutes, or cookies are blocked; start again. "Hasn't verified your email address" — the IdP doesn't vouch for that mailbox, so we won't sign it in. "Domain isn't verified for your workspace's single sign-on" — your IdP returned an address on a domain you haven't verified (an alias domain or a subdomain, for example); verify that domain as well, or have the IdP send the address on your verified domain. "Your company's single sign-on is active again" — the password you used was set while SSO was unavailable, and now that SSO works again it has been removed: click "Continue with single sign-on (SSO)". "Your company requires signing in with SSO" — your workspace has Require SSO switched on, so your password and Google don't sign you in: click "Continue with single sign-on (SSO)". An error shown by the IdP itself (for example "redirect_uri_mismatch") means the app registered there needs correcting, not CrunchJunkie.