Feature Overview (aka. goal summary)

Enable Red Hat Quay to natively support Microsoft Entra ID v2.0 access tokens for direct API authentication, eliminating the need for token exchange workarounds.

Currently, Quay's OIDC implementation enforces strict single-issuer validation that only accepts legacy v1.0 tokens (sts.windows.net), blocking modern authentication flows that use the v2.0 issuer (login.microsoftonline.com/.../v2.0).

This feature extends Quay's OIDC authentication to:

• Accept tokens from multiple issuers per provider (enabling simultaneous v1.0 and v2.0 support)
• Support flexible audience validation for On-Behalf-Of (OBO) flows
• Enable keyless authentication patterns required for Zero Trust architectures

Note: This unblocks strategic Red Hat integrations including Red Hat Developer Hub (RHDH) and Red Hat Dev Spaces

Goals (aka. expected user outcomes)

The primary goal is to enable Quay to act as a proper OIDC Resource Server capable of validating modern Microsoft Entra ID tokens without requiring intermediate token exchanges.

This feature empowers users to:

• Use Modern Auth Flows: Authenticate with Quay using v2.0 access tokens from RHDH, Dev Spaces, and other tools leveraging current Microsoft identity standards.

• Implement Zero Trust: Eliminate long-lived static secrets (OAuth tokens, robot passwords) by using short-lived OIDC tokens directly against the Quay API.

• Support On-Behalf-Of Flows: Allow upstream services (like RHDH) to call Quay on behalf of authenticated users using downstream tokens with custom audience claims.

• Maintain Backward Compatibility: Continue supporting v1.0 tokens during migration periods by configuring both issuers simultaneously.

• Simplify Configuration: Use a single OIDC provider configuration for multiple token versions without complex workarounds.

Background

Microsoft Entra ID Token Evolution

Microsoft Entra ID (formerly Azure AD) has two token endpoint versions:

• v1.0: Legacy endpoint using issuer https://sts.windows.net/\ {tenant}/
• v2.0: Current standard using issuer {{https://login.microsoftonline.com/\ {tenant}
  /v2.0}}

Microsoft's documentation and tooling default to v2.0 for new integrations, treating it as the modern standard.

The Current Gap

Red Hat Quay currently:

• Supports OIDC: Has robust OIDC authentication via *_LOGIN_CONFIG blocks
• Strict Issuer Matching: Performs exact string comparison for issuer validation (oauth/loginmanager.py)
• Hardcoded Audience: Always validates aud claim against CLIENT_ID (oauth/oidc.py)
• Uses Workarounds: Disables audience validation (verify_aud: False) to accommodate some flows, creating security gaps

