Skip to main content
Prerequisites
  • Gecko Enterprise plan
  • A team admin who can manage Settings > Single Sign-On & SCIM
  • An Okta admin who can create app integrations
  • A test user in Okta who is not the person changing sign-in policy

​
Before you start

This guide follows the current Gecko access flow:
  • You must save a unique team slug before you connect SSO.
  • Gecko keeps SSO enforcement optional until you turn it on.
  • Gecko shows the team sign-in URL after the connection is verified.
  • SCIM comes after SSO. It is not the first step.
Keep one existing Gecko admin session open until the first Okta login succeeds. Do not switch SSO enforcement to required during your first test.

​
Connect Okta SAML

1

Set the team slug in Gecko

Go to Settings > Single Sign-On & SCIM.Save a unique team slug. Gecko uses it to generate your team sign-in path.
The team slug becomes read-only after SSO is connected.
2

Start the Okta setup from Gecko

In the Single sign-on section, click Connect.Gecko starts the self-service Okta SAML flow and pre-creates the connection name for your team.If you leave the setup midway, return to the same page and resume the pending setup before it expires.
3

Create the SAML app in Okta

In Okta, create a private SAML 2.0 app integration.Use the SAML values shown in the Gecko setup flow for the single sign-on URL, audience, and certificate exchange.Set Name ID format to EmailAddress.Make sure the SAML subject resolves to each user’s work email address.
4

Verify the connection in Gecko

Return to Gecko and finish verification from Settings > Single Sign-On & SCIM.When verification succeeds, the connection moves to Connected and Gecko shows the team Sign-in URL.
5

Test the first login

Open the Gecko Sign-in URL in a fresh browser session.Sign in with a real Okta user who should have access to the team.Confirm the user lands in the correct workspace before you change enforcement.
6

Share the sign-in URL and require SSO

Share the Gecko Sign-in URL with your team.Keep SSO enforcement set to Optional while you finish testing.When sign-in is stable, change SSO enforcement to Required.

​
Turn on SCIM after SSO works

Gecko starts in just-in-time provisioning mode after SSO is connected. Users are created on first login. Move to SCIM when you want deterministic provisioning, group sync, and cleaner role assignment.
1

Enable SCIM in Gecko

Stay in Settings > Single Sign-On & SCIM.After SSO login works, enable SCIM in Directory sync.Gecko reveals the SCIM base URL and rotates a fresh gscim token for the connector.
If your workspace says provisioning is managed by Auth0, finish provisioning upstream there instead of using Gecko-hosted SCIM.
2

Configure Okta provisioning

In Okta, open the app integration and enable SCIM provisioning from General > App Settings.In Provisioning, paste the Gecko SCIM base URL.Use userName as the unique identifier.Choose HTTP Header authentication and put the gscim token in the Authorization header.Enable Create Users, Update User Attributes, and Deactivate Users.
3

Push groups and map roles

Push one Okta group for each Gecko role you want to manage.Back in Gecko, map each pushed group to the matching role in Role mappings.Save the mappings before you run your first full sync.
4

Run the first sync

Use Sync Now in Gecko.Confirm users, groups, and role counts look right.Fix any unmapped groups before you rely on automatic role assignment.

​
Rollout checklist

Ready for required SSO

You saved the final team slug, verified the sign-in URL, tested a non-admin login, and kept a fallback admin session alive.

Ready for SCIM

You enabled SCIM after SSO worked, tested the connector, pushed groups, and saved Gecko role mappings.

​
Troubleshooting

Save the team slug first. Gecko blocks SSO setup until the slug exists and your latest slug edits are saved.
That is expected after SSO is connected. Pick the final slug before you finish the SSO setup.
The connection is not verified yet. Finish the Okta setup, then return to Gecko and verify the pending connection.
You are probably still on just-in-time provisioning. Enable SCIM, push groups from Okta, and save Gecko role mappings.
Gecko only reveals those fields after SSO is verified and SCIM is enabled. If provisioning is managed by Auth0 for your workspace, use the upstream provisioning flow instead.
Re-check the SAML subject and Name ID format. Gecko expects a stable work-email identity. Keep SSO enforcement optional until the login succeeds end to end.