Make errors related to access tokens be more specific and actionable

[eecavanna]

On this branch, I updated the function that processes incoming JWTs so that the user-facing error messages it displays are more specific to the situation and more actionable.

Details

Previously, the error message in all scenarios was the same:

• Could not validate credentials

Now, there are several error messages, all actionable, and some include additional details that could help "support staff" distinguish bug reports from one another.

• Access token is invalid. Please log in again. Details: The access token contains an invalid subject.
• Access token is invalid. Please log in again. Details: The access token contains invalid claims.
• Access token is invalid. Please log in again.
• Access token has been invalidated. Please log in again.
• Access token has expired. Please log in again.
• Access token is invalid or missing. Please log in again.

For example:

$ curl http://127.0.0.1:8000/users/me
{"detail":"Access token is invalid or missing. Please log in again."}

I consider this to be an improvement over what was there before. For the longer term: I think we (i.e. someone) will revisit this code when we overhaul the auth system.

Related issue(s)

Fixes #1267

Related subsystem(s)

• Runtime API (except the Minter)
• Minter
• Dagster
• Project documentation (in the docs directory)
• Translators (metadata ingest pipelines)
• MongoDB migrations
• Other

The authentication flow.

Testing

• I tested these changes (explain below)
• I did not test these changes

I tested these changes by confirming all tests pass.

Documentation

• I have not checked for relevant documentation yet (e.g. in the docs directory)
• I have updated all relevant documentation so it will remain accurate
• Other (explain below)

Maintainability

• Every Python function I defined includes a docstring (test functions are exempt from this)
• Every Python function parameter I introduced includes a type hint (e.g. study_id: str)
• All "to do" or "fix me" Python comments I added begin with either # TODO or # FIXME
• I used black to format all the Python files I created/modified
• The PR title is in the imperative mood (e.g. "Do X") and not the declarative mood (e.g. "Does X" or "Did X")

[Copilot]

Pull Request Overview

This PR improves error handling for JWT access token validation by replacing generic credential error messages with specific, actionable error messages that provide clear guidance to users.

• Introduces granular error handling for different JWT validation failure scenarios
• Adds detailed error messages that distinguish between invalid subjects, claims errors, expired tokens, and invalidated tokens
• Improves logging by replacing print statements with proper logging and adding exception logging

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[hesspnnl]

Overall this looks good. I think there could still be confusion around what "subject" or "claims" means. It could be good to instead say more plainly what subject and claims means to the support staff. Other than that this is a great addition and provides more information! Optional change as I know there are other priorities right now.

[eecavanna]

Thanks, @hesspnnl.

I agree with you that these messages present the words "subject" and "claims" without having introduced the reader to what they are. Thanks for bringing this up. I think I am going to revise this PR so that those words aren't shown to the end user, and are only shown in the server-side logs.

As far as educating support people about them, I'll add a comment to the code (later, but before merging), containing the URL of a related reference (i.e. https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-token-claims, which is about "claims", one of which is the "subject" claim).

[eecavanna]

Tests are passing locally (make test), but failing on GHA.

[eecavanna]

The same test is currently failing on the main branch also.

[eecavanna]

Looks like @hesspnnl has implemented a fix for the failing test, in PR #1293. Merging this one now.