Skip to content

Federated Login Failed

URI: https://docs.ankatech.co/errors/federation-callback-invalid
HTTP Status: 401 Unauthorized

When you see this

A federated login could not be completed at the callback leg — the OIDC callback or the SAML assertion consumer, GET/POST /api/v3/auth/idp/callback. Every callback failure produces this one type and this one body.

One body for every cause, deliberately

The response is byte-identical whichever check failed. Nothing in it reveals which one, because the caller at this point is an unauthenticated browser and a distinguishable body would be an enumeration oracle — it would let a visitor learn which handshake identifiers exist, which assertions have been seen before, and which provider a state belongs to.

The true cause is written to the server log, without any token, assertion or secret.

Common Causes

  • The authorization code was rejected by the identity provider, or had already been redeemed.
  • The id_token or the SAML assertion failed validation.
  • A nonce or an assertion was replayed.
  • The handshake state / RelayState is unknown, expired, missing or malformed — the usual cause of which is simply taking too long at the provider's sign-in screen, or completing a login that was started in a different browser session.

Response Example

{
  "type": "https://docs.ankatech.co/errors/federation-callback-invalid",
  "title": "Federated Login Failed",
  "status": 401,
  "detail": "The federated login could not be completed. Please try again.",
  "instance": "/api/v3/auth/idp/callback",
  "timestamp": 1730000000
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. The Auth API carries no correlation member in the body: correlate through the X-Correlation-Id response header instead. See Error Index & Overview.

When the same failure reaches a browser leg it is converted into a console redirect rather than a body — see Federated Login Errors for that surface. This page documents the problem+json form the non-browser legs receive.

How to Resolve

  1. Start the login again from the console rather than reloading the callback URL. A callback URL is single-use and reloading it always fails.
  2. Complete the provider's sign-in promptly and in the same browser session the login started in.
  3. If it keeps failing, ask an operator to read the server log for the correlation identifier from the X-Correlation-Id response header — the specific check that failed is recorded there.

For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.