]> Okta

aaron@parecki.com

Okta

public@karlmcguinness.com

Security Web Authorization Protocol cross-domain authorization authz assertion enterprise 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 and JWT Profile for OAuth 2.0 Authorization Grants . About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The draft specification Identity Chaining Across Trust Domains 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 and JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants . 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.

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 when, and only when, they appear in all capitals, as shown here.

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 , this is the Client in trust domain A.

Resource Application

Application that provides an OAuth 2.0 Protected Resource. In , 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 , 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.

Overview The example flow is for an enterprise acme

Role	App URL	Tenant URL	Description
Client	https://wiki.example	https://acme.wiki.example	SaaS 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 | | | | 1 User SSO | | | | | | | | ID Token | | | | <- - - - - - - - | | | | | | | | | | | | | | | | 2 Token Exchange | | | | ----------------> | | | | | | | | ID-JAG | | | | <- - - - - - - - | | | | | | | | | | | | | | | | 3 Present ID-JAG | | | | ------------------+----------------> | | | | | | | Access Token | | | | <- - - - - - - - - - - - - - - - - - | | | | | | | | | | | | | | | 4 Resource Request with Access Token| | | -----------------------------------------------------> | | | | | | | | | | | | | ]]>

1. User logs in to the Client, the Client obtains the Identity Assertion (e.g. SAML Assertion or OpenID Connect ID Token)
2. Client uses the Identity Assertion to request an Identity Assertion Authorization Grant for the Resource Application from the IdP
3. Client exchanges the Identity Assertion Authorization Grant JWT for an Access Token at the Resource Application's token endpoint
4. Client makes an API request with the Access Token

User Authentication The Client initiates an authentication request with the IdP using OpenID Connect or SAML. The following is an example using OpenID Connect 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.

Token Exchange The Client makes a Token Exchange request to the IdP's Token Endpoint with the following parameters:

• requested_token_type=urn:ietf:params:oauth:token-type:id-jag
• resource - The token endpoint of the Resource Application.
• scope - The space-separated list of scopes at the Resource Application to include in the token
• subject_token - The identity assertion (SAML Assertion or OpenID Connect ID Token) for the target end-user
• subject_token_type - For SAML2 Assertion: urn:ietf:params:oauth:token-type:saml2, or OpenID Connect ID Token: urn:ietf:params:oauth:token-type:id_token
• Client authentication (e.g. client_id and client_secret, or the more secure private_key_jwt method using client_assertion and client_assertion_type)

The example below uses an ID Token as the Identity Assertion, and uses private_key_jwt as the client authentication method, (tokens truncated for brevity):

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.

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 :

• issued_token_type - urn:ietf:params:oauth:token-type:id-jag
• access_token - The Identity Assertion Authorization Grant JWT. (Token Exchange requires the access_token response parameter for historical reasons, even though this is not an OAuth access token.)
• token_type - N_A (As defined by Token Exchange.)
• scope - The list of scopes granted by the IdP. This may be fewer scopes than the application requested based on various policies in the IdP.
• expires_in - The lifetime in seconds of the authorization grant.

Error Response On an error condition, the IdP returns an OAuth 2.0 Token Error response as defined in Section 5.2 of , e.g:

Identity Assertion Authorization Grant JWT The Identity Assertion Authorization Grant JWT is issued and signed by the IdP, and describes the intended audience of the authorization grant as well as the client to which it was issued and the subject identifier of the original identity assertion, using the following claims:

• iss - The IdP issuer URL
• sub - The User ID at the IdP
• aud - Token endpoint of the Resource Application's authorization server
• client_id - Client ID as registered with the Resource Application's authorization server.
• scopes - Array of scopes at the Resource Application granted to the Client
• jti - Unique ID of this JWT
• exp, iat - as defined by JWT

The typ of the JWT indicated in the JWT header MUST be oauth-id-jag+jwt. An example JWT shown with expanded header and payload claims is below: Implementation notes:

• If the IdP is multi-tenant and uses the same issuer for all tenants, the Resource Application will already have IdP-specific logic to determine the tenant from OIDC/SAML (e.g. the hd claim in Google) and will need to use that if the IdP also has only one client registration for the Resource Application.
• sub should be an opaque ID, as iss+sub is unique. The IdP might want to also include the user's email here, which it should do as a new email claim. This would let the app dedupe existing users who may have an account with an email address but have not done SSO yet.

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 .

• grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
• assertion - The Identity Assertion Authorization Grant JWT obtained in the previous token exchange step
• Client Authentication - the Client authenticates with its credentials as registered with the Resource Application's authorization server

For example:

Processing Rules All of Section 5.2 of applies, in addition to the following processing rules:

• Validate the JWT typ is oauth-id-jag+jwt (per )
• The aud claim MUST identify the token endpoint of the Resource Application as the intended audience of the JWT.

Response The Resource Application token endpoint responds with an OAuth 2.0 Token Response, e.g.:

Security Considerations

Client Authentication This specification SHOULD only be supported for confidential clients. Public clients SHOULD redirect the user with an OAuth 2.0 Authorization Request.

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 . 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.

IANA Considerations

Media Types This section registers oauth-id-jag+jwt, a new media type in the "Media Types" registry in the manner described in . It can be used to indicate that the content is a Identity Assertion Authorization Grant JWT.

OAuth URI Registration This section registers urn:ietf:params:oauth:token-type:id-jag in the "OAuth URI" subregistry of the "OAuth Parameters" registry .

• URN: urn:ietf:params:oauth:token-type:id-jag
• Common Name: Token type URI for a Identity Assertion JWT Authorization Grant
• Change Controller: IESG
• Specification Document: This document

References Normative References The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. This specification replaces and obsoletes the OAuth 1.0 protocol described in RFC 5849. [STANDARDS-TRACK] This specification provides a framework for the use of assertions with OAuth 2.0 in the form of a new client authentication mechanism and a new authorization grant type. Mechanisms are specified for transporting assertions during interactions with a token endpoint; general processing rules are also specified. The intent of this specification is to provide a common framework for OAuth 2.0 to interwork with other identity systems using assertions and to provide alternative client authentication mechanisms. Note that this specification only defines abstract message flows and processing rules. In order to be implementable, companion specifications are necessary to provide the corresponding concrete instantiations. This specification defines the use of a JSON Web Token (JWT) Bearer Token as a means for requesting an OAuth 2.0 access token as well as for client authentication. This specification defines a protocol for an HTTP- and JSON-based Security Token Service (STS) by defining how to request and obtain security tokens from OAuth 2.0 authorization servers, including security tokens employing impersonation and delegation. JSON Web Tokens, also known as JWTs, are URL-safe JSON-based security tokens that contain a set of claims that can be signed and/or encrypted. JWTs are being widely used and deployed as a simple security token format in numerous protocols and applications, both in the area of digital identity and in other application areas. This Best Current Practices document updates RFC 7519 to provide actionable guidance leading to secure implementation and deployment of JWTs. Microsoft Microsoft MITRE NSA-CCSS Ping Identity This specification defines a mechanism to preserve identity information and federate authorization across trust domains that use the OAuth 2.0 Framework. Discussion Venues This note is to be removed before publishing as an RFC. Discussion of this document takes place on the Web Authorization Protocol Working Group mailing list (oauth@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/oauth/. Source for this draft and an issue tracker can be found at https://github.com/oauth-wg/oauth-identity-chaining. IANA This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. This second document defines the general structure of the MIME media typing system and defines an initial set of media types. [STANDARDS-TRACK] In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References It is not uncommon for resource servers to require different authentication strengths or recentness according to the characteristics of a request. This document introduces a mechanism that resource servers can use to signal to a client that the authentication event associated with the access token of the current request does not meet its authentication requirements and, further, how to meet them. This document also codifies a mechanism for a client to request that an authorization server achieve a specific authentication strength or recentness when processing an authorization request. This specification defines the use of a Security Assertion Markup Language (SAML) 2.0 Bearer Assertion as a means for requesting an OAuth 2.0 access token as well as for client authentication.

Use Cases

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.

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

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.

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

Relationship to RFC7522 "SAML 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants" describes a mechanism for using a SAML assertion as an authorization grant to obtain an access token. Directly exchanging a SAML assertion for an access token is limited in the ways this can be securely deployed. This specification adds an intermediate step of exchanging a SAML assertion for the intermediate Identity Assertion Authorization Grant, which is then later exchanged for an access token. By adding this intermediate step, this provides the security benefit of being able to indicate which API the access token is being requested, enabling the authorization server to enforce policies before issuing the authorization grant. Without this step, policies must be enforced at each resource application's authorization server, which doesn't scale well and is impossible in some deployments.

Acknowledgments The authors would like to thank the following people for their contributions and reviews of this specification: Brian Campbell.