# "Identity Chaining"

## Introduction

Since the introduction of the [OAuth 2.0 Authorization Framework (RFC6749)](https://datatracker.ietf.org/doc/html/rfc6749) in 2012 it has found brought adoption in the industry and is still popular today.

Whilst clients, resource servers, resources and the authorization server are all part of one domain, developers are often faced with the situation that a protected resource is located in a domain and thus protected by a different authorization server. A request can even take multiple hops across various domains until it finds its destination at a resource.

All protected resources along the way are challenged to correctly authorizing the end user and require its claims from the previous trust domains to achieve that.

This problem is further described as **Identity Chaining**

Figure 1: Identity Chaining.

Figure 1 draws a simple scenario of Identity Chaining. The **User** accesses a protected resource located at **Resource Server A**. The access is determined via **Authorization Server A**. Resource Server A itself needs to access protected resource located at **Resource Server B** in "Domain B" which is protected by **Authorization Server B**.

## Use cases

A few use cases are described below to help clarify the various scenarios the authors see and this specification targets to solve.

### Preserve identity across trust boundaries

To be added.

### Scenario for resilience flow

To be added.

### Scenario for governance flow

To be added.

## Identity Chaining Flow

To achieve Identity Chaining the authors of this specification propose a combination of [Token Exchange (RFC8393)]() and a profile of the [Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants](). The authors are convinced that leveraging existing specifications reduces complexity and drives quick adoption.

The abstract flow outlined below describes how these specification are used and work together. 2 profiles are later described in this specification targeting different requirements:
- Resilience oriented profile
- Governance oriented profile

Further profiles may be developed but adhering the abstract Identity Chaining flow is highly reccomended.

### Roles

**Client**
The entity that performs Identity Chaining is in this specification referred as the Client. Based on the 2 profiles below the client may either be a Resource Server or an Authorization Aerver.

**Authorization Server A and Resource Server A**
Authorization Server and Resource Server of Domain A.
Resource Server A requires access to a protected resource located at Domain B.

**Authorization Server B and Resource Server B**
Authorization Server and Resource Server of Domain B. Resource Server B hosts the protected resource Domain A requires.

### Abstract Flow

The flow in figure 2 describes the steps necessary to receive an access token for the protected resource a at Resource Server B in Domain B. The steps are described in detail below.

*Figure 2: Abstract Identity Chaining flow*

### **(A) Discovering Authorization Server B**

The first step is the discovery of the Authorization Server B. This specification does not cover the details of such. The client MAY contact the resource and leverage the WWW-Authentication response (see [RFC 6750 Section 3](https://datatracker.ietf.org/doc/html/rfc6750#section-3)), maintain a static mapping or use other means to identify Authorization Server B.

### **(B+C) Token Exchange**

Once the Authorization Server B is identified the client performs an [RFC 8693 Token Exchange](https://datatracker.ietf.org/doc/html/rfc8693) to its own Authorization Server A. This steps is used to receive a Authorization Grant as specified in [RFC 6749 Section 1.3](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3) and [RFC 7523 Section 2.1](https://datatracker.ietf.org/doc/html/rfc7523#section-2.1) dedicated for Authorization Server B.

The token exchange allows the following:

- Authorization Server A has control over trust boundary federations. It MAY deny the request if federation to trust boundary B is not allowed.

- Authorization Server A can control what claims are disclosed to Authorization Server B. It may remove claims not designated to be seen outside of trust boundary. It also may hide claims (e.g. by producing a [SD-JWT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-selective-disclosure-jwt-04)) for privacy or other reasons.

- Authorization Server A MAY add additional claims. This can be necessary for Authorization Server B to correctly identify the subject. It may know the identity under a different identifier and Authorization Server A maintains that mapping.

- Authorization Server B may require a specific authorization grant format. This specification does not specify or restrict certain formats and choosen format is subject to support and security requirements of both Authorization Servers. It is reccomended for both Authorization Servers to negociate a contract of authorization grant format and containing claims. Authorization Grants are subject to the implementation and MAY be JWT tokens [see RFC 7523 Section 3](https://datatracker.ietf.org/doc/html/rfc7523#section-3), encrypted JWE tokens [see RFC 7516](https://datatracker.ietf.org/doc/html/rfc7516) or something entire differently.

The parameters described in [Token Exchange]() apply here with the following restrictions:

|||
|---------------|-------|
| subject_token | REQUIRED Access token of the subject that will be used to call protected resource X in trust boundary B |
| requested_token_type | OPTIONAL according to [RFC8693 Section 2.1](https://datatracker.ietf.org/doc/html/rfc8693#name-request). This specification, however, reccomends that clients SHOULD NOT specify this to allow the Authorization Server to returns an Authorization Grant based on the targeted Authorization Server and not tightly couple clients to the format. |
| resource | OPTIONAL. URI of Authorization Server B. REQUIRED if audience is not set. |
| audience | OPTIONAL. Well known/logical name of Authorization Server B. REQUIRED if resource is not set. |
| scope | OPTIONAL additional scopes to indicate scopes included in returned authorization grant |

#### Requirement of resource or audience

Either one of resource or audience is required to indicate the Authorization Server what other Authorization Server is targeted. The request MUST deny the request if neither is set. A Authorization SHOULD deny the request on an unknown resource/audience. In cases where federation to any authorization server is deliberate this MAY be allowed.

#### Using scope to control claim exposure

Client and Authorization Servers MAY use the scope parameter to control transcribed claims and thus the claims exposed to trust boundary B.

Authorization Servers SHOULD verify that requested scopes are not higher priveleged than the scopes of presented subject_token.

#### Response

The token exchange response aligns with [Token Exchange section 2.2](https://datatracker.ietf.org/doc/html/rfc8693#name-response).

The returned authorization grant format is subject to the requested audience/resource (authorization server) and clients SHOULD NOT rely on the format and consider the authorization grant as a whole. This allows flexibility on the contract of claims and format between Authorization Server A and B.

Returned Authorization Grant MUST be audienced to Authorization Servers. This corresponds with [RFC 7523 Section 3, Point 3](https://datatracker.ietf.org/doc/html/rfc7523#section-3) and is there to reduce missuse and to prevent clients from presenting their (for other use cases intented) access tokens as asseration.

Response authorization grant MAY be audienced to multiple Authorization Servers if federation happens to multiple trust boundaries. The authors of this specification reccomended that only one audience is used to prevent Authorization Server B to abuse and present the token to Authorization Server C.

#### Example

grant_type=urn:ietf:params:oauth:grant-type:token-exchange
subject_token=<access token of the end-user (in a 3 legged flow) or the requesting resource server (in a 2 legged flow)>
subject_token_type=urn:ietf:params:oauth:token-type:access_token
actor_token=<access token of the requesting resource server>
actor_token_type=urn:ietf:params:oauth:token-type:access_token
resource=<URL of Authorization Server B>

### (D+E) Authorization Grant Flow

The client uses the received Authorization Grant from steps B and C as an asseration towards Authorization Server B.

#### Request

Everything in [RFC 7521](https://www.rfc-editor.org/rfc/rfc7521) ([Section 4.1](https://www.rfc-editor.org/rfc/rfc7521#section-4.1) in specific) and [RFC 7523](https://www.rfc-editor.org/rfc/rfc7523) applies. For the purpose of this specification the following descriptions apply:

|||
|----|-----|
| grant_type | REQUIRED. In case of an JWT Bearer Grant this would be `urn:ietf:params:oauth:grant-type:jwt-bearer`. A different URN may be used in case of a different format. |
| asseration | REQUIRED. Authorization Grant received from Authorization Server A |
| scope | OPTIONAL. No changes. |

TODO: How do we incidate the resource?

#### Processing rules

All of [Section 5.2 in RFC 7521](https://www.rfc-editor.org/rfc/rfc7521#section-5.2) applies. For the purpose of this specification the following concrete descriptions apply:

|||
|--|--|
| Issuer | The issuer MUST be the Authorization Server A that issued the authorization grant. |
| Audience | MUST be Authorization Server B |

#### Response

Authorization Server B returns an access token for Resource Server B.

#### Example

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
assertion=<resulting authorization grant from token exchange>

## Profiles

### Resilience Profile

**In this profile Resource Server A acts as the client of the Identity Chaining flow**

This profiles MAY be used when:
- Authorization Server B is reachable by Resource Server A by network and possesses the appropiate client authentication (if required by Authorization Server B).
- Resource Server A has the ability to determine the Authorization Server of Resource B (Authorization Server B). In some cases additional context only the requestor possesses is required to determine the correct Authorization Server. For example when the resource URI accepts access token of multiple issuers.

Steps:

(A) The client accesses a resource within its domain (Resource Server A). The resource recognises that it requires to access a resource in a different domain (Resource Server B).

(abstract_A) Resource Server A determines the Authorization Server of P B (Authorization Server B).

(abstract_B) Resource Server A performs a token exchange to Authorization Server A. See abstract for details.

(abstract_C) Authorization Server A allows the access to resource in the different domain (Resource B) and returns an issued token audienced to Authorization Server B.

(abstract_D) Resource Server A uses this token to perform a bearer flow at Authorization Server B. See abstract for details.

(abstract_E) Authorization Server B performs its checks, transribes claims and returns an access token for Resource Server B.

(B) Resource Server A uses this access token to access Resource Server B.

### Governance Profile

**In this profile Authorization Server A acts as the client of the Identity Chaining flow**

This profile focuses on governance and MAY be picked if either of the following is true:
- Resource Server must not have knowledge of Authorization Server B.
- Resource Server does not have network access to Authorization Server B
- Authorization Server A requires strict control on resources (or resources outside of domain) accessed.
- Authorization Server B requires client authentication and managing clients for Resource Servers of Trust Domain A is not wanted.

Steps:

(A) The client accesses a resource within its domain (Resource A). The resource recognises that it requires to access a resource outside of its domain (Resource B).

(B) Resource A performs a token exchange (TBD, maybe separate profile) to its authorization server (Authorization Server A) to request an access token for Resource B.

(abstract_A) Authorization Server A (in abstract "Client") recognises the resource and determines the correct authorization server (Authorization Server B).

(abstract_B+C) Authorization Server A performs an internal token exchange to mint an authorization grant audienced to Authorization Server B.

(abstract_D) Authorization Server A uses the authorization grant as an asseration towards Suthorization Server B.

(abstract_E) Authorization Server B performs its checks and returns an access token for Resource Server B.

(D) Authorization Server A returns received token to Resource Server A.

(E) Resource Server A uses the access token to access Resource Server B.