Federated Login Errors (Browser Redirect Surface)

Surface: browser redirect — 302 Found / 303 See Other, no response body
Carrier: the error and ref query parameters on the console login URL
Not an RFC 7807 problem type — see How this differs from every other page in this reference

When an external identity-federation login fails, the browser is redirected to the ANKASecure console login screen carrying a machine-readable cause and a support reference:

HTTP/1.1 302 Found
Location: https://<edge-host>/admin/login?error=access_not_configured&ref=7c9e6679-7425-40de-944b-e07fc1f90ae7
Content-Length: 0

The console renders a human-readable explanation for the error code and displays the ref. Quote the ref when contacting an operator or support — it is the correlation identifier that ties the failure to the server-side log line and to the audit record.

How this differs from every other page in this reference

Every other error in this reference is an API error: a response body in RFC 7807 Problem Details form, served as application/problem+json, carrying type, title, status, detail, instance, correlationId and timestamp.

This surface is not an API response. It is a browser redirect, and it therefore has:

• no body — Content-Length: 0
• no type — the cause is the error query parameter, not a URI
• no correlationId — the correlation identifier is the ref query parameter
• no status beyond the redirect itself — 302 (OIDC callback, initiate) or 303 See Other (SAML ACS)

Consequently the "Programmatic Error Handling" example on the Error Reference Index, which dispatches on problemDetails.getType(), does not apply here. There is no problem document to dispatch on. A programmatic consumer never reaches this surface: it exists only for a top-level browser navigation.

The boundary rule — when a surface may redirect instead of returning a problem document

A surface may use the browser-redirect error projection if and only if all three conditions hold:

1. the request is a top-level browser navigation that the browser renders as a document;
2. the caller therefore cannot read a response body, so an interposing CDN or proxy may replace it;
3. an equivalent typed RFC 7807 refusal remains available on a non-navigation surface for programmatic consumers.

Every non-navigation surface — fetch/XHR, the SDKs, the CLIs and service-to-service calls — keeps RFC 7807 unconditionally. The redirect is an additional projection of refusals that already exist as typed problem documents; it retires none of them and renumbers none of them.

Three federation legs meet all three conditions and therefore redirect:

The LDAP credential login leg (POST /api/v3/auth/idp/ldap/login) does not redirect on failure. It fails condition (2): its caller is a JSON-consuming XHR that can read the response body, so the body is never replaced by an interposing CDN. It continues to return 200, 401 and 503 as application/problem+json, byte-identical to before.

Disambiguation from the OAuth 2.0 invalid_request problem type

This reference already documents an error named invalid_request (400). It is a different thing, and the two must not be conflated:

Both are named invalid_request deliberately, because both take the name from RFC 6749. The underscore form used by the ANKASecure OAuth 2.0 error pages exists precisely so the RFC 7807 type suffix matches the RFC 6749 error code exactly; the federated-login redirect uses the RFC 6749 name in the redirect-parameter sense the RFC defines for it, which is the closer of the two readings. No page named invalid_request.md is created for this surface — every code is documented here, on one page.

The six codes

The set is closed. A code is never derived from upstream text, so an identity provider cannot inject a value; a value outside this set is treated by the console as unrecognised and rendered generically.

What each code projects

Each code is the browser projection of one or more typed RFC 7807 refusals that are unchanged on every non-navigation surface:

Why the unverified email is told apart and the email collision is not

Two refusals arise from the same place — the identity slot, after the platform has already agreed the identity's roles are grantable — and they are deliberately projected differently.

• The provider asserted an email it did not confirm. That is a fact about the provider's own assertion, and it discloses nothing about ANKASecure: whether an account exists here, whether the address is in use, and whether the tenant has any users are all unchanged by it. So it gets its own code, identity_provider_email_unverified, because the person who can fix it is the administrator of the identity provider and telling them "access is not configured" sends them to the wrong administrator.
• The address is already owned by another account in the tenant. Telling an unauthenticated caller that would confirm an account exists for that address — the account-existence oracle the collapse exists to prevent. It therefore keeps access_not_configured, byte-identical to a plain admission denial.

Codes never reveal which user, tenant or rule was involved

Every code is oracle-safe. The redirect reveals nothing about whether a user, a tenant, a provider or an admission rule exists. In particular access_not_configured is byte-identical whether the user matched no rule at all, matched a rule naming a role that does not exist, matched a rule naming a role that cannot be assigned in the owning tenant type, was stopped by a domain guard, or presented an email address already owned in the tenant. identity_provider_email_unverified reports only what the provider did not assert, and is likewise byte-identical whatever the platform holds. Diagnosis is performed from the server-side record keyed by ref, never from the response.

Using the ref

ref is a server-authored UUID. It is never taken from a client-supplied value on this surface, and the console validates its shape before rendering it.

For an end user: quote the ref verbatim to whoever administers your ANKASecure deployment.

For an operator: the same value appears in the auth-api log line for the failure, in the admin-api log line for the specific cause, and in the correlationId of the audit event recording the refusal — so one lookup resolves the whole path. The internal troubleshooting runbook describes that lookup.

Verifying on a non-SaaS deployment

initiate's invalid_request arm is reachable only on SaaS deployments. On a private-cloud or on-premise deployment, initiate resolves the deployment-default provider directly and never takes the branch that validates a submitted login address, so the code it can emit is identity_provider_not_configured (or identity_provider_unavailable), not invalid_request.

Measured on the development environment: GET https://dev.ankatech.co/api/v3/auth/idp/initiate returns 503 upstream and therefore redirects with error=identity_provider_not_configured. That is correct behaviour, not a defect — do not file it as one. To exercise the invalid_request arm, use a SaaS deployment.

Related

• Error Reference Index — the RFC 7807 contract for all API errors
• Invalid Request (400) — the OAuth 2.0 token-endpoint error of the same name
• Forbidden (403) — the general authorization refusal
• Service Unavailable (503) — the general availability refusal