Skip to main content
A Gecko team admin sets up single sign-on entirely from Settings > Single Sign-On & SCIM, with no back-and-forth with the Gecko team. It works with any SAML 2.0 or OIDC identity provider: clicking Connect opens a hosted setup wizard where you pick the protocol and enter your IdP’s details.
You’ll need: Gecko Enterprise plan, a Gecko team admin, an admin on your identity provider, and a test user who isn’t the admin changing sign-in policy.

How it works

When you start setup, Gecko provisions a dedicated connection for your team and the wizard shows the exact values your IdP needs. The single most important rule:
Copy the service-provider values verbatim from the setup wizard. For SAML, the Entity ID and metadata URL contain a connection ID derived from your team’s internal ID (for example gecko-okta-72468ca55845447aa90c); they are not built from your team slug. Don’t hand-construct or guess them; paste exactly what the wizard shows, or import its metadata URL. Mismatched values are the number-one cause of failed logins.
Your team slug appears in your sign-in URL (https://app.gecko.security/sso/login?c=<team-slug>), not in your SAML Entity ID. Two different things; keep them straight.

Set it up

1

Save your team slug

In Settings > Single Sign-On & SCIM, save a unique team slug. It becomes part of your sign-in URL. Slugs are lowercase letters, digits, and hyphens, and must be unique across all Gecko teams.
The slug is read-only once SSO is connected. Pick the final one now.
2

Start the connection and copy the SP values

Click Connect. Gecko opens the setup wizard in a new tab, where you choose SAML or OIDC and see the values your IdP needs:
  • SAML: ACS URL, Entity ID, and a metadata URL. Copy these exactly (or hand the metadata URL to your IdP).
  • OIDC: the redirect (callback) URI.
Back in Gecko the connection shows as Pending until you verify it. You can Re-open the wizard to continue where you left off, or Clear the pending setup and start over. A pending setup expires after 24 hours.
3

Create the app in your IdP

Create a SAML or OIDC app in your identity provider using those exact values, then assign the app to the users who should reach Gecko.
  • SAML: set the Name ID and attributes. See the SAML provider reference for the per-provider screens (Google Workspace, Okta, Entra ID) and the exact claim names.
  • OIDC: create an OAuth client and note its client ID, client secret, and issuer / discovery URL.
4

Finish in the wizard, then verify in Gecko

Enter your IdP details in the wizard:
  • SAML: sign-in URL and signing certificate.
  • OIDC: issuer/discovery URL, client ID, and client secret.
Then return to Gecko and click Verify. If the wizard isn’t finished yet, Gecko tells you the setup is still in progress; complete it and verify again.
5

Test, then enforce

Once verified, the connection shows Connected and Gecko displays your team Sign-in URL. Open it in a fresh incognito window and log in with a non-admin test user.When that works, sign in through SSO yourself, then switch SSO enforcement from Optional to Required.
Enforcement applies to existing sessions, not just new logins. If you switch to Required while your own session came from a password login, you will be locked out along with everyone else, and reverting enforcement requires contacting the Gecko team. Sign in through SSO first.

The settings, one by one

Everything on Settings > Single Sign-On & SCIM, and what it does: Four behaviors worth knowing before you rely on them:
  • New SSO users default to Member. Anyone your IdP lets through gets a Gecko account on first login with the Member role, unless a role mapping says otherwise. Control who can log in by controlling app assignment in your IdP.
  • Group membership is read at login (or at SCIM sync). A group change in your IdP takes effect the next time the user signs in, not immediately.
  • Removing a user from your IdP doesn’t remove them from Gecko under just-in-time provisioning; it only stops future logins. Use SCIM deactivation, or remove them from Settings > Members as part of offboarding.
  • People who already use Gecko link their account once. SCIM attaches an existing account on an email match only when that account has no sign-in credentials. Otherwise it lists the person as waiting to link, without an error, until they sign in through your identity provider and confirm. A directory subject already linked to another account is declined with a 409. See Onboard people who already use Gecko.
SSO decides who can sign in and, through role mappings, what role they get. It has no say over repositories: what exists in Gecko comes from your team’s source-control connection, and what each user sees follows their own linked GitLab account, so linking is the natural last step of onboarding after the first SSO login.

Onboard people who already use Gecko

Some people in your rollout already have a Gecko account. They signed in with GitHub or a password, or they belong to another team. Gecko does not attach an account to your team because its email matches your directory. The person links it themselves, once, in a single sitting. What you do: assign the person in your IdP, then ask them to sign in to Gecko from your IdP app tile. That is the whole task. You don’t send an invite and you don’t run another sync. What the person does: signs in through your IdP, signs in to their existing Gecko account when asked, and confirms the link.
Gecko does not contact the person. It sends no email and shows nothing to a signed-in account on its own, because it does not verify that your team owns the email domain. Nothing happens until they sign in through your IdP, so you have to tell them. The IdP tile works for SAML connections; for OIDC, send them your team Sign-in URL.
1

Assign the person in your IdP

SCIM answers as it does for any new user, with no error. Gecko records that your directory wants this person and lists them as waiting to link. The record gives them no access and changes nothing on their account. Each SCIM push from your IdP refreshes it, and it expires after 30 days without one.
2

Ask them to sign in through the IdP tile

Gecko doesn’t tell them for you. Once they sign in through your connection, Gecko asks them to sign in to their existing account, then shows a link screen.
3

They confirm the link

The link screen names your team and your connection and says what linking grants. Both sign-ins, the IdP login and the existing account, must have happened within the last 10 minutes. If either is older, Gecko asks them to sign in again.
4

Gecko seats them

They join your team with the role your mappings give them. Their account, history, and other teams stay as they were.

Watch who is waiting

Admins who can manage members see the list in two places:
  • Settings > Members > Pending Invitations lists each person as Waiting to link through your connection, next to your invitations. Click Revoke to withdraw the offer. If the person is still assigned in your IdP, the next SCIM push lists them again, so unassign them there too.
  • Settings > Single Sign-On & SCIM shows N people waiting to link on the SSO connection card. The line is hidden when nobody is waiting.
If you deactivate or delete a waiting person in your IdP, Gecko removes them from the list. Nothing else changes.

What linking grants, keeps, and removes

  • It grants: membership of your team with the mapped role, and the ability for anyone who administers your connection to sign in to this Gecko account. The link screen says so, and names any other teams that already manage the account.
  • The person keeps: the account, its history, its other teams, and any sign-in method they already verified.
  • Linking removes, only when Gecko can’t confirm the mailbox: if the person’s existing account has no verified email sign-in for the address your directory lists, Gecko emails a one-time code to that address and requires it. After they link, Gecko deletes every unverified sign-in method on the account, so a password someone else registered for that address stops working, and emails the mailbox to say the account is now managed by your team.
  • Deprovisioning removes: when you deactivate or delete the person in your IdP, with deprovisioning enforced, or remove them from the team, they leave your team and lose the sign-in methods your connection created. The account itself, its history, and their other teams stay. If you reactivate them and the account has no other sign-in credentials, their next sign-in through your connection reconnects it. An account with credentials is listed as waiting to link again and needs one more confirmation.
If someone’s work email differs from the email on their existing account, Gecko can’t match the two, and SCIM creates a new account. They sign in through your connection, open Settings > General > Personal connections, and click Connect on the GitHub row. Gecko then offers Merge accounts.

Common errors

The connection= value in your URL doesn’t match the connection Gecko created. Use the exact connection ID / metadata URL from the setup wizard. It’s derived from your team’s internal ID (such as gecko-okta-72468ca55845447aa90c), not from your team slug.
The Entity ID or ACS URL in your IdP doesn’t match the wizard. This happens when the values were derived from the slug instead of copied. Re-paste the Entity ID and ACS URL exactly as the wizard shows them, or re-import its metadata URL.
Gecko configures IdP-initiated sign-in automatically for SAML connections during verification, so the app tile should work once the connection is verified. For OIDC connections there is no IdP-initiated flow; always start from your Gecko Sign-in URL.
Google’s SAML app isn’t turned on for that user. In the Google Admin console open the app, click User access, and set it On for everyone or the right org unit. If your browser is signed into several Google accounts (a authuser= value in the URL), test in a fresh incognito window as the correct user.
The user authenticated at the IdP, but Gecko couldn’t attach them to your team. Make sure the connection shows Connected (users are only provisioned once it’s verified) and that they signed in through your sign-in URL, not with a password or another method. If you’re on SCIM provisioning, the user may not have been assigned yet; assign them in the IdP and sync. The same message appears when the email belongs to an existing account your team can’t link. Ask them to contact a team admin.
They probably already have a Gecko account. Check Settings > Members
Pending Invitations for Waiting to link. If they’re listed, ask them to sign in to Gecko from your IdP tile. See Onboard people who already use Gecko.
Users get the Member role unless a role mapping matches one of their groups. Check that your IdP sends groups (via SCIM push or a groups claim) and that Role mappings references those exact group names. Membership is read at login, so users must sign in again after a group change.
Enforcement blocks every session that didn’t come through the SSO connection, including the admin who enabled it. If you can still complete an SSO login as any admin, sign in that way and set enforcement back to Optional. Otherwise contact the Gecko team to revert it; there is no self-service recovery.