Skip to content

fix(authorization): answer an expired token with 401, not 403 - #206

Open
RHeynsZa wants to merge 1 commit into
awslabs:mainfrom
RHeynsZa:fix/expired-token-401
Open

RHeynsZa wants to merge 1 commit into
awslabs:mainfrom
RHeynsZa:fix/expired-token-401

Conversation

@RHeynsZa

Copy link
Copy Markdown
Contributor

What does this change do?

When an access token has expired, the request authorizer returns a Deny policy, and API Gateway turns that into a 403. Most OAuth clients refresh their token only on a 401, so a client that holds an expired token never refreshes it and just keeps getting 403s. We hit this from a CLI and a portal that call the user API with Cognito tokens.

With this change, an expired token gets a 401:

  • JWTAuthorizer raises a new TokenExpiredError when jwt.decode fails with ExpiredSignatureError, instead of returning False. Logging and the CognitoInvalidToken metric don't change.
  • Authorizer.authorize passes that error up instead of turning it into a Deny, and records a UserUnauthenticated metric.
  • The Lambda handler catches it and raises Exception("Unauthorized"). API Gateway answers 401 only when a Lambda authorizer raises exactly that message (docs).

The DEFAULT_4XX gateway response already adds the CORS headers, so browsers can read the 401.

Everything else still returns a Deny (403): an invalid signature, a token that can't be decoded, the wrong client id or token_use, a failed UserInfo call, and Verified Permissions and project-role denials. Refreshing the token doesn't fix any of these, so I left them alone to keep the change small.

Type of change

  • Bug fix
  • New feature
  • Refactor / tech debt
  • Documentation
  • Infrastructure / CI

How was this tested?

cd backend && uv run pytest app/authorization: 66 passed.

  • test_jwt_authorizer_when_expired_should_raise_token_expired (replaces ..._should_deny)
  • test_authorize_when_token_expired_should_raise_instead_of_deny
  • test_authorizer_lambda_handler_expired_token_returns_401: runs the handler end to end with an expired JWT and checks that it raises Unauthorized

I haven't deployed this yet, so the 401 hasn't been checked against a live API Gateway.

Checklist

  • Follows the guidance in CONTRIBUTING.md
  • Tests added/updated and passing locally
  • Lint / type checks pass locally (black, flake8)
  • No secrets, credentials, or account IDs committed
  • Docs updated if behavior or usage changed
  • Linked the related issue (if any): closes #

Notes for reviewers

  • The web app isn't affected. Amplify refreshes tokens before they expire, and the frontend doesn't check for 401 or 403.
  • A Deny is cached under authorizerResultTtlInSeconds: 1800 for each token, path and method, so the 403 for an expired token could stick around. If I read the docs right, an Unauthorized result isn't cached that way.

Acknowledgment

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

The authorizer turned every failed step into a Deny policy, which API
Gateway returns as 403. Clients usually refresh their access token on
401 only, so an expired token was never refreshed.

The JWT step now raises TokenExpiredError for an expired token, and the
handler raises "Unauthorized", which API Gateway maps to 401. The
DEFAULT_4XX gateway response already adds the CORS headers. All other
failures still return a Deny policy (403).
@RHeynsZa
RHeynsZa requested a review from a team November 17, 2026 08:01
Comment on lines +93 to +95
except TokenExpiredError:
self.__metrics.add_metric(name="UserUnauthenticated", unit=MetricUnit.Count, value=1)
raise

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let me know if this metric is overkill @raphaho

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant