Authentication tokens serve a fundamental purpose: to verify whether a caller is authorized to perform a specific action. However, they are not designed to function as a stable data interface or a reliable schema for application logic.
Token Claims Are Not Guaranteed
While tokens may seem readable at present, this was never an assurance. The contents of tokens have never been publicly documented, allowing for changes to token claims at any time and for any reason. Developers should be aware that claims can change, become optional, be renamed, or even be removed entirely. Relying on decoded token contents is considered an unsupported and fragile practice.
Upcoming Changes
This summer, Azure DevOps will implement further encryption of authentication tokens. Some changes may occur even sooner as the token formats evolve. As a result, token payloads will become unreadable by clients, which will disrupt any applications that depend on decoding tokens to extract claims. Conversely, applications that already treat tokens as opaque will remain unaffected.
Best Practices Moving Forward
Tokens should strictly be used for authorization purposes. After obtaining a token, applications should leverage supported Azure DevOps REST APIs to access user or organization data. These APIs provide stable contracts and clear documentation regarding changes, unlike token claims.
Key guidelines include:
- Use tokens solely to verify the identity and permissions of the caller.
- Utilize supported APIs for actual data retrieval.
- Be prepared for any token claim to change or be removed without prior notice.
Developers decoding tokens to access values should reconsider this approach.
A Final Reminder
For applications relying on decoded token claims, this serves as a warning to transition away from that pattern before the encryption measures take effect this summer. Authentication tokens are meant for authentication and authorization, not for accessing data. They should be treated as opaque, with data access routed through supported APIs.