The Problem: When users configure Quay with the v2.0 issuer, v1.0 tokens are rejected (and vice versa). When RHDH uses OBO flows, tokens have aud set to the downstream API (api://quay-api) rather than the client ID, causing validation failures.

Customer Impact

This blocks customers from:

• Integrating RHDH with Quay (OBO flow requires v2.0 tokens with custom audiences)
• Using Dev Spaces for container development (uses Device Code flow with v2.0)
• Implementing Zero Trust architectures that eliminate static credentials
• Following Microsoft's current authentication best practices

Requirements (aka. acceptance criteria)

• Quay accepts OIDC tokens from multiple issuers configured for a single provider via a new OIDC_ISSUERS configuration field (list).

• Quay supports flexible audience validation via a new OIDC_AUDIENCES configuration field (list) to handle OBO flows where aud ≠ CLIENT_ID.

• By default, Quay maintains backward compatibility by supporting single OIDC_ISSUER and defaulting audience validation to CLIENT_ID.

• The issuer matching logic (oauth/loginmanager.py) checks tokens against all configured issuers for a provider, not just a single issuer.

• The JWT validation logic (oauth/oidc.py) attempts to decode tokens with each configured issuer until one succeeds.

• The JWT validation logic validates the aud claim against all configured audiences, not just the client ID.

• The existing verify_aud: False workaround in auth/oauth.py is removed and replaced with proper audience list validation.

• Quay extracts and logs the azp (authorized party) claim for audit purposes when OBO tokens are used.

• Users can optionally configure an OIDC_ALLOWED_CLIENTS whitelist to restrict which client IDs are permitted to act on behalf of users.

• All authentication paths (web UI, API endpoints, federated robot auth) consistently support multi-issuer and multi-audience validation.

• Configuration validation ensures OIDC_ISSUERS and OIDC_AUDIENCES are lists (if provided) and logs clear error messages if misconfigured.

Use cases

• Scenario 1: RHDH Integration with OBO Flow
  • As a: Platform Engineer using Red Hat Developer Hub,
  • I want to: authenticate users via RHDH and have RHDH call Quay APIs on their behalf without storing Quay credentials.
  • So that: Users can trigger image builds and deployments from RHDH templates while maintaining proper authentication trails and eliminating shared secrets.

• Scenario 2: Migration from v1.0 to v2.0
  • As a: Quay Administrator migrating to modern authentication,
  • I want to: configure Quay to accept both v1.0 and v2.0 tokens during a transition period.
  • So that: I can update my Azure app registration to v2.0 without breaking existing integrations that still use v1.0 tokens.

• Scenario 3: Zero Trust Architecture
  • As a: Security Operations Engineer,
  • I want to: eliminate all long-lived static credentials (OAuth tokens, robot passwords) from my container registry.
  • So that: All API access uses short-lived OIDC tokens that expire automatically, reducing the attack surface and simplifying secret rotation.

• Scenario 4: Dev Spaces Integration
  • As a: Developer using Red Hat Dev Spaces,
  • I want to: push and pull container images directly from my development workspace using my corporate identity.
  • So that: I don't need to manage separate registry credentials and my access automatically follows corporate identity policies.

• Scenario 5: Custom Tooling with Service Accounts
  • As a: DevOps Engineer building custom CI/CD tooling,
  • I want to: obtain Entra ID service principal tokens and use them directly with Quay APIs.
  • So that: My automation can access Quay without managing separate credential stores, using Azure Key Vault or Managed Identity instead.

Out of scope

• Automatic Issuer Discovery: This work does not implement automatic detection of multiple issuers from OIDC discovery. Administrators must explicitly configure OIDC_ISSUERS.

• Dynamic Audience Resolution: Quay will not automatically discover valid audiences. Administrators must explicitly configure OIDC_AUDIENCES for OBO flows.

• Token Exchange Protocol (RFC 8693): This feature enables direct token validation, not token exchange. The existing Robot Federation feature handles token exchange separately.

• Token Revocation Checks: Quay validates token signatures and expiration but does not check real-time revocation status against Microsoft's revocation endpoints.

• Multi-Tenant Wildcards: Accepting tokens from any Azure tenant (*/v2.0) is intentionally not supported for security reasons. Each tenant must be explicitly configured.

Documentation considerations

• Documentation explains the single vs. multi-issuer configuration with clear examples for both Microsoft Entra ID v1.0 and v2.0.

• Provide a migration guide for customers moving from v1.0 to v2.0, including how to configure dual-issuer support during the transition.

• Document the OBO flow configuration with specific instructions for RHDH integration, including Azure Portal setup and OIDC_AUDIENCES configuration.

• Explain the security implications of OIDC_AUDIENCES configuration and best practices for limiting accepted audiences.

• Document the OIDC_ALLOWED_CLIENTS whitelist feature and when to use it for enhanced security.

• Provide Azure Portal setup instructions including:
  • Setting accessTokenAcceptedVersion: 2 in the app manifest
  • Exposing API scopes for OBO flows
  • Authorizing client applications

• Include troubleshooting section covering common issues:
  • "Issuer not configured" errors
  • "Invalid audience" errors
  • Token signature verification failures
  • Authorized party rejections

• Update or remove any existing documentation that discourages using login.microsoftonline.com or recommends sts.windows.net

Dependencies

• PyJWT library: Already supports list of audiences (no upgrade needed)
• Azure Portal access: Required for customer testing and validation
• RHDH integration: Optional for E2E OBO flow testing
• Quay Operator: No changes needed (YAML config passes through transparently)

References

• Customer RFE: https://issues.redhat.com/browse/RFE-8691
• Microsoft OBO Flow Documentation: https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-on-behalf-of-flow
• Microsoft Token Reference: https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens
• Quay OIDC Implementation: oauth/oidc.py, oauth/loginmanager.py, auth/oauth.py