Okta

Preview

This integration is in preview.

Prerequisites

Complete the preparation checklist.

Application setup

In the Okta Admin Console, create an OIDC - OpenID Connect integration of type Web Application. Enable Authorization Code and Refresh Token. Set Sign-in redirect URIs to https://api.<platform-host>/identity/callback and Sign-out redirect URIs to https://<platform-host> (plus any other approved frontend addresses). Require S256 PKCE where supported by the application policy, then assign the approved test person or group. Use a client-secret authentication method.

Use your Istari domain for <platform-host>. For a custom API hostname or base URL, use the configured callback address.

Collected values

Collect the Client ID and secret from the application. Decide whether this installation uses the org authorization server, whose issuer is https://<okta-domain>, or a custom authorization server, whose issuer includes /oauth2/<authorization-server-id> (often default). Copy the issuer field from that server's OpenID configuration; do not confuse the two servers or use the administration domain. Preserve the chosen issuer for this installation.

For a custom authorization server, configure an access policy and rule that permits this client, its users, requested scopes, and authorization-code and refresh-token grants.

Installation configuration

istari-values.yaml (excerpt)

identity:
  oidc:
    provider: okta
    issuer: "https://<okta-domain>/oauth2/<authorization-server-id>"
    clientId: "<client-id>"
    clientAuthMethod: client_secret_basic
    scopes: "openid profile email offline_access"
  idpMigration:
    enabled: false

Store ISTARI_DIGITAL_IDENTITY_SERVICE_OIDC_CLIENT_SECRET in the Identity Service Secret. Set ISTARI_DIGITAL_IDENTITY_SERVICE_ENROLLMENT_POLICY=pre-registered-only.

Account preparation

Seed pending registrations for provider okta before the first login, or import authoritative sub mappings. For an existing Zitadel installation, use the Okta/PingFederate migration recipe. Email claiming requires a pending registration and trusted email_verified=true; it is not unrestricted email enrollment. The stable subject is sub, and local membership selects the tenant.

See account import commands and administrator setup.

Verification

Test an assigned, pre-registered account and a refused unprepared account. Confirm stable sub across repeated login, refresh, logout, and principal/tenant/role continuity after migration.

Limitations

Both secret-basic and secret-post are supported. An Okta administrator or import can mark an email verified; that assertion is not independent evidence that the person proved mailbox control. Confirm the customer's account-verification and email-change policy before relying on email linking. Use authoritative subject mappings if that trust cannot be established.