Antylogic
DemoApp login

399 operational guides

Docs sections
DocsAuthentication
Device

Start external authentication

Start a public OAuth/OIDC handoff for a configured provider. Antylogic checks the provider, creates temporary state cookies, and redirects the browser to the provider authorisation URL. User and session creation happen later in auth.oauth.complete.

In this article

Use this article when operations, support, or implementation teams need to confirm that an external sign-in handoff can start from Antylogic.

This is a public link/API handoff. It does not complete login, create an Antylogic session, or update users.

Before you start

  • An auth_providers record exists for the provider code used in the route.
  • The provider has enabled=true.
  • The provider has an effective authorization_endpoint and client_id; config.authorization_endpoint can supply the endpoint.
  • The browser or client preserves temporary /api/app cookies until the callback.
  • No signed-in user, token, organisation, location, role, or membership is required to open the public start route.

Instructions

  1. 1.

    Confirm an enabled provider exists

    Use a provider code that is enabled in the current environment. For the GB documentation runtime, native-local is the safe documented default when it is configured. Do not document Google, Microsoft, or Apple as available unless the runtime enables them.

  2. 2.

    Open the start link

    Open GET /api/app/auth/authorize/{provider} from the same browser session that will receive the callback. Optional query values are return_to, client_id, and scopes. A documentation-safe native example is /api/app/auth/authorize/native-local?return_to=/auth/login.

  3. 3.

    Keep the temporary state

    Antylogic builds the callback URL, generates state, reads the provider configuration, and writes temporary provider-scoped cookies for the callback. Successful starts write oauth_state_{provider} and oauth_client_id_{provider}; return_to, scopes, and PKCE cookies are written only when applicable.

  4. 4.

    Follow the redirect

    On success, Antylogic returns 302 Found and redirects to the provider authorisation endpoint with response_type=code, client_id, redirect_uri, scope, and state. Native providers, and providers without client_secret, also use PKCE S256.

  5. 5.

    Continue with the callback

    Keep the same browser context until the provider returns to GET /api/app/auth/callback/{provider}. The callback validates state, uses the saved values, and completes the Antylogic session in auth.oauth.complete.

Validations and limits

  • The request must use GET; other methods return 405 with metodo no permitido.
  • The provider route value is required, trimmed, and normalised to lowercase.
  • An empty provider returns 404 with provider requerido.
  • Missing, disabled, or incomplete provider configuration stops the start request with a 400 response.
  • auth_providers.config.authorization_endpoint takes priority over auth_providers.authorization_endpoint.
  • The upstream scope comes from auth_providers.scopes, or defaults to openid profile email. Query scopes are preserved for the callback/session step only.
  • Temporary cookies use Path=/api/app, HttpOnly, SameSite=Lax, Secure for TLS or X-Forwarded-Proto=https requests, and expire after 10 minutes.
  • External provider pages are outside Antylogic and should not be treated as product UI captures.

Expected result

The browser is redirected to the configured provider or safe native login surface while Antylogic retains temporary callback state. No Antylogic user or session has been created yet.

Related articles