Okta
Bring Okta workforce and B2B authentication into the shared Flutter and Dart workflow.
Overview
Okta integrates through Aortem's shared auth lifecycle, so onboarding, login, refresh, and logout all use the same typed SDK calls used by every other provider.
Prerequisites
- Create a Okta application and record the client identifier and redirect URI.
- Set OKTA_CLIENT_ID and OKTA_REDIRECT_URI in your build environment.
- Enable the scopes required by your application, typically openid, profile, and email.
- Confirm the callback URI is registered for every mobile, web, or desktop target you support.
Installation
Add the provider adapter beside the core SDK package. Provider adapters stay intentionally small so application code continues to depend on the shared auth API, not provider-specific helpers.
Configuration
- Install aortem_auth_okta alongside the core aortem_auth package.
- Register AuthProvider.okta during SDK initialization.
- Store provider secrets in environment-specific configuration rather than shipping raw values in source.
- Validate issuer domains and audience values before promoting configuration to production.
Authentication flow
Trigger provider login through the shared `auth.login` method. That keeps callback handling, telemetry, and session lifecycle behavior aligned with every other integration in the portal.
Example implementation
Keep provider setup close to application bootstrap so the rest of the codebase can depend on the shared auth client instead of provider-specific wiring.
Error handling
- Catch AuthException values and branch on providerCode for tenant, scope, or consent failures.
- Retry token refresh only for recoverable network errors; force re-authentication for invalid_grant responses.
- Log redirect mismatches and state verification failures as deployment-time configuration issues.
Advanced configuration
- Override requested scopes per route when enterprise providers require least-privilege access.
- Attach custom claims mappers if your backend expects normalized profile fields across providers.
- Use environment-specific issuer overrides to separate staging tenants from production tenants.
Best practices
- Keep provider setup isolated in one module so application code only consumes the shared auth interface.
- Test refresh and logout flows in addition to first-time login before shipping a provider integration.
- Instrument provider latency and failure rates to catch upstream changes before they impact release quality.
Troubleshooting
- Verify the redirect URI in the provider dashboard exactly matches the runtime callback URI.
- Confirm required scopes are enabled before testing refresh or consent-heavy flows.
- Inspect provider-specific error codes first when login succeeds locally but fails after deployment.