Complete an external OAuth callback
Complete the external OAuth/OIDC return to Antylogic by validating state, exchanging the provider code, resolving the application user, issuing a session, clearing temporary OAuth cookies, and returning the browser to the requested destination.
In this article
This guide covers the handoff that happens after a user signs in with an external provider. There is no dedicated Antylogic screen for this callback; the browser returns from the provider to `GET /api/app/auth/callback/{provider}` and then moves on to the final destination.
Use it when validating external sign-in for Harbor Demo Group, checking why a callback restarted authorisation, or explaining why `redirect=0` responses must never be published with real tokens visible.
Before you start
- An `auth_providers.code` record exists for `{provider}` and the provider is enabled.
- The browser returns to `GET /api/app/auth/callback/{provider}` with `code` and `state` in the query string.
- The temporary `oauth_state_{provider}` cookie matches the returned `state`.
- If PKCE is used, `oauth_pkce_verifier_{provider}` is available for the code exchange.
- The provider can exchange the code at its `token_endpoint` and return a profile with `sub` from the ID token or userinfo endpoint.
- The auth service accepts the internal token exchange used to issue the Antylogic session.
Instructions
- 1.
Receive the provider return
The provider redirects the browser to `GET /api/app/auth/callback/{provider}`. Antylogic trims and lowercases the provider code, requires `GET`, and rejects callbacks that do not include both `code` and `state`.
- 2.
Confirm the temporary OAuth state
Antylogic compares the returned `state` with `oauth_state_{provider}`. If the value is missing or different, it clears the temporary OAuth cookies for that provider and restarts sign-in at `/api/app/auth/authorize/{provider}`, preserving `return_to` when present.
- 3.
Exchange the authorisation code
The callback builds its absolute redirect URI and exchanges the returned code with the configured provider. Query `client_id` and `scopes` override temporary cookie values, and an available PKCE verifier is sent as `code_verifier`.
- 4.
Resolve the Antylogic user
Antylogic builds the external profile from the ID token or userinfo response. It first matches by provider and subject, may fall back to a verified email, and creates an active external user when no existing user is found.
- 5.
Issue the session
The app service asks the auth service to issue tokens through internal token exchange. The auth service creates or updates the user identity, validates OAuth client and consent rules when they apply, and creates access and refresh tokens.
- 6.
Return to the destination
On success, Antylogic writes `access_token`, `refresh_token`, and `auth_session` cookies, clears the temporary OAuth cookies, and redirects with `303 See Other`. Technical clients can use `redirect=0`, `redirect=false`, or `redirect=no` to receive JSON with `status`, `return_to`, and `result` instead.
Validations and limits
- An invalid or missing state does not issue a session and restarts authorisation.
- The provider must exist in `auth_providers` and be enabled.
- The external profile must include `sub`, and the resolved Antylogic user must be active.
- If the resolved OAuth client is not first-party, active consent must cover the requested scopes.
- A successful JSON response includes `result.access_token` and `result.refresh_token`; mask token values before any public capture.
- The inspected handler does not validate `return_to` against an allowlist, so documentation examples should use controlled destinations only.
Expected result
A valid callback signs the user into Antylogic and returns the browser to the requested destination, such as Harbor Soho. Invalid state restarts authorisation, while provider, profile, inactive-user, client, consent, or token-exchange failures stop the sign-in with an unauthorised response.