Internet-Draft | ID Token Authz Grant | October 2024 |
Parecki & McGuinness | Expires 23 April 2025 | [Page] |
- Workgroup:
- Web Authorization Protocol
- Internet-Draft:
- draft-parecki-oauth-identity-assertion-authz-grant-02
- Published:
- Intended Status:
- Standards Track
- Expires:
Identity Assertion Authorization Grant
Abstract
This specification provides a mechanism for an application to use an identity assertion to obtain an access token for a third-party API using Token Exchange [RFC8693] and JWT Profile for OAuth 2.0 Authorization Grants [RFC7523].¶
About This Document
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://drafts.aaronpk.com/draft-parecki-oauth-identity-assertion-authz-grant/draft-parecki-oauth-identity-assertion-authz-grant.html. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-parecki-oauth-identity-assertion-authz-grant/.¶
Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (mailto:oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/. Subscribe at https://www.ietf.org/mailman/listinfo/oauth/.¶
Source for this draft and an issue tracker can be found at https://github.com/aaronpk/draft-parecki-oauth-identity-assertion-authz-grant.¶
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 23 April 2025.¶
Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
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.¶
1. Introduction
The draft specification Identity Chaining Across Trust Domains [I-D.ietf-oauth-identity-chaining] defines how to request a JWT authorization grant from an Authorization Server and exchange it for an Access Token at another Authorization Server in a different trust domain. The specification is an application of a combination of OAuth 2.0 Token Exchange [RFC8693] and JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants [RFC7523]. The draft supports multiple different use cases by leaving many details of the token exchange request and JWT authorization grant unspecified.¶
This specification defines the additional details necessary to support interoperable implementations when using identity tokens as the input to the token exchange request. This specification assumes that there is a single authorization server that is trusted by two applications in different trust domains, as typically found in an enterprise scenario where the two applications allow users to log in using the same enterprise identity provider. The same enterprise identity provider that is trusted by applications for single sign-on can be extended to broker access to APIs as well.¶
2. 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.¶
2.1. Roles
- Client
-
Application that wants to obtain an OAuth 2.0 access token on behalf of a signed-in user to an external/3rd party application's API (Resource Server below). In [I-D.ietf-oauth-identity-chaining], this is the Client in trust domain A.¶
- Resource Application
-
Application that provides an OAuth 2.0 Protected Resource. In [I-D.ietf-oauth-identity-chaining], this is the Protected Resource in trust domain B.¶
- Authorization Server (IdP)
-
The Identity Provider that is trusted by a set of applications in an organization's app ecosystem. In [I-D.ietf-oauth-identity-chaining], this is the Authorization Server in trust domain A, which is also trusted by the Authorization Server of the Protected Resource in trust domain B.¶
3. Overview
The example flow is for an enterprise acme
, which uses a wiki app and chat app from different vendors, both of which are integrated into the enterprise's Identity Provider using OpenID Connect.¶
Role | App URL | Tenant URL | Description |
---|---|---|---|
Client |
https://wiki.example
|
https://acme.wiki.example
|
Wiki app that embeds content from one or more resource applications |
Resource Application |
https://chat.example
|
https://acme.chat.example
|
Chat and communication app |
Identity Provider |
https://idp.example
|
https://acme.idp.example
|
Identity Provider |
Sequence Diagram¶
+---------+ +--------------+ +---------------+ +--------------+ | | | | | Resource | | Resource | | | | IdP | | Application | | Application | | Client | | Authorization| | Authorization | | Resource | | | | Server | | Server | | Server | +----+----+ +-------+------+ +-------+-------+ +------+-------+ | | | | | | | | | --------------> | | | | 1 User SSO | | | | | | | | ID Token | | | | <- - - - - - - - | | | | | | | | | | | | | | | | 2 Token Exchange | | | | ----------------> | | | | | | | | ID-JAG | | | | <- - - - - - - - | | | | | | | | | | | | | | | | 3 Present ID-JAG | | | | ------------------+----------------> | | | | | | | Access Token | | | | <- - - - - - - - - - - - - - - - - - | | | | | | | | | | | | | | | 4 Resource Request with Access Token| | | -----------------------------------------------------> | | | | | | | | | | | | |¶
-
User logs in to the Client, the Client obtains the Identity Assertion (e.g. OpenID Connect ID Token or SAML assertion)¶
-
Client uses the Identity Assertion to request an Identity Assertion Authorization Grant for the Resource Application from the IdP¶
-
Client exchanges the Identity Assertion Authorization Grant JWT for an Access Token at the Resource Application's token endpoint¶
-
Client makes an API request with the Access Token¶
This specification is constrained to deployments where all Resource Application Resource Servers are leveraging the same IdP Authorization Server for Single-Sign-On (SSO) and session management services. The IdP provides a consistent trust boundary enabling the set of Resource Application Authorization Servers to honor the JWT Authorization Grant (ID-JAG) issued by the IdP. This specification also assumes that the Resource Server Authorization Servers delegate user authorization authority to the IdP (e.g. the IdP is trusted to ensure the scopes identified in the ID-JAG have been correctly authorized before issuing the ID-JAG token).¶
4. User Authentication
The Client initiates an authentication request with the IdP using OpenID Connect or SAML.¶
The following is an example using OpenID Connect¶
302 Redirect Location: https://acme.idp.example/authorize?response_type=code&scope=openid&client_id=...¶
The user authenticates with the IdP, and is redirected back to the Client with an authorization code, which it can then exchange for an ID Token.¶
Note: The Enterprise IdP may enforce security controls such as multi-factor authentication before granting the user access to the Client.¶
POST /token HTTP/1.1 Host: acme.idp.example Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code=..... HTTP/1.1 200 Ok Content-Type: application/json { "id_token": "eyJraWQiOiJzMTZ0cVNtODhwREo4VGZCXzdrSEtQ...", "token_type": "Bearer", "access_token": "7SliwCQP1brGdjBtsaMnXo", "scope": "openid" }¶
5. Token Exchange
The Client makes a Token Exchange [RFC8693] request to the IdP's Token Endpoint with the following parameters:¶
-
requested_token_type
: -
REQUIRED - The value
urn:ietf:params:oauth:token-type:id-jag
indicates that an ID Assertion JWT is being requested.¶ -
resource
: -
REQUIRED - The Issuer URL of the Resource Application's authorization server.¶
-
audience
: -
The audience parameter MUST NOT be used.¶
-
scope
: -
OPTIONAL - The space-separated list of scopes at the Resource Application that is being requested.¶
-
subject_token
: -
REQUIRED - The identity assertion (e.g. the OpenID Connect ID Token or SAML assertion) for the target end-user.¶
-
subject_token_type
: -
REQUIRED - An identifier, as described in Section 3 of [RFC8693], that indicates the type of the security token in the
subject_token
parameter. For an OpenID Connect ID Token:urn:ietf:params:oauth:token-type:id_token
, or for a SAML assertion:urn:ietf:params:oauth:token-type:saml2
.¶
The additional parameters defined in Section 2.1 of [RFC8693] actor_token
and actor_token_type
are not used in this specification.¶
Client authentication to the authorization server is done using the standard mechanisms provided by OAuth 2.0. Section 2.3.1 of [RFC6749] defines password-based authentication of the client (client_id
and client_secret
), however, client authentication is extensible and other mechanisms are possible. For example, [RFC7523] defines client authentication using bearer JSON Web Tokens using client_assertion
and client_assertion_type
.¶
The example below uses an ID Token as the Identity Assertion, and uses a JWT Bearer Assertion ([RFC7523]) as the client authentication method, (tokens truncated for brevity):¶
POST /oauth2/token HTTP/1.1 Host: acme.idp.example Content-Type: application/x-www-form-urlencoded grant_type=urn:ietf:params:oauth:grant-type:token-exchange &requested_token_type=urn:ietf:params:oauth:token-type:id-jag &resource=https://acme.chat.example/ &scope=chat.read+chat.history &subject_token=eyJraWQiOiJzMTZ0cVNtODhwREo4VGZCXzdrSEtQ... &subject_token_type=urn:ietf:params:oauth:token-type:id_token &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer &client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0...¶
5.1. Processing Rules
The IdP MUST validate the subject token, and MUST validate that the audience of the Subject Token (e.g. the aud
claim of the ID Token) matches the client_id
of the client authentication of the request.¶
The IdP evaluates administrator-defined policy for the token exchange request and determines if the client should be granted access to act on behalf of the subject for the target audience and scopes.¶
The IdP may also introspect the authentication context described in the SSO assertion to determine if step-up authentication is required.¶
5.2. Response
If access is granted, the IdP creates a signed Identity Assertion Authorization Grant JWT and returns it in the token exchange response defined in Section 2.2 of [RFC8693]:¶
HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store Pragma: no-cache { "issued_token_type": "urn:ietf:params:oauth:token-type:id-jag", "access_token": "eyJhbGciOiJIUzI1NiIsI...", "token_type": "N_A", "scope": "chat.read chat.history", "expires_in": 300 }¶
-
issued_token_type
: -
REQUIRED -
urn:ietf:params:oauth:token-type:id-jag
¶ -
access_token
: -
REQUIRED - The Identity Assertion Authorization Grant JWT. (Note: Token Exchange requires the
access_token
response parameter for historical reasons, even though this is not an OAuth access token.)¶ -
token_type
: -
REQUIRED -
N_A
(because this is not an OAuth access token.)¶ -
scope
: -
OPTIONAL if the scope of the issued token is identical to the scope requested by the client; otherwise, it is REQUIRED. This may be fewer scopes than the application requested based on various policies in the IdP.¶
-
expires_in
: -
RECOMMENDED - The lifetime in seconds of the authorization grant.¶
-
refresh_token
: -
OPTIONAL according to Section 2.2 of [RFC8693]. In the context of this specification, this parameter SHOULD NOT be used.¶
5.2.1. Error Response
On an error condition, the IdP returns an OAuth 2.0 Token Error response as defined in Section 5.2 of [RFC6749], e.g:¶
HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store { "error": "invalid_grant", "error_description": "Audience validation failed" }¶
6. Access Token Request
The Client makes an access token request to the Resource Application's token endpoint using the previously obtained Identity Assertion Authorization Grant as a JWT Assertion as defined by [RFC7523].¶
-
grant_type
: -
REQUIRED - The value of
grant_type
isurn:ietf:params:oauth:grant-type:jwt-bearer
¶ -
assertion
: -
REQUIRED - The Identity Assertion Authorization Grant JWT obtained in the previous token exchange step¶
The Client authenticates with its credentials as registered with the Resource Application's authorization server.¶
For example:¶
POST /oauth2/token HTTP/1.1 Host: acme.chat.example Authorization: Basic yZS1yYW5kb20tc2VjcmV0v3JOkF0XG5Qx2 grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer assertion=eyJhbGciOiJIUzI1NiIsI...¶
6.1. Processing Rules
All of Section 5.2 of [RFC7521] applies, in addition to the following processing rules:¶
6.2. Response
The Resource Application token endpoint responds with an OAuth 2.0 Token Response, e.g.:¶
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { "token_type": "Bearer", "access_token": "2YotnFZFEjr1zCsicMWpAA", "expires_in": 86400, "scope": "chat.read chat.history", "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", }¶
7. Security Considerations
7.1. Client Authentication
This specification SHOULD only be supported for confidential clients. Public clients SHOULD redirect the user with an OAuth 2.0 Authorization Request.¶
7.2. Step-Up Authentication
In the initial token exchange request, the IdP may require step-up authentication for the subject if the authentication context in the subject's assertion does not meet policy requirements. An insufficient_user_authentication
OAuth error response may be returned to convey the authentication requirements back to the client similar to OAuth 2.0 Step-up Authentication Challenge Protocol [RFC9470].¶
HTTP/1.1 400 Bad Request Content-Type: application/json Cache-Control: no-store { "error": "insufficient_user_authentication", "error_description": "Subject doesn't meet authentication requirements", "max_age": 5 }¶
The Client would need to redirect the user back to the IdP to obtain a new assertion that meets the requirements and retry the token exchange.¶
TBD: It may make more sense to request the Identity Assertion Authorization Grant as an additional response_type
on the authorization request if using OIDC for SSO when performing a step-up to skip the need for additional token exchange round-trip.¶
7.3. Cross-Domain Use
This specification is intended for cross-domain uses where the Client, Resource App, and Identity Provider are all in different trust domains. In particular, the Identity Provider SHOULD NOT issue access tokens in response to an ID-JAG it issued itself. Doing so could lead to unintentional broadening of the scope of authorization.¶
8. IANA Considerations
8.1. Media Types
This section registers oauth-id-jag+jwt
, a new media type [RFC2046] in the "Media Types" registry [IANA.MediaTypes] in the manner described in [RFC6838]. It can be used to indicate that the content is a Identity Assertion Authorization Grant JWT.¶
8.2. OAuth URI Registration
This section registers urn:ietf:params:oauth:token-type:id-jag
in the "OAuth URI" subregistry of the "OAuth Parameters" registry [IANA.oauth-parameters].¶
9. References
9.1. Normative References
- [I-D.ietf-oauth-identity-chaining]
- Schwenkschuster, A., Kasselman, P., Burgin, K., Jenkins, M. J., and B. Campbell, "OAuth Identity and Authorization Chaining Across Domains", Work in Progress, Internet-Draft, draft-ietf-oauth-identity-chaining-02, , <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-identity-chaining-02>.
- [IANA.MediaTypes]
- "*** BROKEN REFERENCE ***".
- [IANA.oauth-parameters]
- IANA, "OAuth Parameters", <https://www.iana.org/assignments/oauth-parameters>.
- [RFC2046]
- Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, DOI 10.17487/RFC2046, , <https://www.rfc-editor.org/rfc/rfc2046>.
- [RFC2119]
- Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
- [RFC6749]
- Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/rfc/rfc6749>.
- [RFC6838]
- Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, , <https://www.rfc-editor.org/rfc/rfc6838>.
- [RFC7519]
- Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, , <https://www.rfc-editor.org/rfc/rfc7519>.
- [RFC7521]
- Campbell, B., Mortimore, C., Jones, M., and Y. Goland, "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, , <https://www.rfc-editor.org/rfc/rfc7521>.
- [RFC7523]
- Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, , <https://www.rfc-editor.org/rfc/rfc7523>.
- [RFC8174]
- Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
- [RFC8693]
- Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, DOI 10.17487/RFC8693, , <https://www.rfc-editor.org/rfc/rfc8693>.
- [RFC8725]
- Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Current Practices", BCP 225, RFC 8725, DOI 10.17487/RFC8725, , <https://www.rfc-editor.org/rfc/rfc8725>.
9.2. Informative References
- [RFC9470]
- Bertocci, V. and B. Campbell, "OAuth 2.0 Step Up Authentication Challenge Protocol", RFC 9470, DOI 10.17487/RFC9470, , <https://www.rfc-editor.org/rfc/rfc9470>.
Appendix A. Use Cases
A.1. Enterprise Deployment
Enterprises often have hundreds of SaaS applications. SaaS applications often have integrations to other SaaS applications that are critical to the application experience and jobs to be done. When a SaaS app needs to request an access token on behalf of a user to a 3rd party SaaS integration's API, the end-user typically needs to complete an interactive delegated OAuth 2.0 flow, as the SaaS application is not in the same security or policy domain as the 3rd party SaaS integration.¶
It is industry best practice for an enterprise to connect their ecosystem of SaaS applications to their Identity Provider (IdP) to centralize identity and access management capabilites for the organization. End-users get a better experience (SSO) and administrators get better security outcomes such multi-factor authentication and zero-trust. SaaS applications today enable the administrator to establish trust with an IdP for user authentication.¶
This specification can be used to extend the SSO relationship of multiple SaaS applications to include API access between these applications as well. This specification enables federation for Authorization Servers across policy or administrative boundaries. The same enterprise IdP that is trusted by applications for SSO can be extended to broker access to APIs. This enables the enterprise to centralize more access decisions across their SaaS ecosystem and provides better end-user experience for users that need to connect multiple applications via OAuth 2.0.¶
A.1.1. Preconditions
-
The Client has a registered OAuth 2.0 Client with the IdP Authorization Server¶
-
The Client has a registered OAuth 2.0 Client with the Resource Application¶
-
Enterprise has established a trust relationship between their IdP and the Client for SSO and Identity Assertion Authorization Grant¶
-
Enterprise has established a trust relationship between their IdP and the Resource Application for SSO and Identity Assertion Authorization Grant¶
-
Enterprise has granted the Client permission to act on behalf of users for the Resource Application with a set of scopes¶
A.2. Email and Calendaring Applications
Email clients can be used with arbitrary email servers, and cannot require pre-established relationships between each email client and each email server. When an email client uses OAuth to obtain an access token to an email server, this provides the security benefit of being able to use strong multi-factor authentication methods provided by the email server's authorization server, but does require that the user go through a web-based flow to log in to the email client. However, this web-based flow is often seen as distruptive to the user experience when initiated from a desktop or mobile native application, and so is often attempted to be minimized as much as possible.¶
When the email client needs access to a separate API, such as a third-party calendaring application, traditionally this would require that the email client go through another web-based OAuth redirect flow to obtain authorization and ultimately an access token.¶
To streamline the user experience, this specification can be used to enable the email client to use the identity assertion to obtain an access token for the third-party calendaring application without any user interaction.¶
A.2.1. Preconditions
-
The Client does not have a pre-registered OAuth 2.0 client at the IdP Authorization Server or the Resource Application¶
-
The Client has obtained an Identity Assertion (e.g. ID Token) from the IdP Authorization Server¶
-
The Resource Application is configured to allow the Identity Assertion Authorization Grant from unregistered clients¶
Acknowledgments
The authors would like to thank the following people for their contributions and reviews of this specification: Brian Campbell, Kamron Batmanghelich, Sofia Desenberg.¶