Azure AD Token Issuer Mismatch: Resolving sts.windows.net vs login.microsoftonline.com
Working with Azure Active Directory authentication can sometimes present unexpected challenges. One such issue that frequently surfaces in development teams involves receiving access tokens with an unexpected issuer claim. Specifically, applications may receive tokens issued by sts.windows.net when the expected issuer should be login.microsoftonline.com.
This discrepancy often leads to authentication failures and can be particularly frustrating when working with third-party integrations or modern authentication frameworks that expect specific token formats.
Problem Analysis
The issue manifests when examining the iss (issuer) claim within access tokens. Instead of the anticipated modern issuer format, developers encounter:
- Received:
https://sts.windows.net/{tenant-id}/ - Expected:
https://login.microsoftonline.com/{tenant-id}/v2.0
This difference stems from Azure AD's dual token versioning system, where applications can receive tokens in either v1.0 or v2.0 format depending on their configuration.
Token Format Differences
Azure AD maintains two distinct token formats to ensure backward compatibility while supporting modern authentication requirements:
- Uses
sts.windows.netas the issuer - Primarily designed for work and school accounts
- Represents the legacy token structure
- Automatically assigned to applications without explicit version specification
- Uses
login.microsoftonline.comas the issuer - Supports both personal and organizational accounts
- Provides enhanced OpenID Connect compatibility
- Offers improved claim structure and additional features
Implementation Solution
The resolution requires modifying the application registration's manifest to explicitly request v2.0 tokens. This involves updating the accessTokenAcceptedVersion property.
Configuration Steps
1. Access Application Registration Navigate to the Azure Portal and locate the application registration under Azure Active Directory > App registrations.
2. Open Application Manifest Select the target application and access the "Manifest" section from the left navigation panel.
3. Modify Token Version Locate the accessTokenAcceptedVersion property and update its value:
"accessTokenAcceptedVersion": 2
4. Apply Changes Save the manifest and allow several minutes for the changes to propagate across Azure AD infrastructure.
Technical Implications
The token format has several downstream effects on application behavior and integration patterns:
Validation Logic: Applications performing issuer validation must account for the correct expected format. Hardcoded validation against a specific issuer will fail if the token format differs from expectations.
Library Compatibility: Modern authentication libraries, particularly those implementing OpenID Connect, often expect v2.0 token formats. Using v1.0 tokens may result in compatibility issues or reduced functionality.
Claims Structure: While both versions contain similar core claims, the structure and availability of certain claims may differ between versions.
Migration Considerations
Organizations planning to update existing applications should evaluate several factors:
Testing Requirements: Comprehensive testing across all authentication flows ensures that the token format change doesn't introduce regressions.
Dependent Systems: Any downstream services consuming these tokens must be evaluated for compatibility with the new issuer format.
Rollback Planning: Understanding how to revert changes quickly is essential for production environments.
Best Practices
New Application Development When creating new Azure AD integrations, explicitly set accessTokenAcceptedVersion to 2 during the initial application registration process.
Authentication Library Selection Utilize Microsoft Authentication Library (MSAL) which naturally aligns with v2.0 endpoints and token formats.
Environment Management Test token format changes in development and staging environments before implementing in production systems.
Alternative Approaches
In scenarios where modifying the application manifest isn't feasible, consider these alternatives:
- Update token validation logic to accept multiple issuer formats
- Implement conditional validation based on token version detection
- Create a new application registration with v2.0 configuration
Conclusion
The token issuer mismatch between sts.windows.net and login.microsoftonline.com represents a common configuration issue rather than a system malfunction. Understanding Azure AD's token versioning system and appropriately configuring the accessTokenAcceptedVersion property resolves this issue while positioning applications for better compatibility with modern authentication standards.
The transition from v1.0 to v2.0 tokens not only addresses immediate issuer validation concerns but also provides access to enhanced authentication features and improved integration capabilities with contemporary identity management systems.