Authentication concepts shared across every provider
Use these concepts to keep application code stable while providers, tenants, and deployment environments evolve underneath the SDK.
Provider abstraction
Application code should call `login`, `logout`, `refresh`, and `session.current` without branching on provider type. The provider adapter owns the identity-system specifics, while the SDK exposes a predictable contract.
One client
Initialize once and pass the same auth client through your app shell, state container, or service layer.
One session model
Normalize access tokens, user claims, expiry state, and provider metadata into one typed session object.
One error surface
Catch provider-specific failures through one exception type so logging and recovery logic stay centralized.
Session lifecycle
Aortem treats session state as the shared truth between login, refresh, authorization checks, and logout. Session refresh should happen before expiry, and unrecoverable refresh errors should route the user back through authentication rather than attempting infinite retries.
- Persist only the minimum session fields needed by the client runtime.
- Refresh proactively when expiry is near, not after requests are already failing.
- Always clear local session state during logout, even when upstream revocation fails.
Redirect handling
Most provider onboarding issues come from redirect mismatches. Keep callback registration explicit, verify URI schemes per target platform, and validate state parameters on return to the app.
Recommended discipline
Maintain callback URIs in environment configuration, mirror them in provider dashboards, and test sign-in plus sign-out paths in every target before release.
Operational model
Provider choice should not dictate logging shape, alerting strategy, or documentation structure. Teams scale faster when observability, troubleshooting, and deployment workflows follow the same conventions across integrations.
- Log provider latency and redirect errors with normalized fields.
- Document provider prerequisites with the same headings for every integration.
- Treat auth configuration drift as an operational issue, not a client bug.