Single sign-on

Overview

Single sign-on connects your organisation to your own identity provider — Okta, Microsoft Entra ID, OneLogin, Ping, Google Workspace, or any SAML 2.0 or OpenID Connect provider — so your people reach Gitmoap with the credentials they already have. You prove you own an email domain, point Gitmoap at your provider, and decide who is allowed through: everybody on the domain, or only the people you name.

It also gives you the switch that closes the other door: turn on enforcement and anyone whose email is on one of your verified domains has to come through your provider, so a Gitmoap password stops being a second, unmanaged way into your code.

Before you start

How it works

The four parts

How a sign-in resolves

Everything turns on the domain of the email address a person types.

Two properties of that flow are worth holding on to.

One person is one account, keyed by their verified email. When somebody who already signed up with alice@acme.com first comes through your provider, Gitmoap links the two rather than creating a second Alice. Her repositories, tokens, stars and history are all still hers; she gains membership of your organisation, and from then on both routes reach the same account.

Linking and automatic joining only ever happen inside a domain you have proved you own, and only for an address your provider marks as verified. That gate is not optional and cannot be relaxed: without it a misconfigured — or hostile — provider could assert somebody else's address and take over their account. It is also the reason an unverified domain silently does nothing rather than half working.

The connection's status

Configuring the connection registers your provider and wires it into the sign-in page, which takes a moment and can fail for reasons that live at your provider. The connection reports where it got to.

Group membership from your provider

Your provider can also say which of its groups a person is in, and a team can follow one of those groups. Map the claim your provider sends groups in — attribute_mapping.groups on the connection — and link each team to a group's name, spelled exactly as the claim spells it. Sending the configuration is what applies a new mapping, so a connection set up before you mapped groups needs sending again. Then every sign-in through your provider puts the person on the linked teams whose group it names and takes them off the ones it does not; a sign-in whose claim names none of those groups takes them off all of them. Only your provider's word counts: the groups are read only for an account linked to your organisation's own provider, and only your provider can set them — nobody can write their own groups to put themselves on a team.

A place your provider confirms lasts for the connection's sync period, idp_sync_max_age_days: 30 days unless you set it, anywhere from 1 to 365. Someone who leaves a group but never signs in again drops off the team once the period passes. A groups claim of 2 048 characters or more may not have arrived whole, so it changes nothing at all rather than removing people on a partial list — and neither does a claim Gitmoap cannot read. Have your provider send only the groups your teams follow.

Sign-in sync learns about a change only when the person signs in, and the places it writes are not in your audit log one by one. For changes that take effect as they happen, including removing somebody who never signs in again, provision over SCIM. While your organisation has a live SCIM token, sign-in sync is off, so the two never disagree — and places on linked teams lapse at the end of the sync period, because nothing confirms them.

Domains are matched exactly

A verified acme.com routes alice@acme.com and nothing else. alice@eng.acme.com is a different domain: claim and verify it too, or those addresses go to the ordinary sign-in page. A verified domain belongs to one organisation only — no two organisations can hold the same one verified — which is what makes "this address belongs to that organisation" a fact rather than a preference.

Claims are not exclusive until verified

Claiming a domain only hands you the record that proves it. Until somebody verifies it, any number of organisations can claim the same domain, and none of them gains anything by it: an unverified claim routes no sign-in, links no account, shows on no organisation and unlocks no name. The first organisation to publish its record and verify owns the domain, and the other organisations' claims on it are removed. So a claim somebody else made on your domain cannot keep you out of it — verify it, and theirs goes.

A verified domain does more than route sign-ins. It shows on your organisation, as verified_domains on its details, to everyone who can see the organisation, which is how a reader tells your organisation from one with a similar name. And it unlocks your organisation's name if Gitmoap keeps that name for whoever owns the domain — see Take your reserved name.

How to

Claim an email domain

Claiming hands you the TXT record that proves you own the domain; it reserves nothing until you verify it. Claim every domain your people use email on, including the ones you only use for aliases.

The record you add is a TXT record named _gitmoap-challenge.acme.com whose value is the whole gitmoap-domain-verification=… string. Most DNS providers want the name relative to the zone, so in the acme.com zone the name is _gitmoap-challenge alone — appending the zone twice is the single most common reason verification never succeeds.

Claiming a domain you already hold is safe: it returns the live challenge instead of a new one, so a lost record value is one call away rather than a reason to release and re-claim.

Verify a claimed domain

Verification resolves the TXT record and, if it matches, marks the domain verified. A verified domain is what routes sign-ins and what the linking gate checks, so nothing else on this page takes effect until at least one domain is verified. From that moment the domain also shows on your organisation and unlocks its reserved name, if it has one, and any other organisation's pending claim on the domain is removed.

Add the record first and give your DNS a minute. Verification reads what is published at that moment — it does not retry in the background, and it does not queue. A failed attempt does not mint a new challenge, so the record you already published is still the right one. If your connection is already active, verifying a domain starts routing its addresses to your provider straight away, with no further step; if sign-ins from it still meet a password form afterwards, send the configuration again, which re-registers every verified domain you hold.

Verifying a domain that is already verified is harmless and reports the same result.

See which domains you hold

This is the list to check when a sign-in goes to the wrong place. A domain that is claimed but not verified routes nothing at all. The listing does not repeat the DNS challenge; claim the domain again to read that back.

Connect your identity provider

Configuring the connection registers your provider and attaches it to the sign-in page. Send the protocol and one matching configuration block: SAML with either a metadata URL or a metadata document, or OpenID Connect with an issuer URL and a client id. An OpenID Connect connection requests openid, email and profile unless you name your own set.

Four things about this call are easy to get wrong the first time.

