Troubleshooting: identity
Refused tokens, scopes, API keys, client certificates and CORS origins: the symptom, its cause and what to do.
TroubleshootingOperationsSince version 0.3.0
Operations guide: configure, deploy and observe the gateway. What the feature does, product side: product guide; calling it: developer guide.
| Symptom | Cause | Action |
|---|---|---|
401 on valid tokens right after a start |
The issuer's keys are not loaded yet | The log says issuer not reachable yet; check the gateway reaches the discovery URL |
401 invalid_token on a token that works elsewhere |
Audience, issuer or algorithm: the reason is in the log (token refused), never in the response |
Compare the token's aud and iss with auth.issuers |
403 insufficient_scope |
The token lacks the scope or role the contract requires | Read scope= in WWW-Authenticate; for a role, check roles_claim |
401 WWW-Authenticate: ApiKey on a key believed good |
Unknown key (removed, mistyped), expired, or without the fwk_ prefix |
The log (API key refused) gives the cause and, for an expired key, its id; create a new one |
401 "does not accept API keys" |
The operation has no apiKey alternative in the contract |
Add { key: [] } to its security, if intended |
403 "not bound to this operation" (key or certificate) |
The entry does not name this operation | Add the operationId to the entry's operations; reload |
| Refused at load "no contract declares" on a key or a certificate | The entry names an operation that does not exist (renamed?) | Fix the operationId |
401 "requires a client certificate" despite a certificate |
Undeclared certificate, or x-forwarded-client-cert from a peer outside server.trusted_proxies |
Check the URI SAN or subject against auth.mtls.clients; declare the edge's range |
TLS handshake refused on :8443 |
A client certificate from another authority than client_ca_file |
Add the authority to the file: it is re-read without a restart |
403 "This origin is not allowed" |
The browser's origin is in no cors policy |
Add it to allow_origins |