Google Workspace sign-in

Google Workspace sign-in lets the people in your workspace sign in to Badge with their company Google account. You name your company domains, for example example.com, and prove that you control each one with a DNS record. Anyone who signs in with a Google Workspace account on a verified domain is admitted. Anyone else is refused.

Google sign-in is available only when it is switched on for your Badge deployment. If the Google option is not offered in the Single sign-on section of the Team page, it is not turned on for your deployment.

For identity providers such as Microsoft Entra ID and Okta, use Single sign-on with SAML instead. The two can be used in the same workspace.

Before you start

• You must be the workspace owner. Only owners can set up, change, or turn off SSO.
• Your workspace must be on the Enterprise plan. SSO is an Enterprise feature, as shown on Pricing. Both the workspace and your own subscription must be on Enterprise. On any other plan, saving settings or verifying a domain is refused with plan_sso_not_included.
• You need access to the DNS for each company domain. You will add one TXT record per domain to prove that you control it. See Prove your domain with DNS.
• Your people need Google Workspace accounts on those domains. A personal Gmail account cannot sign in through this option, because it has no company domain. Consumer domains such as gmail.com cannot be claimed at all.

Set it up

1. Open the Single sign-on section on the Members tab of the Team page and choose Google.
2. Under Allowed Google domains, enter your company domains separated by commas, for example example.com. Badge takes your own email domain if you leave the field blank.
3. Choose the default role for people who sign in for the first time: Member or Viewer. Owners and Admins are never granted by sign-in.
4. Save. Badge records the change in the audit log as sso.config_updated.
5. Add the DNS TXT record Badge shows for each domain, then select Verify now. Single sign-on stays off for a domain until its record is verified.
6. Optionally, turn on SSO-only once you have checked that an owner can still sign in with a password or GitHub. Turning it on ends the existing sessions of everyone except owners, and the others sign straight back in through Google. Owners keep their sessions. See SSO-only mode.

How a person signs in

1. The person opens Badge's sign-in page, chooses Sign in with SSO, and enters their work email.
2. Badge sends them to Google. Badge asks Google to show accounts from your company domain first. This is a hint only. The check is made on Badge's server, as described below.
3. They choose their company account and approve the sign-in.
4. Badge checks Google's response. If it passes, Badge signs them in. If the browser is already signed in to Badge as someone else, Badge first asks whether to switch accounts, and keeps the current one unless the person chooses to continue. If they are not yet members of the workspace, Badge creates their account and adds them with the default role.

What Badge checks

Badge does not take the domain from the sign-in page or from anything the browser sends. It checks Google's response on its own server, and admits the person only if every check passes:

• The response is genuinely from Google and was issued for Badge. Badge verifies Google's signature, the audience, the issuer, and the nonce it issued for this sign-in.
• The account is a Google Workspace account on one of your allowed domains, and that domain has been verified with its DNS record. Google states an account's Workspace domain in the hd claim. Badge requires that claim to match an allowed domain, and the domain of the email address to match it too. A personal Google account has no hd claim, so it is refused.
• The email address is verified by Google.

What happens to someone outside the allowed domains

Someone whose account is not on one of your verified domains is refused. Badge creates no account, adds no membership, and signs no one in. They return to the login page with the error code sso_domain_not_allowed.

This applies to personal Gmail accounts, to Workspace accounts on other domains, and to any account whose Google response fails a check above. Refusing one sign-in does not affect anyone else. People on your domains can still sign in, and people who already have a Badge password can still use it unless SSO-only is on.

Existing Badge accounts

If someone already has a Badge account with the same email address, Badge links the Google sign-in to it only when that account is already an accepted member of this workspace, with a verified email. Otherwise the sign-in is refused with sso_account_conflict, and Badge does not take over the account. An owner who wants that person in the workspace can invite the existing account. Once it is an accepted member, Google sign-in can link to it.

The first time, the person confirms the connection. After Google, Badge asks them to sign in with their current Badge password, or with GitHub if that is how they sign in, and nothing is linked until they do. This applies to owners too. See Connecting an existing account.

Things to know

• One workspace per person. A person can belong to one SSO workspace in v1.
• If your plan changes. If the workspace leaves the Enterprise plan while Google sign-in is set up, people who are already members keep signing in. Nobody new can join until it is on Enterprise again: a new person's Google sign-in is refused with sso_not_enabled, and you cannot invite anyone or have a pending invitation accepted. You can still turn off Require single sign-on for all members, remove an allowed domain, or turn SSO off; anything else needs Enterprise, and the Team page says so beside each setting you cannot change. Turning SSO off lets you invite people again. See If your plan changes.
• Roles are not mapped from Google. A person's role comes from the default role, and from changes you make in the Members tab. Google groups do not set roles.
• Removing someone blocks their sign-in until you invite them again. Badge removes the link to their Google account when they leave. A removed member who signs in with Google is refused with sso_account_unavailable. Invite them again to restore access, or accept a pending invitation, which admits them with the role on that invitation. To stop access altogether, suspend them in Google Workspace as well.
• Turning SSO off. The steps are the same as for SAML, including the Forgot password step for people who joined through SSO. See Turning SSO off.
• Other errors. The other codes you may see on the login page, and what to do about each, are listed in Single sign-on with SAML. Cancelling at Google shows sso_cancelled.