OAuth Working Group JT. Turrado Internet-Draft FE. Escolar Intended status: Standards Track Independent Expires: 30 March 2026 26 September 2025 OAuth 2.0 External Assertion Authorization Grant draft-external-assertion-oauth-grant-00 Abstract This document specifies a new OAuth 2.0 authorization grant type, "external assertion", identified by urn:ietf:params:oauth:grant- type:external-assertion. It enables a client to obtain an access token by presenting a verifiable JWT assertion issued by a trusted external identity provider to an authorization server. The mechanism facilitates short-lived, auditable credentials for workloads without provisioning long-lived secrets. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 30 March 2026. Copyright Notice Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved. Turrado & Escolar Expires 30 March 2026 [Page 1] Internet-Draft OAuth2 External Assertion Grant September 2025 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Conventions and Definitions . . . . . . . . . . . . . . . . . 2 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 3 4. External Assertion Grant Type . . . . . . . . . . . . . . . . 3 4.1. Token Request . . . . . . . . . . . . . . . . . . . . . . 3 4.2. Assertion Validation . . . . . . . . . . . . . . . . . . 4 4.3. Token Response . . . . . . . . . . . . . . . . . . . . . 5 4.4. Error Response . . . . . . . . . . . . . . . . . . . . . 5 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 6. Privacy Considerations . . . . . . . . . . . . . . . . . . . 6 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 8. Normative References . . . . . . . . . . . . . . . . . . . . 7 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 7 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 1. Conventions and Definitions The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 ([RFC2119], [RFC8174]) when, and only when, they appear in all capitals, as shown here. Authorization Server (AS): The OAuth 2.0 server that issues access tokens. External Identity Provider (External IdP): An OAuth 2.0/OpenID Connect compliant identity provider that issues JWT assertions trusted by the AS. Assertion: A signed JWT bearing claims used by the AS to authenticate and authorize the client for token issuance. Turrado & Escolar Expires 30 March 2026 [Page 2] Internet-Draft OAuth2 External Assertion Grant September 2025 2. Introduction The OAuth 2.0 Authorization Framework ([RFC6749]) defines multiple grant types for obtaining access tokens. In many environments, workloads already possess identities issued by an external IdP. In order to interact with a resource server that relies on an AS different from the external IdP, a mechanism is needed to exchange the external identity for a locally-issued access token without provisioning long-lived secrets. This document defines the "external assertion" grant type, identified by urn:ietf:params:oauth:grant-type:external-assertion, which allows a client to present a verifiable JWT assertion issued by a trusted external IdP to an AS in exchange for a short-lived access token. The grant is conceptually similar to token exchange ([RFC8693]) but is narrowly focused on a client-submitted external JWT assertion used as an authorization grant, and it does not define subject or actor token semantics beyond the validation rules herein. 3. Protocol Overview At a high level, the client obtains a JWT assertion from an external IdP and submits it to the AS's token endpoint using the grant type defined in this document. The AS validates the assertion according to its local trust configuration (e.g., trusted issuers and keys), and, if validation succeeds and policy permits, issues an access token to the client. 4. External Assertion Grant Type 4.1. Token Request The client makes a request to the token endpoint with the content type application/x-www-form-urlencoded as defined in [RFC6749] Appendix B, including the following parameters: grant_type: REQUIRED. Value MUST be urn:ietf:params:oauth:grant- type:external-assertion. client_id: REQUIRED - unless client authentication is otherwise established by means outside of this request. The OAuth client identifier. client_assertion: REQUIRED. A JWT assertion issued by a trusted external IdP. The assertion MUST be integrity-protected (e.g., JWS) and MUST contain the claims specified in Section 4.2. scope: OPTIONAL. The scope of the access request as described in Turrado & Escolar Expires 30 March 2026 [Page 3] Internet-Draft OAuth2 External Assertion Grant September 2025 Section 3.3 of [RFC6749]. Example request: POST /token HTTP/1.1 Host: as.example.com Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:external-assertion& client_id=s6BhdRkqt3& client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... 4.2. Assertion Validation Upon receiving the request, the AS MUST perform all of the following validation steps: Client Authorization Verify the client is recognized, authenticated as required by AS policy, and permitted to use this grant type (unauthorized_client if not). Issuer Trust Ensure the assertion's iss value is configured as a trusted issuer. Trust configuration is out of scope; it may use local policy, static keys, or dynamic discovery (e.g., OpenID Provider configuration and JWKS). Signature Verification Validate the JWS signature using keys associated with the trusted issuer (see [RFC7517] and [RFC7515]). Expiration and Not-Before Enforce exp and, if present, nbf. The assertion MUST be unexpired at the time of processing. Audience Ensure the assertion's aud identifies the AS (e.g., token endpoint or an AS audience value). Subject Validate the sub according to AS policy for the trusted issuer (e.g., allowlists or mappings). JWT ID (Replay) If a jti is present, the AS MUST prevent replay by rejecting previously seen jti values within the assertion's validity window. Use of jti is RECOMMENDED. Issued-At (Freshness) If iat is present, the AS SHOULD enforce a maximum assertion age according to policy. Scope and Policy Enforce that requested scopes are authorized for the client and permitted for the asserted identity. Turrado & Escolar Expires 30 March 2026 [Page 4] Internet-Draft OAuth2 External Assertion Grant September 2025 The assertion MUST be a JWT ([RFC7519]) and MUST include the following claims: iss Issuer identifier of the external IdP. sub Subject identifier at the external IdP. aud Audience for the AS (value defined by AS policy). exp Expiration time. iat Issued-at time (RECOMMENDED). jti JWT ID for replay detection (RECOMMENDED). The assertion SHOULD be signed with an algorithm acceptable to the AS (e.g., RS256 or ES256). Use of none MUST NOT be accepted. If the AS supports nested JWTs, additional confidentiality mechanisms are deployment-specific. 4.3. Token Response If the request is valid and authorized, the AS issues an access token per Section 5.1 of [RFC6749]. A refresh token MUST NOT be issued for this grant type. Example successful response: HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "access_token": "2YotnFZFEjr1zCsicMWpAA", "token_type": "bearer", "expires_in": 3600 } 4.4. Error Response On error, the AS returns an error response as defined in Section 5.2 of [RFC6749]. The following error codes are commonly applicable: invalid_request Malformed or missing parameters. unauthorized_client Client not authorized for this grant. Turrado & Escolar Expires 30 March 2026 [Page 5] Internet-Draft OAuth2 External Assertion Grant September 2025 invalid_grant Assertion invalid, expired, audience mismatch, replayed, or issuer not trusted. unsupported_grant_type Grant type not enabled at the AS. 5. Security Considerations The security of this grant depends on the AS's trust configuration and assertion validation. Deployments MUST: * Restrict trusted issuers and acceptable algorithms by policy. * Validate signatures and enforce exp/nbf strictly. * Bind assertions to the AS via aud; reject generic or missing audiences. * Prevent replay via unique jti and server-side caching within validity windows. * Issue short-lived access tokens and prefer least-privilege scopes. * Use TLS for all endpoints and key retrieval. * Log validation outcomes and consider rate limiting failed attempts. If the AS includes an "actor" representation in issued tokens (e.g., the act claim from [RFC8693]), it SHOULD ensure that privacy and policy constraints are respected. 6. Privacy Considerations Assertions may include identifiers that can correlate clients across services. Deployments SHOULD minimize personally identifiable information in assertions, avoid unnecessary claim propagation into issued tokens, and follow data minimization practices. 7. IANA Considerations This document requests registration of the following value in the "OAuth URI" registry: URN: urn:ietf:params:oauth:grant-type:external-assertion Common Name: External Assertion Grant Change Controller: IESG Specification Document: This document Turrado & Escolar Expires 30 March 2026 [Page 6] Internet-Draft OAuth2 External Assertion Grant September 2025 8. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, . [RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, . [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8693] Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, DOI 10.17487/RFC8693, January 2020, . Appendix A. Acknowledgments The authors thank the OAuth community for prior work on assertion- based flows and token exchange. Authors' Addresses Jorge Turrado Independent Email: jorge_turrado@hotmail.es Fernando Escolar Independent Email: fer.escolar@gmail.com Turrado & Escolar Expires 30 March 2026 [Page 7]