It replaces the whole configuration rather than patching it. Every setting you want has to be present on every call — a switch you leave out goes back to its default, and a default role you leave out goes back to Reporter.

Send the OpenID Connect client secret every time. Leaving it out keeps the secret Gitmoap has stored, but the registration is rebuilt from the call you just made — so a call that omits the secret registers without one, and the connection can come back failed.

The secret is write-only. Reading the connection tells you whether a secret is set, never what it is. Store it where you can find it, or be ready to mint a new one at your provider.

Exactly one block, matching the protocol. A SAML connection carrying an OpenID Connect block is refused, and so is a SAML block carrying both a metadata URL and an inline document. Prefer the metadata URL where your provider offers one: it is refetched, so a certificate rotation at your provider needs nothing from you.

The same call carries the four settings that decide who is admitted and how.

Enforcement is checked when somebody signs in with a password, and nowhere else. Access tokens are unaffected, so a build that pushes with a token keeps working. That also means it is not a way to end anyone's access: it closes the password route for your verified domains and leaves memberships and tokens exactly as they are. Turn it on after the connection reads active and the test passes, because from that moment your provider is the only way in for those addresses.

Check the connection

The test performs three read-only checks and changes nothing: that a connection exists, that the provider registration is live, and that you have at least one verified domain. Run it after a change at your provider, and before you tell anyone to try signing in. It is gated with the changes rather than the reads, so a token carrying only sso:read cannot run it.

A test that reports no verified domains is the usual explanation for a connection that looks configured and routes nobody.

Review the connection

Reading the connection is recorded in your audit log as a sensitive read, with the account that did it. That is intentional: this view is the closest thing your organisation has to a description of how it authenticates, and it is worth knowing who looked.

Invite somebody who has no account

An invite pre-authorizes one email address. When that person first signs in through your provider, the account is created, membership is granted with the invite's role, and the invite is consumed. Invites are the alternative to automatic joining: use them when you want membership to stay an explicit decision.

An invite sends no mail. It is a standing permission, not an invitation letter: nothing reaches the address, and the person joins by signing in through your provider like everybody else. Tell them yourself that they can sign in.

An invite decides the role only for somebody who has no Gitmoap account. Somebody who already has one is linked and joins with the connection's default role whatever the invite says — and the invite is spent all the same. To give an existing account a different role, give it to them on the group's access list.

The address is matched exactly, capital letters included, against what your provider asserts — so type it the way the mailbox is actually spelled, in lower case unless you know your provider asserts otherwise.

Inviting an address only helps if its domain is one of yours and verified. An invite for a domain you do not hold sits there and never resolves, because the sign-in that would consume it never routes to you.

See who is waiting to join

This list is also your cleanup worklist. An invite that has been pending since somebody's start date passed is usually a typo in the address, and it is holding a slot against the cap.

Revoke a pending invite

Revoking removes the pre-authorization. If the person has no Gitmoap account and automatic joining is off, their next sign-in is refused.

Revoking is addressed by the email, matched exactly as it was invited — take it from the listing rather than retyping it.

Revoking an invite somebody has already used takes nothing away: the invite was consumed at their first sign-in and their membership is a separate thing. Remove them from the group's members to end their access.

Route a sign-in to the right provider

Given an email address or a domain, this returns the URL to send somebody to so they land on your provider instead of a password form. It needs no credential, which is what lets your own sign-in page, a desktop tool or a CLI ask it before anyone has authenticated. A domain that does not route to an active connection answers plainly that it does not, and you fall back to the ordinary sign-in page.

The answer says whether the domain routes to single sign-on and, where it does, which protocol it speaks. Nothing else about the connection is exposed — no issuer, no client id, no claim mapping.

Release a domain

Release a domain when you have genuinely stopped using it — a retired brand, a company you sold. To pause sign-ins without giving up the name, turn single sign-on off instead, which keeps every domain you have verified.

Turn single sign-on off

Configuring the connection again brings it back with no re-verification of your domains. Because the client secret was deleted, an OpenID Connect connection needs its secret supplied again.

Reference

Limits

A thousand pending invites per organisation. The number is the same on every plan, and it counts invites that are still waiting: an invite consumed at somebody's first sign-in, or revoked, frees its slot the moment it goes.

The thousand-and-first is refused with 429, naming the invite limit. Nothing is created by the refused call, so a retry once you have freed a slot behaves exactly as the first attempt would have. If you are anywhere near it, the fix is almost never a bigger number: revoke the invites that have been pending for months, and turn automatic joining on so that people on a verified domain need no invite at all.

Joining consumes a member slot on your top-level group, and that cap does depend on your plan: 50 members on Free, 200 on Pro, 1 000 on Team and 5 000 on Enterprise. This one bites in an unusual way. When the group is full, the sign-in still succeeds — your provider authenticated them and the account is real — but membership is not granted, so the person arrives able to sign in and unable to see anything. The group's usage and limits view shows the live count against the cap, and it is worth checking before a rollout rather than after. Where you need a higher ceiling, request a limit increase on the group; it is an Owner-level request and it is reviewed.

Troubleshooting

Examples

Setting up an OpenID Connect provider end to end

--group-id takes the group's id or its path. <client-secret> is the secret from the application you created at your provider; it is stored write-only and never read back.

A SAML provider, invite-only, with passwords blocked

Automatic joining is left off, so only the two invited addresses can create an account. Enforcement is on, so everyone else on acme.com who tries a password is refused. Bob joins as a Reporter — the connection default — and Alice as a Maintainer.

Clearing out invites that were never used

Anything still pending months after a start date is usually a mistyped address, and each one holds a slot against the invite cap.

FAQ

Related