Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarifications on using sender-constraint tokens DPoP #225

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
30 changes: 30 additions & 0 deletions documentation/CAMARA-Security-Interoperability.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@
* [Conventions](#conventions)
* [General Considerations](#general-considerations)
+ [Transport Security](#transport-security)
+ [Sender-Constrained Tokens](sender-constrained-tokens)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
+ [Sender-Constrained Tokens](sender-constrained-tokens)
+ [Sender-Constrained Tokens](#sender-constrained-tokens)

* [OIDC Authorization Code Flow](#oidc-authorization-code-flow)
+ [Cross-Site Request Forgery Protection](#cross-site-request-forgery-protection)
* [Client-Initiated Backchannel Authentication Flow](#client-initiated-backchannel-authentication-flow)
Expand Down Expand Up @@ -62,6 +63,35 @@ Unless otherwise noted, all the protocol parameter names and values are case sen
### Transport Security
All network connections MUST use TLS 1.2 or better.

### Sender-Constrained Tokens

[OAuth 2.0 Security Best Current Practice](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics#section-2.2.1) and the [FAPI 2.0 Baseline Profile](https://openid.net/specs/fapi-2_0-baseline-01.html) both RECOMMEND that authorization and resource servers use mechanisms for sender-constraining access tokens.

This document states that Demonstrating Proof of Possession (DPoP) [RFC9449](https://datatracker.ietf.org/doc/html/rfc9449) MAY be used by API Consumers, to prevent misuse of stolen and leaked access tokens.

CAMARA authorization servers MUST NOT respond with an error if they do not support DPoP. DPoP allows authorization servers to issue tokens that are not sender-constrained even if a valid DPoP header is present in the authorization request. It is up to the API consumer to decide whether none-sender-constrained tokens meet their security requirements.

If the API Provider supports DPoP, support for it MAY be expressed by the server metadata field `dpop_signing_alg_values_supported` or alternate API documentation.

API consumers with high security demands that e.g. want to achieve EIDAS LOA high can be set to be required to always send DPoP requests. This requirement is expressed by the API consumer's metadata in the field `dpop_bound_access_tokens`. This requirement on the API consumer is determined at onboarding time.

The following table illustrated the expected behaviour of the API Provider at the API endpoint.

| API Consumer | API Provider |Proof Presented? | Provider Behavior |
| -------------- | -------------- |----------| -------------------------------------------------------------------------------------|
| Supports DPoP | Supports DPoP | Yes | MUST process the proof |
| Supports DPoP | Supports DPoP | No | MUST validate the bearer token |
| Supports DPoP | Requires DPoP | Yes | MUST process the proof |
| Supports DPoP | Requires DPoP | No | MUST return an appropriate HTTP error with details in the custom message text |
| Supports DPoP | No DPoP Support | Yes | MUST drop the HTTP parameter |
| Supports DPoP | No DPoP Support | No | MUST validate the bearer token |
| Requires DPoP | Supports DPoP | Yes | MUST process the Proof |
| Requires DPoP | Requires DPoP | Yes | MUST process the Proof |
| Requires DPoP | No DPoP Support | Yes | MUST drop the unrecognized HTTP header |
| No DPoP Support| Supports DPoP | No | MUST validate the bearer token |
| No DPoP Support| Requires DPoP | No | MUST return an appropriate HTTP error with details in the custom message text |
| No DPoP Support| No DPoP Support | No | MUST validate the bearer token |
Comment on lines +78 to +93
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The API Consumer either presents the DPoP proof to the API Provider, or they do not. Whether they "require" the API Provider to support DPoP or not does not affect API Provider behaviour. So the table can be greatly simplified.

Suggested change
The following table illustrated the expected behaviour of the API Provider at the API endpoint.
| API Consumer | API Provider |Proof Presented? | Provider Behavior |
| -------------- | -------------- |----------| -------------------------------------------------------------------------------------|
| Supports DPoP | Supports DPoP | Yes | MUST process the proof |
| Supports DPoP | Supports DPoP | No | MUST validate the bearer token |
| Supports DPoP | Requires DPoP | Yes | MUST process the proof |
| Supports DPoP | Requires DPoP | No | MUST return an appropriate HTTP error with details in the custom message text |
| Supports DPoP | No DPoP Support | Yes | MUST drop the HTTP parameter |
| Supports DPoP | No DPoP Support | No | MUST validate the bearer token |
| Requires DPoP | Supports DPoP | Yes | MUST process the Proof |
| Requires DPoP | Requires DPoP | Yes | MUST process the Proof |
| Requires DPoP | No DPoP Support | Yes | MUST drop the unrecognized HTTP header |
| No DPoP Support| Supports DPoP | No | MUST validate the bearer token |
| No DPoP Support| Requires DPoP | No | MUST return an appropriate HTTP error with details in the custom message text |
| No DPoP Support| No DPoP Support | No | MUST validate the bearer token |
The following table defines the REQUIRED behaviour of the API Provider for the `/token` endpoint, dependent on whether a DPoP proof is provided, and the API Provider's own level of DPoP support.
| DPoP Proof Provided | API Provider DPoP Support | Token Type Issued |
|:-----------------------:|:-------------------------------:|:-------------------:|
| Yes | No DPoP Support | Bearer token |
| Yes | Supports DPoP | DPoP token |
| Yes | Requires DPoP | DPoP token |
| No | No DPoP Support | Bearer token |
| No | Supports DPoP | Bearer token |
| No | Requires DPoP | HTTP 400 `invalid_dpop_proof`<br>(see RFC [9449](https://www.rfc-editor.org/rfc/rfc9449.html#name-oauth-extensions-error-regi)) |


## OIDC Authorization Code Flow

The OIDC Authorization Code Flow is defined in [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html)
Expand Down