Skip to main content

Migrating from Okta to Gate

Okta's positioning is workforce-IAM-first — a Universal Directory of user profiles, group memberships, and application assignments centralised at the org level; SAML / OIDC federation downstream into customer applications; rich admin tooling. Gate is project-scoped — each project has its own user table; the org-level Universal Directory concept maps onto per-project membership in Kilimanjaro's project model.

For workforce-IAM customers, the migration involves a conceptual shift: instead of one Okta org federating into N downstream apps, you have N Kilimanjaro projects each with their own Gate substrate, optionally federating into the same upstream identity provider (the customer's existing AD / Entra / Google Workspace).

If you haven't already, read the migration overview for the four-phase migration arc that applies across all vendors.

1. Capability mapping​

CapabilityOktaGate
Universal DirectoryOrg-level user profiles + groups + application assignmentsPer-project users + groups; AD / LDAP native bridging for unified directory federation
SAML SSOOkta as SAML IdP for downstream appsGate as SAML IdP — configure via Console; or Gate as SP federating into customer's existing SAML IdP via gate.signInWithProvider({ provider: 'saml', ... })
OIDCOkta as OIDC IdPGate as IdP (native session model); Gate-as-RP upstream federation via generic OIDC is not supported — use the 'saml' provider path for Okta federation
SCIM provisioningInbound + outbound SCIMBidirectional SCIM sync (<orgSlug>.api.k9o.io/@<projectSlug>/scim)
AD / LDAP integrationOkta AD Agent / LDAP AgentNative AD / LDAP bridging — configured as an identity provider, with a pre-save bind test; no agent install required (architecture claim; see note below)
MFA — TOTPOkta Verify TOTPEnd-user TOTP enrollment: POST /@<projectSlug>/gate/mfa/totp/enroll and .../totp/confirm
MFA — WebAuthnOkta FastPass + WebAuthnSee API → Auth §6
MFA — SMSSMS factorNot supported (SIM-swap risk; NIST 800-63B-4 deprecation)
MFA — pushOkta Verify PushNot supported
Group-based accessGroup rules + application assignmentsGroup memberships + RBAC role bindings + JSON policy per project
Adaptive MFARisk-based step-upStep-up driven from policy decisions per Controls
User profile schemaProfile attribute editorcustomAttributes (typed object per project)
Lifecycle hooksOkta workflowsWebhook subscriptions per Security §2.6 + Maker-Checker via Controls
Admin ConsoleOkta AdminConsole /admin/auth/{members,groups,providers}
Branded sign-inOkta Sign-In WidgetGate Studio — visual sign-in authoring
PricingPer-user / per-feature workforce IAM50K MAU on Free; Unlimited on every paid tier

The single capability Gate does not currently support is push-based MFA (Okta Verify Push). Workforce deployments dominated by push-MFA should plan a TOTP / WebAuthn re-enrollment window during the parallel-run phase.

2. API-shape mapping​

2.1 Gate as SP — federating into the customer's Okta (SAML)​

If Okta remains your authoritative IdP and Gate is the service provider, use signInWithProvider with provider: 'saml'. This is the path for Okta federation.

UserGateOktagate.signInWithProviderredirect to Okta (SAML)Okta asserts identitySAML assertionGate callbackgate.completeSignIn()assertion becomes a sessionsigned in with a Gate JWT
With Okta still the authoritative IdP, Gate is the service provider and exchanges Okta's SAML assertion for a Gate session.
// Initiate sign-in — redirects the browser to Okta's SAML endpoint via Gate (returns void)
await gate.signInWithProvider({
provider: 'saml',
redirectUri: 'https://your-app.example.com/auth/callback',
});

// On the callback page — exchange the SAML assertion for a Gate session
const result = await gate.completeSignIn();
if (result.ok) {
// result.accessToken is the Gate JWT for this user
}

The provider: 'saml' value targets the SAML IdP configured for the project. Configure the Okta SAML application metadata (entity ID, ACS URL, signing certificate) at Console /admin/auth/providers/saml — no fabricated SDK registration call exists for this; it is a Console / gateway configuration.

Note: Generic OIDC (provider: 'oidc') is not supported. The supported provider set is 'saml' plus the hosted social providers ('google', 'github', 'microsoft'). For Okta federation, use 'saml'.

2.2 Gate as IdP — downstream apps consume Gate identities​

If Gate replaces Okta as the authoritative IdP and downstream applications verify Gate-issued identities:

UserGateDownstream appgate.signInsession with a Gate JWTsend the Gate JWTfetch the per-project JWKSverifyJwtclaims: sub, roles, groups
When Gate replaces Okta as the identity provider, downstream services verify Gate-issued tokens with the standalone verifyJwt helper.
// User signs in (email + password, or via upstream provider)
const { data } = await gate.signIn({ email, password });
const token = data.session.accessToken; // the Gate JWT

// In downstream services — verify the Gate-issued JWT with the standalone helper
import { verifyJwt } from "@k9o/gate";
const result = await verifyJwt({
token,
jwksUrl: "https://<org>.api.k9o.io/@<proj>/auth/jwks",
allowedAlgorithms: ['EdDSA', 'RS256', 'ES256'],
expectedIssuer: issuer, // the iss claim of your Gate tokens
expectedAudience: projectId, // end-user tokens: aud is the project id
});
if (result.valid) {
// result.claims.sub is the Gate user ID; claims contain roles, groups, project scope
}

Registering downstream service-providers to consume Gate-issued SAML assertions is a Console configuration concern, not an SDK object. Configure Gate's SAML IdP metadata and per-SP ACS URLs at Console /admin/auth/providers/saml. There is no IdentityProvider { type: 'SAML' } SDK object — the SDK surface for consuming Gate identities is the standalone verifyJwt({ token, jwksUrl }) helper.

2.3 AD / LDAP bridging​

Gate supports native AD / LDAP bridging without an agent install (architecture claim; not separately SDK-verified here). An LDAP or Active Directory directory is configured as an identity provider (idpProvider: 'ldap' or 'active_directory', PROJECT_ADMIN+; see API → Auth §5.3), and POST /@<projectSlug>/identity-providers/bind-test checks the server URL, bind DN template and credentials before you save it. The directory configuration is also available in the Console at /admin/auth/providers/ldap.

2.4 SCIM provisioning​

Gate exposes a SCIM 2.0 endpoint at <orgSlug>.api.k9o.io/@<projectSlug>/scim/v2/{Users,Groups} analogous to Okta's SCIM surface. Configure your upstream identity provider (Entra / Google Workspace / Okta itself if running parallel) to provision into Gate's SCIM endpoint. Bidirectional sync (Gate → upstream IdP) requires opt-in per IdP via the Console.

3. User-data migration​

Export users from Okta via their Users API (GET /api/v1/users) or the Okta CSV export. Field mapping:

Okta fieldGate field
id (00uxxx)New Gate user ID; preserve old in customAttributes.okta_id
profile.emailemail
profile.firstName + lastNamecustomAttributes.firstName + lastName
profile.loginIf different from email, store in customAttributes.login
credentials.providerFederated users re-authenticate via their upstream IdP on first Gate sign-in
status (ACTIVE / STAGED / PROVISIONED / etc.)Map to Gate's status (active / pending_activation / disabled)
_links.groupsGate group memberships (separate import per group)
Custom profile attributescustomAttributes

Passwords cannot transfer from Okta (Okta does not export password hashes). Plan a password-reset flow for users without federated identity at cutover; users with federated identity (SAML) sign in via their upstream IdP via gate.signInWithProvider({ provider: 'saml', ... }) and don't need a Gate password.

4. Cutover checklist​

StepDone when
Capability auditEvery Okta feature in §1 mapped to Gate (or replanned)
Federation strategyDecision: Gate as IdP (replacing Okta) vs Gate as SP (federating into customer's Okta); SAML configuration drafted in Console
Parallel-runGate provisioned alongside Okta; new sign-ups in both; SCIM sync configured
User-data exportOkta users exported via API or CSV
User-data importgate.users.import against the target Gate project; staging dry-run passes
Password-reset windowUsers without federated identity prompted to set a Gate password during the parallel-run phase
MFA re-enrollmentTOTP / WebAuthn re-enrolled during parallel-run window (Okta Verify Push users especially)
Downstream app SAML configs updatedCustomer apps' SAML configs point at Gate's entity-ID / ACS URL (Console /admin/auth/providers/saml)
CutoverSign-ins routed Gate-only; Okta tenant entered grace period
DecommissionOkta subscription cancelled after a 60-day verification window (longer for workforce deployments due to audit-trail retention)

5. See also​