Auth21 Kernel

Auth21 Kernel | Docs

Okta integration docs

Real setup guidance for Okta-oriented environments: issuer, federation shape, claims mapping, token flow and troubleshooting.

Okta

Okta environment guide

Start from the identity layer you already have

Auth21 fits best when Okta remains the established enterprise identity plane and Bridge becomes the modernization layer for application-facing flows.

Recommended setup

Use OIDC discovery as the source of truth

  • Use the issuer exposed by your Okta environment for discovery and validation.
  • Register exact redirect URIs on both sides before testing callbacks.
  • Prefer Authorization Code flow with PKCE for browser-facing clients.

What not to do

Do not treat federation as an afterthought

If the issuer, callback contract or trust boundary are vague, troubleshooting becomes political and expensive very quickly in enterprise environments.

OIDC federation shape

Enterprise framing

Auth21 should not replace Okta here

The better story is: applications talk to Auth21, Auth21 orchestrates modern flows, and Okta remains the existing enterprise identity backbone.

Layered architecture

Applications
    ->
Auth21
    ->
Okta
    ->
Existing workforce identity

Claims mapping

Required

Subject

Keep a stable subject and do not switch identifiers midway through federation.

Practical

Email and display name

Normalize email and user-facing name early so downstream apps stay predictable.

Enterprise

Tenant and org signals

Map org or tenant hints only when they are truly stable and meaningful for authorization.

Token flow and Bridge usage

Bridge story

Use Bridge when the app flow must modernize first

Bridge is the cleanest narrative when the enterprise identity plane already exists and the application experience is what needs to evolve.

Operational checklist

  • Validate issuer and discovery output first.
  • Lock redirect URI exactness before broader testing.
  • Confirm claim mapping before app-side authorization assumptions.
  • Use trace and callback diagnostics for every failed federation test.

Troubleshooting

Common failures

  • Issuer mismatch
  • Redirect URI mismatch
  • Claim mapping drift
  • Federation callback mismatch

What to inspect first

Check issuer, exact callback, mapped claims and trace activity in that order. In most Okta-oriented failures, the problem is structural before it is application code.