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: Three 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.
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.

​
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.
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.