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: 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
Save your team slug
Start the connection and copy the SP values
- 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.
Create the app in your IdP
- 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.
Finish in the wizard, then verify in Gecko
- SAML: sign-in URL and signing certificate.
- OIDC: issuer/discovery URL, client ID, and client secret.
Test, then enforce
The settings, one by one
Everything on Settings > Single Sign-On & SCIM, and what it does:- 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.
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.Assign the person in your IdP
Ask them to sign in through the IdP tile
They confirm the link
Gecko seats them
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.
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.
Common errors
connection not found
connection not found
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.Login fails on the callback (invalid_request / audience or Entity ID mismatch)
Login fails on the callback (invalid_request / audience or Entity ID mismatch)
Signing in from the IdP app tile doesn't work
Signing in from the IdP app tile doesn't work
Google: app_not_configured_for_user
Google: app_not_configured_for_user
authuser= value
in the URL), test in a fresh incognito window as the correct user.Login succeeds but: your sign-in doesn't have access to any workspaces
Login succeeds but: your sign-in doesn't have access to any workspaces
A person is assigned in the IdP but isn't a member
A person is assigned in the IdP but isn't a member
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.
Login works but roles aren't assigned
Login works but roles aren't assigned
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.Locked out after enforcing SSO
Locked out after enforcing SSO