From 3055386f9f2e167cdf391ecaa0758e2ca660fe37 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Tue, 12 Sep 2023 09:51:59 +0200 Subject: [PATCH 01/28] add RFC021 vp_token-brearer grant type for oauth2 --- rfc/rfc021-vp_token-grant-type.md | 162 ++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 rfc/rfc021-vp_token-grant-type.md diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md new file mode 100644 index 0000000..f7b5a6b --- /dev/null +++ b/rfc/rfc021-vp_token-grant-type.md @@ -0,0 +1,162 @@ +# RFC021 VP Token Grant Type + +| | | +|:--------------------------|:-----------------| +| Nuts foundation | W.M. Slakhorst | +| Request for Comments: 021 | Nedap | +| | September 2023 | + +## VP Token Grant Type + +### Abstract + +This specification defines the use of a Verifiable Presentation Bearer +Token as a means for requesting an OAuth 2.0 access token. + +### Status of document + +This document is currently in draft. + +### Copyright Notice + +![](../.gitbook/assets/license.png) + +This document is released under the [Attribution-ShareAlike 4.0 International \(CC BY-SA 4.0\) license](https://creativecommons.org/licenses/by-sa/4.0/). + +## 1. Introduction + +A Verifiable Presentation [VP] is an encoding that enables identity and security information base on Verifiable Credentials to be shared across security domains. +A security token is generally issued by an Identity Provider and consumed by a Relying Party that relies on its content to identify the token's subject for security-related purposes. +In the case of Verifiable Credentials, the identity provider role is fulfilled by the holder using a wallet. The relying party role equals the verifier role as defined by the Verifiable Credentials specification. + +The OAuth 2.0 Authorization Framework [RFC6749] provides a method for making authenticated HTTP requests to a resource using an access token. +Access tokens are issued to third-party clients by an authorization server (AS) with the (sometimes implicit) approval of the resource owner. +In OAuth, an authorization grant is an abstract term used to describe intermediate credentials that represent the resource owner authorization. +An authorization grant is used by the client to obtain an access token. Several authorization grant types are defined to support a wide range of client types and user experiences. +OAuth also allows for the definition of new extension grant types to support additional clients or to provide a bridge between OAuth and other trust frameworks. +Finally, OAuth allows the definition of additional authentication mechanisms to be used by clients when interacting with the authorization server. + +"Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants" [RFC7521] is an abstract extension to OAuth 2.0 that provides a general framework for the use of assertions (a.k.a. security tokens) as client credentials and/or authorization grants with OAuth 2.0. +This specification profiles the OAuth Assertion Framework [RFC7521] to define an extension grant type that uses a Verifiable Presentation Bearer Token to request an OAuth 2.0 access token. + +## 2. Terminology + +All terms are as defined in the following specifications: "The OAuth 2.0 Authorization Framework" [RFC6749], the OAuth Assertion Framework [RFC7521] "JSON Web Token (JWT)" [JWT], Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL], Verifiable Credentials Presentation Exchange [PE], JSON Web Signature 2020 [JSONWebSignature2020], Decentralized Identifiers 1.0 [DID]. + +## 3. HTTP Parameter Bindings for Transporting Assertions + +The OAuth Assertion Framework [RFC7521] defines generic HTTP parameters for transporting assertions (a.k.a. security tokens) during interactions with a token endpoint. +This section defines specific parameters and treatments of those parameters for use with VP Bearer Tokens as Authorization Grants. + +To use a VP as an authorization grant, the client uses an access token request as defined in Section 4 of the OAuth Assertion Framework [RFC7521] with the following specific parameter values and encodings. + +The value of the "grant_type" is "urn:ietf:params:oauth:grant-type:vp_token-bearer". + +The value of the "assertion" parameter MUST contain a Verifiable Presentation. The Verifiable Presentation MUST be encoded as either: + +* The Verifiable Presentation is encoded as JSON using the application/x-www-form-urlencoded content type. +* The Verifiable Presentation is encoded as JWT according to section §6.3.1 of the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. + +The "scope" parameter MUST be used, as defined in the OAuth Assertion Framework [RFC7521], to indicate the requested scope. +The scope parameter determines the set of credentials the authorization server expects. + +The "presentation_submission" parameter MUST be used, as defined in Presentation Exchange [PE], to indicate how the VP matches the requested Verifiable Credentials. +The Presentation Submission MUST be encoded using the application/x-www-form-urlencoded content type. + +The following example demonstrates an access token request with a VP as an authorization grant (with extra line breaks for display purposes only): + + POST /token.oauth2 HTTP/1.1 + Host: as.example.com + Content-Type: application/x-www-form-urlencoded + + grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Avp_token-bearer + &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0. + eyJpc3Mi[...omitted for brevity...]. + J9l-ZhwP[...omitted for brevity...] + &presentation_submission= {..} + +## 3.1 Assertion Encoding + +As stated in the previous section, the assertion parameter can either be encoded in JSON or JWT. +The authorization server determines the encoding by adding the correct parameters to the authorization server metadata [RFC8414]]. +The following parameter MUST be added: + +* `vp_formats`: An object defining the formats and proof types of Verifiable Presentations and Verifiable Credentials that a Verifier supports as stated by §9 of the OpenID for Verifiable Presentations specification [OIDC4VP]. + (ldp_vp or jwt_vp_json) + +When processing the assertion the authorization server can detect the used format by checking the initial character. +A JSON encoded assertion starts with a '{' character or '%7B' when urlencoded. + +## 4. Processing requirements + +In order to issue an access token response as described in OAuth 2.0 [RFC6749], the authorization server MUST validate the VP. +The validation requirements are split into three paragraphs. The first paragraph describes the requirements that apply to all VP's. +The second paragraph describes the requirements that apply to JWT encoded VP's. The third paragraph describes the requirements that apply to JSON encoded VP's. + +### 4.1 General requirements + +1. The authorization server MUST validate the Presentation Submission according to section 6 of the Presentation Exchange [PE] specification. +2. The authorization server MUST validate the VP according to section 6.1 of the Presentation Exchange [PE] specification. +3. The Presentation Submission MUST be an answer to the Presentation Definition that corresponds with the requested scope. + How an authorization server determines the Presentation Definition based on scope is out of scope of this specification. + However, a request to the Presentation Definition endpoint MUST result to the same Presentation Definition as the Presentation Definition that is used to validate the VP. +4. The Verifiable Presentation MUST be not be valid for more than 15 minutes. +5. A clock skew of no more than 5 seconds MAY be applied when validating the Verifiable Presentation. + +### 4.2 JWT requirements + +1. The assertion MUST be a valid JWT according to §6.3.1 of the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. +2. The `vp` field of the JWT MUST be valid according to §4.10 the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. +3. The `nonce` of the JWT MUST be a string that is unique for each request. +4. The `kid` field MUST be a DID URL. +5. The `iss` field MUST be a Decentralized Identifier [DID] and MUST correspond to the `kid`. +6. The `sub` field MUST match the `credentialSubject.ID` field from all the Verifiable Credentials that are used to request the access token. +7. The `aud` field MUST be a DID under control of the Authorization Server. + +### 4.3 JSON requirements + +1. The assertion MUST be a valid JSON object according to §4.10 the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. +2. The proof of the VP MUST be a valid [JSONWebSignature2020] object. +3. The `challenge` field of the JSON object MUST be a string that is unique for each request. +4. The `domain` field of the JSON object MUST be a DID under control of the Authorization Server. +5. The `issuer` field of the JSON object MUST be a Decentralized Identifier [DID]. +6. The `verificationMethod` field of the Proof MUST be a DID URL and correspond to the `issuer` field. +7. The `holder` field if present MUST match the `credentialSubject.ID` field from all the Verifiable Credentials that are used to request the access token. +8. If the `holder` field is not present then the `issuer` field MUST match the `credentialSubject.ID` field from all the Verifiable Credentials that are used to request the access token. + +## 5. Presentation Definition endpoint + +In order for a client to know which Presentation Definition [PE] to use, the authorization server MUST provide a Presentation Definition endpoint. +The Presentation Definition endpoint MUST be registered as a `presentation_definition_endpoint` in the authorization server metadata [RFC8414]. +The Presentation Definition endpoint MUST return a Presentation Definition that corresponds with the requested scope. + +## 6. Access Token Introspection + +The authorization server MUST support the access token introspection endpoint as defined in OAuth 2.0 [RFC7662]. +The introspection endpoint MUST return the following fields: + +* `iss`: The issuer of the access token. +* `sub`: The subject of the access token. +* `exp`: The expiration time of the access token. +* `iat`: The time the access token was issued. +* `scope`: The granted scope. +* `vcs`: The Verifiable Credentials that were used to request the access token. + +## 7. Security Considerations + +The nonce/challenge (nonce) is used to prevent replay attacks. The nonce is a random string that is generated by the client. +The nonce is included in the signed data. The authorization server MUST reject any request that uses a nonce that has been used before. +The authorization server MAY reduce storage requirements by only storing the nonce for the lifetime of the Verifiable Presentation. + +## 8. References + +* [RFC6749] D. Hardt, "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012, . +* [RFC7521] D. Campbell, Ed., B. Zaninovich, Ed., "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, May 2015, . +* [JWT] M. Jones, J. Bradley, N. Sakimura, "JSON Web Token (JWT)", RFC 7519, May 2015, . +* [VC-DATA-MODEL] M. Sporny, D. Longley, D. Chadwick, "Verifiable Credentials Data Model 1.1", W3C Recommendation, 3 March 2022, . +* [PE] D. Buchner, B. Zundel, M. Riedel, K.H. Duffy, "Presentation Exchange 2.X.X", 12 September 2023, . +* [JSONWebSignature2020] O. Steel, M. Prorock, C.E. Lehner, "JSON Web Signature 2020", W3C Community Group Report, 21 July 2022, . +* [OIDC4VP] O. Terbu, T. Lodderstedt, K. Yasuda, T. Looker, "OpenID for Verifiable Presentations Draft 18", OpenID connect working group, 21 April 2023, . +* [RFC8414] M. Jones, N. Sakimura, J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, June 2018, . +* [RFC7662] J. Richer, "OAuth 2.0 Token Introspection", RFC 7662, October 2015, . +* [DID] M. Sporny, D. Longley, M. Sabadello, D. Reed, O. Steele, C. Allen, "Decentralized Identifiers (DIDs) v1.0", W3C Recommendation, 19 July 2022, . \ No newline at end of file From ac52094d8339ac0bfc203e3a62d952f839ee1dce Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Tue, 12 Sep 2023 12:17:01 +0200 Subject: [PATCH 02/28] update vp_formats format --- rfc/rfc021-vp_token-grant-type.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index f7b5a6b..03fac18 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -82,7 +82,7 @@ The authorization server determines the encoding by adding the correct parameter The following parameter MUST be added: * `vp_formats`: An object defining the formats and proof types of Verifiable Presentations and Verifiable Credentials that a Verifier supports as stated by §9 of the OpenID for Verifiable Presentations specification [OIDC4VP]. - (ldp_vp or jwt_vp_json) + (ldp_vp or jwt_vp) When processing the assertion the authorization server can detect the used format by checking the initial character. A JSON encoded assertion starts with a '{' character or '%7B' when urlencoded. From ae717743f5764763d1df8247ce998daa9b18d6e9 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Thu, 14 Sep 2023 09:57:26 +0200 Subject: [PATCH 03/28] fixed technical comments from PR --- rfc/rfc021-vp_token-grant-type.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 03fac18..ef5172f 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -50,7 +50,7 @@ This section defines specific parameters and treatments of those parameters for To use a VP as an authorization grant, the client uses an access token request as defined in Section 4 of the OAuth Assertion Framework [RFC7521] with the following specific parameter values and encodings. -The value of the "grant_type" is "urn:ietf:params:oauth:grant-type:vp_token-bearer". +The value of the "grant_type" is "vp_token-bearer". The value of the "assertion" parameter MUST contain a Verifiable Presentation. The Verifiable Presentation MUST be encoded as either: @@ -82,7 +82,6 @@ The authorization server determines the encoding by adding the correct parameter The following parameter MUST be added: * `vp_formats`: An object defining the formats and proof types of Verifiable Presentations and Verifiable Credentials that a Verifier supports as stated by §9 of the OpenID for Verifiable Presentations specification [OIDC4VP]. - (ldp_vp or jwt_vp) When processing the assertion the authorization server can detect the used format by checking the initial character. A JSON encoded assertion starts with a '{' character or '%7B' when urlencoded. @@ -108,9 +107,9 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 1. The assertion MUST be a valid JWT according to §6.3.1 of the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. 2. The `vp` field of the JWT MUST be valid according to §4.10 the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. 3. The `nonce` of the JWT MUST be a string that is unique for each request. -4. The `kid` field MUST be a DID URL. -5. The `iss` field MUST be a Decentralized Identifier [DID] and MUST correspond to the `kid`. -6. The `sub` field MUST match the `credentialSubject.ID` field from all the Verifiable Credentials that are used to request the access token. +4. The `iss` field MUST be a Decentralized Identifier [DID]. +5. The `kid` field MUST be a DID URL and MUST resolve to a verificationMethod in the DID Document. The DID part of the DID URL MUST match the `iss` field. +6. The `sub` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. 7. The `aud` field MUST be a DID under control of the Authorization Server. ### 4.3 JSON requirements @@ -119,10 +118,9 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 2. The proof of the VP MUST be a valid [JSONWebSignature2020] object. 3. The `challenge` field of the JSON object MUST be a string that is unique for each request. 4. The `domain` field of the JSON object MUST be a DID under control of the Authorization Server. -5. The `issuer` field of the JSON object MUST be a Decentralized Identifier [DID]. -6. The `verificationMethod` field of the Proof MUST be a DID URL and correspond to the `issuer` field. -7. The `holder` field if present MUST match the `credentialSubject.ID` field from all the Verifiable Credentials that are used to request the access token. -8. If the `holder` field is not present then the `issuer` field MUST match the `credentialSubject.ID` field from all the Verifiable Credentials that are used to request the access token. +5. The `verificationMethod` field of the Proof MUST be a DID URL. +6. The `holder` field if present MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. +7. The `verificationMethod` field of the proof MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. ## 5. Presentation Definition endpoint From ac552e2c80b79a5798659c3359f4cfe76c3ace6b Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Fri, 15 Sep 2023 09:59:35 +0200 Subject: [PATCH 04/28] some fixes --- rfc/rfc021-vp_token-grant-type.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index ef5172f..cd84ff4 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -25,19 +25,20 @@ This document is released under the [Attribution-ShareAlike 4.0 International \( ## 1. Introduction -A Verifiable Presentation [VP] is an encoding that enables identity and security information base on Verifiable Credentials to be shared across security domains. -A security token is generally issued by an Identity Provider and consumed by a Relying Party that relies on its content to identify the token's subject for security-related purposes. -In the case of Verifiable Credentials, the identity provider role is fulfilled by the holder using a wallet. The relying party role equals the verifier role as defined by the Verifiable Credentials specification. +A Verifiable Presentation [VP] is an encoding that enables identity and security information base on Verifiable Credentials to be shared across security domains. +A security token is generally issued by an Identity Provider and consumed by a Relying Party that relies on its content to identify the token's subject for security-related purposes. +In the case of Verifiable Credentials, the assertion is self-issued by the holder using a wallet. +The relying party role equals the verifier role as defined by the Verifiable Credentials specification. The OAuth 2.0 Authorization Framework [RFC6749] provides a method for making authenticated HTTP requests to a resource using an access token. Access tokens are issued to third-party clients by an authorization server (AS) with the (sometimes implicit) approval of the resource owner. In OAuth, an authorization grant is an abstract term used to describe intermediate credentials that represent the resource owner authorization. -An authorization grant is used by the client to obtain an access token. Several authorization grant types are defined to support a wide range of client types and user experiences. +An authorization grant is used by the client to obtain an access token. Several authorization grant types are defined to support a wide range of client types and user experiences. OAuth also allows for the definition of new extension grant types to support additional clients or to provide a bridge between OAuth and other trust frameworks. Finally, OAuth allows the definition of additional authentication mechanisms to be used by clients when interacting with the authorization server. "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants" [RFC7521] is an abstract extension to OAuth 2.0 that provides a general framework for the use of assertions (a.k.a. security tokens) as client credentials and/or authorization grants with OAuth 2.0. -This specification profiles the OAuth Assertion Framework [RFC7521] to define an extension grant type that uses a Verifiable Presentation Bearer Token to request an OAuth 2.0 access token. +This specification profiles [RFC7521] to define an extension grant type that uses a self-issued Verifiable Presentation Bearer Token to request an OAuth 2.0 access token. ## 2. Terminology @@ -69,7 +70,7 @@ The following example demonstrates an access token request with a VP as an autho Host: as.example.com Content-Type: application/x-www-form-urlencoded - grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Avp_token-bearer + grant_type=vp_token-bearer &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0. eyJpc3Mi[...omitted for brevity...]. J9l-ZhwP[...omitted for brevity...] From 41918d83ddd7acd957a12a612bd29b24022627f7 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Fri, 15 Sep 2023 10:04:08 +0200 Subject: [PATCH 05/28] fix PE version --- rfc/rfc021-vp_token-grant-type.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index cd84ff4..2fb20ea 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -153,7 +153,7 @@ The authorization server MAY reduce storage requirements by only storing the non * [RFC7521] D. Campbell, Ed., B. Zaninovich, Ed., "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, May 2015, . * [JWT] M. Jones, J. Bradley, N. Sakimura, "JSON Web Token (JWT)", RFC 7519, May 2015, . * [VC-DATA-MODEL] M. Sporny, D. Longley, D. Chadwick, "Verifiable Credentials Data Model 1.1", W3C Recommendation, 3 March 2022, . -* [PE] D. Buchner, B. Zundel, M. Riedel, K.H. Duffy, "Presentation Exchange 2.X.X", 12 September 2023, . +* [PE] D. Buchner, B. Zundel, M. Riedel, K.H. Duffy, "Presentation Exchange 2.0.0", 12 September 2023, . * [JSONWebSignature2020] O. Steel, M. Prorock, C.E. Lehner, "JSON Web Signature 2020", W3C Community Group Report, 21 July 2022, . * [OIDC4VP] O. Terbu, T. Lodderstedt, K. Yasuda, T. Looker, "OpenID for Verifiable Presentations Draft 18", OpenID connect working group, 21 April 2023, . * [RFC8414] M. Jones, N. Sakimura, J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, June 2018, . From d6dbbf806f4a146fbb5d32698d1915775a190611 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Fri, 15 Sep 2023 10:08:50 +0200 Subject: [PATCH 06/28] stuff --- rfc/rfc021-vp_token-grant-type.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 2fb20ea..35314c6 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -100,7 +100,7 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 3. The Presentation Submission MUST be an answer to the Presentation Definition that corresponds with the requested scope. How an authorization server determines the Presentation Definition based on scope is out of scope of this specification. However, a request to the Presentation Definition endpoint MUST result to the same Presentation Definition as the Presentation Definition that is used to validate the VP. -4. The Verifiable Presentation MUST be not be valid for more than 15 minutes. +4. The Verifiable Presentation validity determines the upper bound of access token validity. 5. A clock skew of no more than 5 seconds MAY be applied when validating the Verifiable Presentation. ### 4.2 JWT requirements From 499547024759bc4296248cceebc2a105db41b782 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Wed, 20 Sep 2023 07:57:30 +0200 Subject: [PATCH 07/28] add scope param to example --- rfc/rfc021-vp_token-grant-type.md | 1 + 1 file changed, 1 insertion(+) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 35314c6..81eea5f 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -75,6 +75,7 @@ The following example demonstrates an access token request with a VP as an autho eyJpc3Mi[...omitted for brevity...]. J9l-ZhwP[...omitted for brevity...] &presentation_submission= {..} + &scope=a_scope ## 3.1 Assertion Encoding From fdb9f2cd62e915b0b94742d23ca0b6c38c577848 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Wed, 20 Sep 2023 13:49:24 +0200 Subject: [PATCH 08/28] PR feedback --- rfc/rfc021-vp_token-grant-type.md | 95 ++++++++++++++++++++----------- 1 file changed, 61 insertions(+), 34 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 81eea5f..20b046b 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -10,8 +10,7 @@ ### Abstract -This specification defines the use of a Verifiable Presentation Bearer -Token as a means for requesting an OAuth 2.0 access token. +This specification defines the use of a Verifiable Presentation Bearer Token as a means for requesting an OAuth 2.0 access token. ### Status of document @@ -25,21 +24,33 @@ This document is released under the [Attribution-ShareAlike 4.0 International \( ## 1. Introduction -A Verifiable Presentation [VP] is an encoding that enables identity and security information base on Verifiable Credentials to be shared across security domains. -A security token is generally issued by an Identity Provider and consumed by a Relying Party that relies on its content to identify the token's subject for security-related purposes. +A Verifiable Presentation [VP] is an encoding that enables identity and security information based on Verifiable Credentials to be shared across security domains. +A security token is generally issued by an Authorization Server and consumed by a Relying Party that relies on its content to make authorization decisions. In the case of Verifiable Credentials, the assertion is self-issued by the holder using a wallet. -The relying party role equals the verifier role as defined by the Verifiable Credentials specification. +The Relying Party role equals the verifier role as defined by the Verifiable Credentials specification. The OAuth 2.0 Authorization Framework [RFC6749] provides a method for making authenticated HTTP requests to a resource using an access token. -Access tokens are issued to third-party clients by an authorization server (AS) with the (sometimes implicit) approval of the resource owner. +Access tokens are issued to third-party clients by an Authorization Server (AS) with the (sometimes implicit) approval of the resource owner. In OAuth, an authorization grant is an abstract term used to describe intermediate credentials that represent the resource owner authorization. An authorization grant is used by the client to obtain an access token. Several authorization grant types are defined to support a wide range of client types and user experiences. OAuth also allows for the definition of new extension grant types to support additional clients or to provide a bridge between OAuth and other trust frameworks. -Finally, OAuth allows the definition of additional authentication mechanisms to be used by clients when interacting with the authorization server. +Finally, OAuth allows the definition of additional authentication mechanisms to be used by clients when interacting with the Authorization Server. "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants" [RFC7521] is an abstract extension to OAuth 2.0 that provides a general framework for the use of assertions (a.k.a. security tokens) as client credentials and/or authorization grants with OAuth 2.0. This specification profiles [RFC7521] to define an extension grant type that uses a self-issued Verifiable Presentation Bearer Token to request an OAuth 2.0 access token. +A Verifiable Presentation is created by a holder and can be used to prove possession of a Verifiable Credential. +The holder will need to know which Verifiable Credentials are required to access a resource. +The Authorization Server provides this information in the form of a Presentation Definition [PE]. +The complete flow consists of the following steps: + +1. The client requests a Presentation Definition from the Authorization Server. +2. The client creates a Verifiable Presentation that matches the Presentation Definition. +3. The client requests an access token from the Authorization Server using the Verifiable Presentation as an authorization grant. +4. The Authorization Server validates the Verifiable Presentation and Presentation Definition. +5. The Authorization Server issues an access token. +6. The client uses the access token to access a resource. + ## 2. Terminology All terms are as defined in the following specifications: "The OAuth 2.0 Authorization Framework" [RFC6749], the OAuth Assertion Framework [RFC7521] "JSON Web Token (JWT)" [JWT], Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL], Verifiable Credentials Presentation Exchange [PE], JSON Web Signature 2020 [JSONWebSignature2020], Decentralized Identifiers 1.0 [DID]. @@ -59,7 +70,7 @@ The value of the "assertion" parameter MUST contain a Verifiable Presentation. T * The Verifiable Presentation is encoded as JWT according to section §6.3.1 of the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. The "scope" parameter MUST be used, as defined in the OAuth Assertion Framework [RFC7521], to indicate the requested scope. -The scope parameter determines the set of credentials the authorization server expects. +The scope parameter determines the set of credentials the Authorization Server expects. The "presentation_submission" parameter MUST be used, as defined in Presentation Exchange [PE], to indicate how the VP matches the requested Verifiable Credentials. The Presentation Submission MUST be encoded using the application/x-www-form-urlencoded content type. @@ -79,46 +90,45 @@ The following example demonstrates an access token request with a VP as an autho ## 3.1 Assertion Encoding -As stated in the previous section, the assertion parameter can either be encoded in JSON or JWT. -The authorization server determines the encoding by adding the correct parameters to the authorization server metadata [RFC8414]]. +The assertion parameter can either be encoded in JSON or JWT. +The Authorization Server determines the encoding by adding the correct parameters to the Authorization Server metadata [RFC8414]]. The following parameter MUST be added: * `vp_formats`: An object defining the formats and proof types of Verifiable Presentations and Verifiable Credentials that a Verifier supports as stated by §9 of the OpenID for Verifiable Presentations specification [OIDC4VP]. -When processing the assertion the authorization server can detect the used format by checking the initial character. +When processing the assertion the Authorization Server can detect the used format by checking the initial character. A JSON encoded assertion starts with a '{' character or '%7B' when urlencoded. -## 4. Processing requirements +## 4. JWT Format and Processing Requirements -In order to issue an access token response as described in OAuth 2.0 [RFC6749], the authorization server MUST validate the VP. +In order to issue an access token response as described in OAuth 2.0 [RFC6749], the Authorization Server MUST validate the VP. The validation requirements are split into three paragraphs. The first paragraph describes the requirements that apply to all VP's. The second paragraph describes the requirements that apply to JWT encoded VP's. The third paragraph describes the requirements that apply to JSON encoded VP's. -### 4.1 General requirements +### 4.1 General processing requirements -1. The authorization server MUST validate the Presentation Submission according to section 6 of the Presentation Exchange [PE] specification. -2. The authorization server MUST validate the VP according to section 6.1 of the Presentation Exchange [PE] specification. -3. The Presentation Submission MUST be an answer to the Presentation Definition that corresponds with the requested scope. - How an authorization server determines the Presentation Definition based on scope is out of scope of this specification. - However, a request to the Presentation Definition endpoint MUST result to the same Presentation Definition as the Presentation Definition that is used to validate the VP. +1. The Authorization Server MUST validate the Presentation Submission according to section 6 of the Presentation Exchange [PE] specification. +2. The Authorization Server MUST validate the VP and Presentation Submission according to section 6.1 of the Presentation Exchange [PE] specification. +3. The Presentation Submission MUST be an answer to the Presentation Definition that corresponds with the requested scope. + How an Authorization Server determines the Presentation Definition based on scope is out of scope of this specification. 4. The Verifiable Presentation validity determines the upper bound of access token validity. 5. A clock skew of no more than 5 seconds MAY be applied when validating the Verifiable Presentation. -### 4.2 JWT requirements +### 4.2 JWT format requirements 1. The assertion MUST be a valid JWT according to §6.3.1 of the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. 2. The `vp` field of the JWT MUST be valid according to §4.10 the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. -3. The `nonce` of the JWT MUST be a string that is unique for each request. +3. The `nonce` of the JWT MUST be a string that is unique for each access token request. 4. The `iss` field MUST be a Decentralized Identifier [DID]. 5. The `kid` field MUST be a DID URL and MUST resolve to a verificationMethod in the DID Document. The DID part of the DID URL MUST match the `iss` field. 6. The `sub` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. -7. The `aud` field MUST be a DID under control of the Authorization Server. +7. The `aud` field MUST match the DID of the Authorization Server. -### 4.3 JSON requirements +### 4.3 JSON format requirements 1. The assertion MUST be a valid JSON object according to §4.10 the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. 2. The proof of the VP MUST be a valid [JSONWebSignature2020] object. -3. The `challenge` field of the JSON object MUST be a string that is unique for each request. +3. The `challenge` field of the JSON object MUST be a string that is unique for each token request. 4. The `domain` field of the JSON object MUST be a DID under control of the Authorization Server. 5. The `verificationMethod` field of the Proof MUST be a DID URL. 6. The `holder` field if present MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. @@ -126,29 +136,46 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. ## 5. Presentation Definition endpoint -In order for a client to know which Presentation Definition [PE] to use, the authorization server MUST provide a Presentation Definition endpoint. -The Presentation Definition endpoint MUST be registered as a `presentation_definition_endpoint` in the authorization server metadata [RFC8414]. +In order for a client to know which Presentation Definition [PE] to use, the Authorization Server MUST provide a Presentation Definition endpoint. +The Presentation Definition endpoint MUST be registered as a `presentation_definition_endpoint` in the Authorization Server metadata [RFC8414]. The Presentation Definition endpoint MUST return a Presentation Definition that corresponds with the requested scope. +The endpoint has a single query parameter `scope` that contains the requested scope. The parameter may contain multiple values. + +The following example shows a request to the Presentation Definition endpoint: + + GET /presentation_definition?scope=a&scope=b HTTP/1.1 + Host: as.example.com ## 6. Access Token Introspection -The authorization server MUST support the access token introspection endpoint as defined in OAuth 2.0 [RFC7662]. -The introspection endpoint MUST return the following fields: +The Authorization Server MAY support an access token introspection endpoint as defined in OAuth 2.0 [RFC7662]. +The introspection endpoint SHOULD map the fields as follows: -* `iss`: The issuer of the access token. -* `sub`: The subject of the access token. +* `iss`: The issuer of the access token (DID). +* `sub`: The subject of the access token (DID). * `exp`: The expiration time of the access token. * `iat`: The time the access token was issued. * `scope`: The granted scope. -* `vcs`: The Verifiable Credentials that were used to request the access token. +* `vcs`: The Verifiable Credentials that were used to request the access token using the same encoding as used in the access token request. ## 7. Security Considerations The nonce/challenge (nonce) is used to prevent replay attacks. The nonce is a random string that is generated by the client. -The nonce is included in the signed data. The authorization server MUST reject any request that uses a nonce that has been used before. -The authorization server MAY reduce storage requirements by only storing the nonce for the lifetime of the Verifiable Presentation. +The nonce is included in the signed data. The Authorization Server MUST reject any request that uses a nonce that has been used before. +The Authorization Server MAY reduce storage requirements by only storing the nonce for the lifetime of the Verifiable Presentation. + +All endpoints MUST be protected by TLS, version 1.2 as a minimum. + +## 8. Privacy considerations + +This RFC is meant to be used in a machine to machine context. +If any personal data may be accessed with an `vp_token-bearer` access token, it's recommended to reevaluate and use the OpenID4VP specification and include user authorization. + +Extra care should be taken when designing the scope to Presentation Definition mapping. +Scopes on the personal data level should not result in different Presentation Definitions. +This could be abused to determine if certain data is available at a Resource Server. -## 8. References +## 9. References * [RFC6749] D. Hardt, "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012, . * [RFC7521] D. Campbell, Ed., B. Zaninovich, Ed., "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, May 2015, . From a4d54816d15955613ae91863e76cbc0ba0e9d7dd Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Wed, 27 Sep 2023 11:43:14 +0200 Subject: [PATCH 09/28] PR feedback --- rfc/rfc021-vp_token-grant-type.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 20b046b..70d6f7f 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -25,9 +25,8 @@ This document is released under the [Attribution-ShareAlike 4.0 International \( ## 1. Introduction A Verifiable Presentation [VP] is an encoding that enables identity and security information based on Verifiable Credentials to be shared across security domains. -A security token is generally issued by an Authorization Server and consumed by a Relying Party that relies on its content to make authorization decisions. -In the case of Verifiable Credentials, the assertion is self-issued by the holder using a wallet. -The Relying Party role equals the verifier role as defined by the Verifiable Credentials specification. +A security token is generally issued by an Authorization Server and consumed by a client that relies on its content to make authorization decisions. +In the case of Verifiable Credentials, the presentation is self-signed by the holder using a wallet. The OAuth 2.0 Authorization Framework [RFC6749] provides a method for making authenticated HTTP requests to a resource using an access token. Access tokens are issued to third-party clients by an Authorization Server (AS) with the (sometimes implicit) approval of the resource owner. @@ -44,10 +43,10 @@ The holder will need to know which Verifiable Credentials are required to access The Authorization Server provides this information in the form of a Presentation Definition [PE]. The complete flow consists of the following steps: -1. The client requests a Presentation Definition from the Authorization Server. -2. The client creates a Verifiable Presentation that matches the Presentation Definition. +1. The client requests a Presentation Definition from the Authorization Server based on a scope. +2. The client creates a Verifiable Presentation and a Presentation Submission that describes how the VP fulfills the requirements of the Presentation Definition. 3. The client requests an access token from the Authorization Server using the Verifiable Presentation as an authorization grant. -4. The Authorization Server validates the Verifiable Presentation and Presentation Definition. +4. The Authorization Server validates the Verifiable Presentation and Presentation Submission. 5. The Authorization Server issues an access token. 6. The client uses the access token to access a resource. @@ -69,7 +68,7 @@ The value of the "assertion" parameter MUST contain a Verifiable Presentation. T * The Verifiable Presentation is encoded as JSON using the application/x-www-form-urlencoded content type. * The Verifiable Presentation is encoded as JWT according to section §6.3.1 of the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. -The "scope" parameter MUST be used, as defined in the OAuth Assertion Framework [RFC7521], to indicate the requested scope. +The "scope" parameter MUST be used, as defined in the OAuth Assertion Framework [RFC6749], to indicate the requested scope. The scope parameter determines the set of credentials the Authorization Server expects. The "presentation_submission" parameter MUST be used, as defined in Presentation Exchange [PE], to indicate how the VP matches the requested Verifiable Credentials. @@ -120,7 +119,7 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 2. The `vp` field of the JWT MUST be valid according to §4.10 the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. 3. The `nonce` of the JWT MUST be a string that is unique for each access token request. 4. The `iss` field MUST be a Decentralized Identifier [DID]. -5. The `kid` field MUST be a DID URL and MUST resolve to a verificationMethod in the DID Document. The DID part of the DID URL MUST match the `iss` field. +5. The `kid` header MUST be a DID URL and MUST resolve to a verificationMethod in the DID Document. The DID part of the DID URL MUST match the `iss` field. 6. The `sub` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. 7. The `aud` field MUST match the DID of the Authorization Server. From 0d04aa2abf3b71612463ba7e10ac86412207452c Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Mon, 2 Oct 2023 10:15:52 +0200 Subject: [PATCH 10/28] PR feedback --- rfc/rfc021-vp_token-grant-type.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 70d6f7f..62f4876 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -72,7 +72,7 @@ The "scope" parameter MUST be used, as defined in the OAuth Assertion Framework The scope parameter determines the set of credentials the Authorization Server expects. The "presentation_submission" parameter MUST be used, as defined in Presentation Exchange [PE], to indicate how the VP matches the requested Verifiable Credentials. -The Presentation Submission MUST be encoded using the application/x-www-form-urlencoded content type. +The Presentation Submission MUST be in JSON format, URL encoded. The following example demonstrates an access token request with a VP as an authorization grant (with extra line breaks for display purposes only): From cc3d2e48f64e544896dca491e8c5004c2cb08a29 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Tue, 3 Oct 2023 13:32:15 +0200 Subject: [PATCH 11/28] changed use of jti/challenge over nonce and more strict scope usage --- rfc/rfc021-vp_token-grant-type.md | 54 +++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 62f4876..110da37 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -122,6 +122,10 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 5. The `kid` header MUST be a DID URL and MUST resolve to a verificationMethod in the DID Document. The DID part of the DID URL MUST match the `iss` field. 6. The `sub` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. 7. The `aud` field MUST match the DID of the Authorization Server. +8. The `iat` field MUST be present and contain a valid timestamp. It MUST be before the current time. +9. The `exp` field MUST be present and contain a valid timestamp. It MUST be after the current time. +10. The difference between the `exp` and `iat` fields MUST be equal or less than 5 seconds. +11. The `jti` field MUST be present and contain a string that is unique for each access token request. ### 4.3 JSON format requirements @@ -132,20 +136,58 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 5. The `verificationMethod` field of the Proof MUST be a DID URL. 6. The `holder` field if present MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. 7. The `verificationMethod` field of the proof MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. +8. The `created` field of the proof MUST be present and contain a valid timestamp. It MUST be before the current time. +9. The `expires` field of the proof MUST be present and contain a valid timestamp. It MUST be after the current time. +10. The difference between the `expires` and `created` fields MUST be equal or less than 5 seconds. + +### 4.4 Preventing Token Replay + +The Authorization Server MUST reject any request that uses the unique value (`jti` or `challenge`) that has been used before. +This approach has been chosen over the `nonce` field because there's no initial request to get a nonce from the Authorization Server. +The Authorization Server MUST store the unique value for 10 seconds and MUST reject any request that uses a unique value that has been used before. +The 10 seconds is based on the 5-second clock skew and the 5-second maximum difference between the expires and issued fields. ## 5. Presentation Definition endpoint In order for a client to know which Presentation Definition [PE] to use, the Authorization Server MUST provide a Presentation Definition endpoint. The Presentation Definition endpoint MUST be registered as a `presentation_definition_endpoint` in the Authorization Server metadata [RFC8414]. -The Presentation Definition endpoint MUST return a Presentation Definition that corresponds with the requested scope. +The Presentation Definition endpoint MUST return a Presentation Definition array that corresponds with the requested scope. The endpoint has a single query parameter `scope` that contains the requested scope. The parameter may contain multiple values. +Values are separated by a space and MUST be URL encoded. The following example shows a request to the Presentation Definition endpoint: - GET /presentation_definition?scope=a&scope=b HTTP/1.1 + GET /presentation_definition?scope=a+b HTTP/1.1 Host: as.example.com -## 6. Access Token Introspection +## 6. Scopes + +The scope parameter is used to indicate which Verifiable Credentials are required to access a resource. +The OAuth 2.0 Authorization Framework allows the use of multiple scopes. +To simplify processing, this specification only allows a single main scope and multiple sub-scopes. +Allowing mixing of different main scopes in a single access token request is out of scope of this specification. +The Authorization Server MUST reject any request that contains multiple main scopes. + +A main scope is defined as the first scope in the scope parameter. +It MUST be present and MUST be a string and can't contain `:`. +A sub-scope is defined as any scope after the main scope. +It MUST be a string and can contain `:` to indicate specific resources that need to be accessed. +It SHOULD follow the format `resource:id:operation` where `resource` is the resource type, `id` is the specific identifier of the resource and `operation` is the operation that is allowed on the resource. + +The following example shows a request to the token endpoint with a main scope and a sub-scope: + + POST /token.oauth2 HTTP/1.1 + Host: as.example.com + Content-Type: application/x-www-form-urlencoded + + grant_type=vp_token-bearer + &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0. + eyJpc3Mi[...omitted for brevity...]. + J9l-ZhwP[...omitted for brevity...] + &presentation_submission= {..} + &scope=a_scope+a_resource:5:read + +## 7. Access Token Introspection The Authorization Server MAY support an access token introspection endpoint as defined in OAuth 2.0 [RFC7662]. The introspection endpoint SHOULD map the fields as follows: @@ -157,7 +199,7 @@ The introspection endpoint SHOULD map the fields as follows: * `scope`: The granted scope. * `vcs`: The Verifiable Credentials that were used to request the access token using the same encoding as used in the access token request. -## 7. Security Considerations +## 8. Security Considerations The nonce/challenge (nonce) is used to prevent replay attacks. The nonce is a random string that is generated by the client. The nonce is included in the signed data. The Authorization Server MUST reject any request that uses a nonce that has been used before. @@ -165,7 +207,7 @@ The Authorization Server MAY reduce storage requirements by only storing the non All endpoints MUST be protected by TLS, version 1.2 as a minimum. -## 8. Privacy considerations +## 9. Privacy considerations This RFC is meant to be used in a machine to machine context. If any personal data may be accessed with an `vp_token-bearer` access token, it's recommended to reevaluate and use the OpenID4VP specification and include user authorization. @@ -174,7 +216,7 @@ Extra care should be taken when designing the scope to Presentation Definition m Scopes on the personal data level should not result in different Presentation Definitions. This could be abused to determine if certain data is available at a Resource Server. -## 9. References +## 10. References * [RFC6749] D. Hardt, "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012, . * [RFC7521] D. Campbell, Ed., B. Zaninovich, Ed., "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, May 2015, . From 9c39be273b09d07372cb8f237af6fc485d0ff17b Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Mon, 9 Oct 2023 09:06:01 +0200 Subject: [PATCH 12/28] added error codes --- rfc/rfc021-vp_token-grant-type.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 110da37..c42d0ac 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -147,6 +147,15 @@ This approach has been chosen over the `nonce` field because there's no initial The Authorization Server MUST store the unique value for 10 seconds and MUST reject any request that uses a unique value that has been used before. The 10 seconds is based on the 5-second clock skew and the 5-second maximum difference between the expires and issued fields. +### 4.5 Error Response + +If the Authorization Server determines that the VP is invalid, the Authorization Server MUST return an error response as defined in OAuth 2.0 [RFC6749]. +In addition to the error response defined in OAuth 2.0 [RFC6749], the Authorization Server MUST use the following error codes when the VP is invalid: + +* `invalid_verifiable_presentation`: The VP is invalid. This error code is used when the signature is incorrect or when a required field is missing. +* `invalid_presentation_submission`: The Presentation Submission is invalid. This error code is used when the Presentation Submission is not an answer to the Presentation Definition that corresponds with the requested scope. +* `invalid_verifiable_credentials`: The submitted Verifiable Credentials do not meet the requirements. This error code is used when the Verifiable Credentials aren't corresponding to the Presentation Definition or when the Verifiable Credentials are expired, not trusted or invalid. + ## 5. Presentation Definition endpoint In order for a client to know which Presentation Definition [PE] to use, the Authorization Server MUST provide a Presentation Definition endpoint. From 60d54cc0e90c72ce8962158aebf0c7642a306384 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Thu, 12 Oct 2023 08:14:34 +0200 Subject: [PATCH 13/28] PR feedback --- rfc/rfc021-vp_token-grant-type.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index c42d0ac..b4443b4 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -134,11 +134,10 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 3. The `challenge` field of the JSON object MUST be a string that is unique for each token request. 4. The `domain` field of the JSON object MUST be a DID under control of the Authorization Server. 5. The `verificationMethod` field of the Proof MUST be a DID URL. -6. The `holder` field if present MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. -7. The `verificationMethod` field of the proof MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. -8. The `created` field of the proof MUST be present and contain a valid timestamp. It MUST be before the current time. -9. The `expires` field of the proof MUST be present and contain a valid timestamp. It MUST be after the current time. -10. The difference between the `expires` and `created` fields MUST be equal or less than 5 seconds. +6. The `verificationMethod` field of the proof MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. +7. The `created` field of the proof MUST be present and contain a valid timestamp. It MUST be before the current time. +8. The `expires` field of the proof MUST be present and contain a valid timestamp. It MUST be after the current time. +9. The difference between the `expires` and `created` fields MUST be equal or less than 5 seconds. ### 4.4 Preventing Token Replay @@ -150,17 +149,19 @@ The 10 seconds is based on the 5-second clock skew and the 5-second maximum diff ### 4.5 Error Response If the Authorization Server determines that the VP is invalid, the Authorization Server MUST return an error response as defined in OAuth 2.0 [RFC6749]. -In addition to the error response defined in OAuth 2.0 [RFC6749], the Authorization Server MUST use the following error codes when the VP is invalid: +In addition to the error response defined in OAuth 2.0 [RFC6749], the Authorization Server MUST return a HTTP 400 (Bad Request) and use the following error codes when the VP is invalid: * `invalid_verifiable_presentation`: The VP is invalid. This error code is used when the signature is incorrect or when a required field is missing. * `invalid_presentation_submission`: The Presentation Submission is invalid. This error code is used when the Presentation Submission is not an answer to the Presentation Definition that corresponds with the requested scope. -* `invalid_verifiable_credentials`: The submitted Verifiable Credentials do not meet the requirements. This error code is used when the Verifiable Credentials aren't corresponding to the Presentation Definition or when the Verifiable Credentials are expired, not trusted or invalid. +* `invalid_verifiable_credentials`: The submitted Verifiable Credentials do not meet the requirements. This error code is used when the Verifiable Credentials aren't corresponding to the Presentation Definition or when the Verifiable Credentials are expired, not trusted or invalid. +It is also used when the Verifiable Credentials are not issued to the signer of the Verifiable Presentation. ## 5. Presentation Definition endpoint In order for a client to know which Presentation Definition [PE] to use, the Authorization Server MUST provide a Presentation Definition endpoint. The Presentation Definition endpoint MUST be registered as a `presentation_definition_endpoint` in the Authorization Server metadata [RFC8414]. -The Presentation Definition endpoint MUST return a Presentation Definition array that corresponds with the requested scope. +The Presentation Definition endpoint MUST return a single Presentation Definition that corresponds with the requested scope. +The client MUST support the Submission Requirement Feature [PE]. The endpoint has a single query parameter `scope` that contains the requested scope. The parameter may contain multiple values. Values are separated by a space and MUST be URL encoded. @@ -177,7 +178,7 @@ To simplify processing, this specification only allows a single main scope and m Allowing mixing of different main scopes in a single access token request is out of scope of this specification. The Authorization Server MUST reject any request that contains multiple main scopes. -A main scope is defined as the first scope in the scope parameter. +The main scope MUST be the first value in the scope parameter. It MUST be present and MUST be a string and can't contain `:`. A sub-scope is defined as any scope after the main scope. It MUST be a string and can contain `:` to indicate specific resources that need to be accessed. @@ -219,7 +220,7 @@ All endpoints MUST be protected by TLS, version 1.2 as a minimum. ## 9. Privacy considerations This RFC is meant to be used in a machine to machine context. -If any personal data may be accessed with an `vp_token-bearer` access token, it's recommended to reevaluate and use the OpenID4VP specification and include user authorization. +If any personal data may be accessed with an `vp_token-bearer` access token, it's recommended to reevaluate and use the OpenID4VP specification and include user authentication. Extra care should be taken when designing the scope to Presentation Definition mapping. Scopes on the personal data level should not result in different Presentation Definitions. From 4716cea13e6b73506adc1a2760b4870c1776ea33 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Thu, 12 Oct 2023 08:29:26 +0200 Subject: [PATCH 14/28] added empty scope --- rfc/rfc021-vp_token-grant-type.md | 1 + 1 file changed, 1 insertion(+) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index b4443b4..f5550f1 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -164,6 +164,7 @@ The Presentation Definition endpoint MUST return a single Presentation Definitio The client MUST support the Submission Requirement Feature [PE]. The endpoint has a single query parameter `scope` that contains the requested scope. The parameter may contain multiple values. Values are separated by a space and MUST be URL encoded. +An empty scope MAY be used. The Authorization Server MUST return a Presentation Definition which MAY contain constraints. The following example shows a request to the Presentation Definition endpoint: From d5ed03d49972039f2d7708971567f22d391412c2 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Tue, 17 Oct 2023 08:45:35 +0200 Subject: [PATCH 15/28] some small privacy related things --- rfc/rfc021-vp_token-grant-type.md | 32 +++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index f5550f1..09eb047 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -117,15 +117,14 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 1. The assertion MUST be a valid JWT according to §6.3.1 of the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. 2. The `vp` field of the JWT MUST be valid according to §4.10 the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. -3. The `nonce` of the JWT MUST be a string that is unique for each access token request. -4. The `iss` field MUST be a Decentralized Identifier [DID]. -5. The `kid` header MUST be a DID URL and MUST resolve to a verificationMethod in the DID Document. The DID part of the DID URL MUST match the `iss` field. -6. The `sub` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. -7. The `aud` field MUST match the DID of the Authorization Server. -8. The `iat` field MUST be present and contain a valid timestamp. It MUST be before the current time. -9. The `exp` field MUST be present and contain a valid timestamp. It MUST be after the current time. -10. The difference between the `exp` and `iat` fields MUST be equal or less than 5 seconds. -11. The `jti` field MUST be present and contain a string that is unique for each access token request. +3. The `iss` field MUST be a Decentralized Identifier [DID]. +4. The `kid` header MUST be a DID URL and MUST resolve to a verificationMethod in the DID Document. The DID part of the DID URL MUST match the `iss` field. +5. The `sub` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. +6. The `aud` field MUST match the DID of the Authorization Server. +7. The `iat` field MUST be present and contain a valid timestamp. It MUST be before the current time. +8. The `exp` field MUST be present and contain a valid timestamp. It MUST be after the current time. +9. The difference between the `exp` and `iat` fields MUST be equal or less than 5 seconds. +10. The `jti` field MUST be present and contain a string that is unique for each access token request. ### 4.3 JSON format requirements @@ -180,10 +179,13 @@ Allowing mixing of different main scopes in a single access token request is out The Authorization Server MUST reject any request that contains multiple main scopes. The main scope MUST be the first value in the scope parameter. -It MUST be present and MUST be a string and can't contain `:`. +It MUST be present and MUST be a string and can't contain `/`. A sub-scope is defined as any scope after the main scope. -It MUST be a string and can contain `:` to indicate specific resources that need to be accessed. -It SHOULD follow the format `resource:id:operation` where `resource` is the resource type, `id` is the specific identifier of the resource and `operation` is the operation that is allowed on the resource. +It MUST be a string and can contain `/` to indicate specific resources that need to be accessed. +It SHOULD follow the format `resource/id.operation` where `resource` is the resource type, `id` is the specific identifier of the resource and `operation` is the operation that is allowed on the resource. +The example below indicates read and write access to a resource with identifier 5: + + resource/5.rw The following example shows a request to the token endpoint with a main scope and a sub-scope: @@ -212,9 +214,8 @@ The introspection endpoint SHOULD map the fields as follows: ## 8. Security Considerations -The nonce/challenge (nonce) is used to prevent replay attacks. The nonce is a random string that is generated by the client. +The jti/challenge (further called nonce) is used to prevent replay attacks. The nonce is a random string that is generated by the client. The nonce is included in the signed data. The Authorization Server MUST reject any request that uses a nonce that has been used before. -The Authorization Server MAY reduce storage requirements by only storing the nonce for the lifetime of the Verifiable Presentation. All endpoints MUST be protected by TLS, version 1.2 as a minimum. @@ -227,6 +228,9 @@ Extra care should be taken when designing the scope to Presentation Definition m Scopes on the personal data level should not result in different Presentation Definitions. This could be abused to determine if certain data is available at a Resource Server. +The Presentation Definition endpoint contains a scope parameter which could be logged in an access log. +Privacy-sensitive data in the scope parameter should be avoided. + ## 10. References * [RFC6749] D. Hardt, "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012, . From e70e169c4d884be9a81cab840daac45972ddf8fb Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Tue, 17 Oct 2023 13:55:35 +0200 Subject: [PATCH 16/28] remove parsing detection --- rfc/rfc021-vp_token-grant-type.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 09eb047..6adbb40 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -95,9 +95,6 @@ The following parameter MUST be added: * `vp_formats`: An object defining the formats and proof types of Verifiable Presentations and Verifiable Credentials that a Verifier supports as stated by §9 of the OpenID for Verifiable Presentations specification [OIDC4VP]. -When processing the assertion the Authorization Server can detect the used format by checking the initial character. -A JSON encoded assertion starts with a '{' character or '%7B' when urlencoded. - ## 4. JWT Format and Processing Requirements In order to issue an access token response as described in OAuth 2.0 [RFC6749], the Authorization Server MUST validate the VP. From 6e8d31b76a6cc031c0e547123c411152be1c7e44 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Tue, 24 Oct 2023 16:01:26 +0200 Subject: [PATCH 17/28] Removed scope chapter --- rfc/rfc021-vp_token-grant-type.md | 38 ++++--------------------------- 1 file changed, 4 insertions(+), 34 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 6adbb40..9fc6935 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -167,37 +167,7 @@ The following example shows a request to the Presentation Definition endpoint: GET /presentation_definition?scope=a+b HTTP/1.1 Host: as.example.com -## 6. Scopes - -The scope parameter is used to indicate which Verifiable Credentials are required to access a resource. -The OAuth 2.0 Authorization Framework allows the use of multiple scopes. -To simplify processing, this specification only allows a single main scope and multiple sub-scopes. -Allowing mixing of different main scopes in a single access token request is out of scope of this specification. -The Authorization Server MUST reject any request that contains multiple main scopes. - -The main scope MUST be the first value in the scope parameter. -It MUST be present and MUST be a string and can't contain `/`. -A sub-scope is defined as any scope after the main scope. -It MUST be a string and can contain `/` to indicate specific resources that need to be accessed. -It SHOULD follow the format `resource/id.operation` where `resource` is the resource type, `id` is the specific identifier of the resource and `operation` is the operation that is allowed on the resource. -The example below indicates read and write access to a resource with identifier 5: - - resource/5.rw - -The following example shows a request to the token endpoint with a main scope and a sub-scope: - - POST /token.oauth2 HTTP/1.1 - Host: as.example.com - Content-Type: application/x-www-form-urlencoded - - grant_type=vp_token-bearer - &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0. - eyJpc3Mi[...omitted for brevity...]. - J9l-ZhwP[...omitted for brevity...] - &presentation_submission= {..} - &scope=a_scope+a_resource:5:read - -## 7. Access Token Introspection +## 6. Access Token Introspection The Authorization Server MAY support an access token introspection endpoint as defined in OAuth 2.0 [RFC7662]. The introspection endpoint SHOULD map the fields as follows: @@ -209,14 +179,14 @@ The introspection endpoint SHOULD map the fields as follows: * `scope`: The granted scope. * `vcs`: The Verifiable Credentials that were used to request the access token using the same encoding as used in the access token request. -## 8. Security Considerations +## 7. Security Considerations The jti/challenge (further called nonce) is used to prevent replay attacks. The nonce is a random string that is generated by the client. The nonce is included in the signed data. The Authorization Server MUST reject any request that uses a nonce that has been used before. All endpoints MUST be protected by TLS, version 1.2 as a minimum. -## 9. Privacy considerations +## 8. Privacy considerations This RFC is meant to be used in a machine to machine context. If any personal data may be accessed with an `vp_token-bearer` access token, it's recommended to reevaluate and use the OpenID4VP specification and include user authentication. @@ -228,7 +198,7 @@ This could be abused to determine if certain data is available at a Resource Ser The Presentation Definition endpoint contains a scope parameter which could be logged in an access log. Privacy-sensitive data in the scope parameter should be avoided. -## 10. References +## 9. References * [RFC6749] D. Hardt, "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012, . * [RFC7521] D. Campbell, Ed., B. Zaninovich, Ed., "Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants", RFC 7521, DOI 10.17487/RFC7521, May 2015, . From 04021d5dac69820f284f70dd7fd8d9c153d15f48 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Thu, 26 Oct 2023 11:55:06 +0200 Subject: [PATCH 18/28] small things --- rfc/rfc021-vp_token-grant-type.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 9fc6935..e2d7f0a 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -107,14 +107,13 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 2. The Authorization Server MUST validate the VP and Presentation Submission according to section 6.1 of the Presentation Exchange [PE] specification. 3. The Presentation Submission MUST be an answer to the Presentation Definition that corresponds with the requested scope. How an Authorization Server determines the Presentation Definition based on scope is out of scope of this specification. -4. The Verifiable Presentation validity determines the upper bound of access token validity. -5. A clock skew of no more than 5 seconds MAY be applied when validating the Verifiable Presentation. +4. A clock skew of no more than 5 seconds MAY be applied when validating the Verifiable Presentation. ### 4.2 JWT format requirements 1. The assertion MUST be a valid JWT according to §6.3.1 of the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. 2. The `vp` field of the JWT MUST be valid according to §4.10 the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. -3. The `iss` field MUST be a Decentralized Identifier [DID]. +3. The `iss` field MUST be a Decentralized Identifier [DID] and match the `sub` field. 4. The `kid` header MUST be a DID URL and MUST resolve to a verificationMethod in the DID Document. The DID part of the DID URL MUST match the `iss` field. 5. The `sub` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. 6. The `aud` field MUST match the DID of the Authorization Server. From 3797e92cac424d52224754c72eedd231d40cec93 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Fri, 27 Oct 2023 09:02:43 +0200 Subject: [PATCH 19/28] added client_id to introspection --- rfc/rfc021-vp_token-grant-type.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index e2d7f0a..36d017d 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -172,7 +172,8 @@ The Authorization Server MAY support an access token introspection endpoint as d The introspection endpoint SHOULD map the fields as follows: * `iss`: The issuer of the access token (DID). -* `sub`: The subject of the access token (DID). +* `sub`: The subject of the access token (DID), this is the resource owner. Usually the same as the `iss` field. +* `client_id`: The client (DID) that requested the access token. * `exp`: The expiration time of the access token. * `iat`: The time the access token was issued. * `scope`: The granted scope. From b82d74f8ca752e95b238e9f8b1e925f410592708 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Fri, 3 Nov 2023 12:04:20 +0100 Subject: [PATCH 20/28] PR feedback --- rfc/rfc021-vp_token-grant-type.md | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 36d017d..14b3109 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -93,7 +93,7 @@ The assertion parameter can either be encoded in JSON or JWT. The Authorization Server determines the encoding by adding the correct parameters to the Authorization Server metadata [RFC8414]]. The following parameter MUST be added: -* `vp_formats`: An object defining the formats and proof types of Verifiable Presentations and Verifiable Credentials that a Verifier supports as stated by §9 of the OpenID for Verifiable Presentations specification [OIDC4VP]. +* `vp_formats`: An object defining the formats and proof types of Verifiable Presentations and Verifiable Credentials that a Verifier supports as stated by §9 of the OpenID for Verifiable Presentations specification [OpenID4VP]. ## 4. JWT Format and Processing Requirements @@ -117,22 +117,22 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 4. The `kid` header MUST be a DID URL and MUST resolve to a verificationMethod in the DID Document. The DID part of the DID URL MUST match the `iss` field. 5. The `sub` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. 6. The `aud` field MUST match the DID of the Authorization Server. -7. The `iat` field MUST be present and contain a valid timestamp. It MUST be before the current time. -8. The `exp` field MUST be present and contain a valid timestamp. It MUST be after the current time. +7. The `iat` field MUST be present and contain a valid unix timestamp. It MUST be before the current time. +8. The `exp` field MUST be present and contain a valid unix timestamp. It MUST be after the current time. 9. The difference between the `exp` and `iat` fields MUST be equal or less than 5 seconds. 10. The `jti` field MUST be present and contain a string that is unique for each access token request. ### 4.3 JSON format requirements 1. The assertion MUST be a valid JSON object according to §4.10 the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. -2. The proof of the VP MUST be a valid [JSONWebSignature2020] object. -3. The `challenge` field of the JSON object MUST be a string that is unique for each token request. -4. The `domain` field of the JSON object MUST be a DID under control of the Authorization Server. -5. The `verificationMethod` field of the Proof MUST be a DID URL. -6. The `verificationMethod` field of the proof MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. -7. The `created` field of the proof MUST be present and contain a valid timestamp. It MUST be before the current time. -8. The `expires` field of the proof MUST be present and contain a valid timestamp. It MUST be after the current time. -9. The difference between the `expires` and `created` fields MUST be equal or less than 5 seconds. +2. The proof of the VP MUST be a valid [JSONWebSignature2020] object. Additional requirements for the proof object: + 1. The `challenge` field MUST be a string that is unique for each token request. + 2. The `domain` field MUST be a DID under control of the Authorization Server. + 3. The `verificationMethod` field MUST be a DID URL. + 4. The `verificationMethod` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. + 5. The `created` field MUST be present and contain a valid ISO8601 formatted date string. It MUST be before the current time. + 6. The `expires` field MUST be present and contain a valid ISO8601 formatted date string. It MUST be after the current time. + 7. The difference between the `expires` and `created` fields MUST be equal or less than 5 seconds. ### 4.4 Preventing Token Replay @@ -148,7 +148,8 @@ In addition to the error response defined in OAuth 2.0 [RFC6749], the Authorizat * `invalid_verifiable_presentation`: The VP is invalid. This error code is used when the signature is incorrect or when a required field is missing. * `invalid_presentation_submission`: The Presentation Submission is invalid. This error code is used when the Presentation Submission is not an answer to the Presentation Definition that corresponds with the requested scope. -* `invalid_verifiable_credentials`: The submitted Verifiable Credentials do not meet the requirements. This error code is used when the Verifiable Credentials aren't corresponding to the Presentation Definition or when the Verifiable Credentials are expired, not trusted or invalid. + +An `invalid_request` is returned for any submitted Verifiable Credentials that do not meet the requirements, when the Verifiable Credentials aren't corresponding to the Presentation Definition or when the Verifiable Credentials are expired, not trusted or invalid. It is also used when the Verifiable Credentials are not issued to the signer of the Verifiable Presentation. ## 5. Presentation Definition endpoint @@ -171,13 +172,14 @@ The following example shows a request to the Presentation Definition endpoint: The Authorization Server MAY support an access token introspection endpoint as defined in OAuth 2.0 [RFC7662]. The introspection endpoint SHOULD map the fields as follows: +* `active`: If the access token is valid. * `iss`: The issuer of the access token (DID). * `sub`: The subject of the access token (DID), this is the resource owner. Usually the same as the `iss` field. * `client_id`: The client (DID) that requested the access token. * `exp`: The expiration time of the access token. * `iat`: The time the access token was issued. * `scope`: The granted scope. -* `vcs`: The Verifiable Credentials that were used to request the access token using the same encoding as used in the access token request. +* `vps`: The Verifiable Presentations that were used to request the access token using the same encoding as used in the access token request. ## 7. Security Considerations @@ -206,7 +208,7 @@ Privacy-sensitive data in the scope parameter should be avoided. * [VC-DATA-MODEL] M. Sporny, D. Longley, D. Chadwick, "Verifiable Credentials Data Model 1.1", W3C Recommendation, 3 March 2022, . * [PE] D. Buchner, B. Zundel, M. Riedel, K.H. Duffy, "Presentation Exchange 2.0.0", 12 September 2023, . * [JSONWebSignature2020] O. Steel, M. Prorock, C.E. Lehner, "JSON Web Signature 2020", W3C Community Group Report, 21 July 2022, . -* [OIDC4VP] O. Terbu, T. Lodderstedt, K. Yasuda, T. Looker, "OpenID for Verifiable Presentations Draft 18", OpenID connect working group, 21 April 2023, . +* [OpenID4VP] O. Terbu, T. Lodderstedt, K. Yasuda, T. Looker, "OpenID for Verifiable Presentations Draft 18", OpenID connect working group, 21 April 2023, . * [RFC8414] M. Jones, N. Sakimura, J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, June 2018, . * [RFC7662] J. Richer, "OAuth 2.0 Token Introspection", RFC 7662, October 2015, . * [DID] M. Sporny, D. Longley, M. Sabadello, D. Reed, O. Steele, C. Allen, "Decentralized Identifiers (DIDs) v1.0", W3C Recommendation, 19 July 2022, . \ No newline at end of file From 3186b22e7f73dcff18539b79d39656440f3f7da7 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Wed, 8 Nov 2023 08:45:58 +0100 Subject: [PATCH 21/28] PR feedback --- rfc/rfc021-vp_token-grant-type.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 14b3109..ff90397 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -129,7 +129,7 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 1. The `challenge` field MUST be a string that is unique for each token request. 2. The `domain` field MUST be a DID under control of the Authorization Server. 3. The `verificationMethod` field MUST be a DID URL. - 4. The `verificationMethod` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. + 4. The id part of the DID in the `verificationMethod` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. 5. The `created` field MUST be present and contain a valid ISO8601 formatted date string. It MUST be before the current time. 6. The `expires` field MUST be present and contain a valid ISO8601 formatted date string. It MUST be after the current time. 7. The difference between the `expires` and `created` fields MUST be equal or less than 5 seconds. From 39ee82dacd6e142b9786ef02e16571a01c9ca718 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Tue, 14 Nov 2023 16:06:04 +0100 Subject: [PATCH 22/28] added presentation_submission to introspectin --- rfc/rfc021-vp_token-grant-type.md | 1 + 1 file changed, 1 insertion(+) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index ff90397..6d7d252 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -180,6 +180,7 @@ The introspection endpoint SHOULD map the fields as follows: * `iat`: The time the access token was issued. * `scope`: The granted scope. * `vps`: The Verifiable Presentations that were used to request the access token using the same encoding as used in the access token request. +* `presentation_submission`: The Presentation Submission that was used to request the access token. ## 7. Security Considerations From c0b86395d462b4ee745f02fd337251efec86c8ab Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Thu, 16 Nov 2023 08:54:42 +0100 Subject: [PATCH 23/28] fields as fields --- rfc/rfc021-vp_token-grant-type.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 6d7d252..4bfae1a 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -61,14 +61,14 @@ This section defines specific parameters and treatments of those parameters for To use a VP as an authorization grant, the client uses an access token request as defined in Section 4 of the OAuth Assertion Framework [RFC7521] with the following specific parameter values and encodings. -The value of the "grant_type" is "vp_token-bearer". +The value of the `grant_type` is `vp_token-bearer`. The value of the "assertion" parameter MUST contain a Verifiable Presentation. The Verifiable Presentation MUST be encoded as either: * The Verifiable Presentation is encoded as JSON using the application/x-www-form-urlencoded content type. * The Verifiable Presentation is encoded as JWT according to section §6.3.1 of the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. -The "scope" parameter MUST be used, as defined in the OAuth Assertion Framework [RFC6749], to indicate the requested scope. +The `scope` parameter MUST be used, as defined in the OAuth Assertion Framework [RFC6749], to indicate the requested scope. The scope parameter determines the set of credentials the Authorization Server expects. The "presentation_submission" parameter MUST be used, as defined in Presentation Exchange [PE], to indicate how the VP matches the requested Verifiable Credentials. From 8af6a9632663004830f5c45499262aae9089d442 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Mon, 20 Nov 2023 14:00:38 +0100 Subject: [PATCH 24/28] PR feedback --- rfc/rfc021-vp_token-grant-type.md | 57 ++++++++++++++++--------------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 4bfae1a..3e5ffa5 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -24,9 +24,9 @@ This document is released under the [Attribution-ShareAlike 4.0 International \( ## 1. Introduction -A Verifiable Presentation [VP] is an encoding that enables identity and security information based on Verifiable Credentials to be shared across security domains. -A security token is generally issued by an Authorization Server and consumed by a client that relies on its content to make authorization decisions. -In the case of Verifiable Credentials, the presentation is self-signed by the holder using a wallet. +A Verifiable Presentation (VP) [VP] is an encoding that enables identity and security information based on Verifiable Credentials (VC) to be shared across security domains. +A security token is generally issued by an Authorization Server and consumed by a client that relies on its content to make authorization decisions. +A Verifiable Presentation can be used as a security token. When used as a security token, the wallet of the holder assumes the role of the Authorization Server. The OAuth 2.0 Authorization Framework [RFC6749] provides a method for making authenticated HTTP requests to a resource using an access token. Access tokens are issued to third-party clients by an Authorization Server (AS) with the (sometimes implicit) approval of the resource owner. @@ -43,7 +43,7 @@ The holder will need to know which Verifiable Credentials are required to access The Authorization Server provides this information in the form of a Presentation Definition [PE]. The complete flow consists of the following steps: -1. The client requests a Presentation Definition from the Authorization Server based on a scope. +1. The client requests a Presentation Definition from the Authorization Server based on an OAuth scope. 2. The client creates a Verifiable Presentation and a Presentation Submission that describes how the VP fulfills the requirements of the Presentation Definition. 3. The client requests an access token from the Authorization Server using the Verifiable Presentation as an authorization grant. 4. The Authorization Server validates the Verifiable Presentation and Presentation Submission. @@ -63,15 +63,15 @@ To use a VP as an authorization grant, the client uses an access token request a The value of the `grant_type` is `vp_token-bearer`. -The value of the "assertion" parameter MUST contain a Verifiable Presentation. The Verifiable Presentation MUST be encoded as either: +The value of the `assertion` parameter MUST contain a Verifiable Presentation. The Verifiable Presentation MUST be encoded as either: -* The Verifiable Presentation is encoded as JSON using the application/x-www-form-urlencoded content type. -* The Verifiable Presentation is encoded as JWT according to section §6.3.1 of the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. +* JSON object using the application/x-www-form-urlencoded content type. +* JWT according to section §6.3.1 of the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. The `scope` parameter MUST be used, as defined in the OAuth Assertion Framework [RFC6749], to indicate the requested scope. The scope parameter determines the set of credentials the Authorization Server expects. -The "presentation_submission" parameter MUST be used, as defined in Presentation Exchange [PE], to indicate how the VP matches the requested Verifiable Credentials. +The `presentation_submission` parameter MUST be used, as defined in Presentation Exchange [PE], to indicate how the VP matches the requested Verifiable Credentials. The Presentation Submission MUST be in JSON format, URL encoded. The following example demonstrates an access token request with a VP as an authorization grant (with extra line breaks for display purposes only): @@ -84,28 +84,26 @@ The following example demonstrates an access token request with a VP as an autho &assertion=eyJhbGciOiJFUzI1NiIsImtpZCI6IjE2In0. eyJpc3Mi[...omitted for brevity...]. J9l-ZhwP[...omitted for brevity...] - &presentation_submission= {..} + &presentation_submission=%7B...omitted for brevity...%7D &scope=a_scope ## 3.1 Assertion Encoding The assertion parameter can either be encoded in JSON or JWT. The Authorization Server determines the encoding by adding the correct parameters to the Authorization Server metadata [RFC8414]]. -The following parameter MUST be added: - -* `vp_formats`: An object defining the formats and proof types of Verifiable Presentations and Verifiable Credentials that a Verifier supports as stated by §9 of the OpenID for Verifiable Presentations specification [OpenID4VP]. +The `vp_formats` parameter MUST be added. It MUST contain an object defining the formats and proof types of Verifiable Presentations and Verifiable Credentials that a Verifier supports as stated by §9 of the OpenID for Verifiable Presentations specification [OpenID4VP]. ## 4. JWT Format and Processing Requirements In order to issue an access token response as described in OAuth 2.0 [RFC6749], the Authorization Server MUST validate the VP. The validation requirements are split into three paragraphs. The first paragraph describes the requirements that apply to all VP's. -The second paragraph describes the requirements that apply to JWT encoded VP's. The third paragraph describes the requirements that apply to JSON encoded VP's. +The second paragraph describes the requirements that apply to JWT encoded VP's. The third paragraph describes the requirements that apply to JSON-LD encoded VP's. ### 4.1 General processing requirements 1. The Authorization Server MUST validate the Presentation Submission according to section 6 of the Presentation Exchange [PE] specification. 2. The Authorization Server MUST validate the VP and Presentation Submission according to section 6.1 of the Presentation Exchange [PE] specification. -3. The Presentation Submission MUST be an answer to the Presentation Definition that corresponds with the requested scope. +3. The Presentation Submission MUST fulfill the Presentation Definition that corresponds with the requested scope. How an Authorization Server determines the Presentation Definition based on scope is out of scope of this specification. 4. A clock skew of no more than 5 seconds MAY be applied when validating the Verifiable Presentation. @@ -117,26 +115,26 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 4. The `kid` header MUST be a DID URL and MUST resolve to a verificationMethod in the DID Document. The DID part of the DID URL MUST match the `iss` field. 5. The `sub` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. 6. The `aud` field MUST match the DID of the Authorization Server. -7. The `iat` field MUST be present and contain a valid unix timestamp. It MUST be before the current time. -8. The `exp` field MUST be present and contain a valid unix timestamp. It MUST be after the current time. +7. The `iat` field MUST be present and contain a valid unix timestamp. It MUST be before the the current time (time at which the JWT is processed). +8. The `exp` field MUST be present and contain a valid unix timestamp. It MUST be after the current time (time at which the JWT is processed). 9. The difference between the `exp` and `iat` fields MUST be equal or less than 5 seconds. 10. The `jti` field MUST be present and contain a string that is unique for each access token request. -### 4.3 JSON format requirements +### 4.3 JSON-LD format requirements 1. The assertion MUST be a valid JSON object according to §4.10 the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. 2. The proof of the VP MUST be a valid [JSONWebSignature2020] object. Additional requirements for the proof object: 1. The `challenge` field MUST be a string that is unique for each token request. 2. The `domain` field MUST be a DID under control of the Authorization Server. 3. The `verificationMethod` field MUST be a DID URL. - 4. The id part of the DID in the `verificationMethod` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. - 5. The `created` field MUST be present and contain a valid ISO8601 formatted date string. It MUST be before the current time. - 6. The `expires` field MUST be present and contain a valid ISO8601 formatted date string. It MUST be after the current time. + 4. The ID part of the DID in the `verificationMethod` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. + 5. The `created` field MUST be present and contain a valid ISO8601 formatted date string. It MUST be before the current time (time at which the assertion is processed). + 6. The `expires` field MUST be present and contain a valid ISO8601 formatted date string. It MUST be after the current time (time at which the assertion is processed). 7. The difference between the `expires` and `created` fields MUST be equal or less than 5 seconds. ### 4.4 Preventing Token Replay -The Authorization Server MUST reject any request that uses the unique value (`jti` or `challenge`) that has been used before. +The Authorization Server MUST reject any request that uses the a value for `jti` (JWT proofs) or `challenge` (JSON Web Proofs) that has been used before. This approach has been chosen over the `nonce` field because there's no initial request to get a nonce from the Authorization Server. The Authorization Server MUST store the unique value for 10 seconds and MUST reject any request that uses a unique value that has been used before. The 10 seconds is based on the 5-second clock skew and the 5-second maximum difference between the expires and issued fields. @@ -144,13 +142,16 @@ The 10 seconds is based on the 5-second clock skew and the 5-second maximum diff ### 4.5 Error Response If the Authorization Server determines that the VP is invalid, the Authorization Server MUST return an error response as defined in OAuth 2.0 [RFC6749]. -In addition to the error response defined in OAuth 2.0 [RFC6749], the Authorization Server MUST return a HTTP 400 (Bad Request) and use the following error codes when the VP is invalid: - -* `invalid_verifiable_presentation`: The VP is invalid. This error code is used when the signature is incorrect or when a required field is missing. -* `invalid_presentation_submission`: The Presentation Submission is invalid. This error code is used when the Presentation Submission is not an answer to the Presentation Definition that corresponds with the requested scope. - -An `invalid_request` is returned for any submitted Verifiable Credentials that do not meet the requirements, when the Verifiable Credentials aren't corresponding to the Presentation Definition or when the Verifiable Credentials are expired, not trusted or invalid. -It is also used when the Verifiable Credentials are not issued to the signer of the Verifiable Presentation. +This RFC reuses the `invalid_request` error code for all errors related to the VP. +The Authorization Server SHOULD include a description in the error response. +Errors that could occur are: + +- The signature is incorrect. +- A required field is missing. +- The Presentation Submission is not an answer to the Presentation Definition that corresponds with the requested scope. +- The submitted Verifiable Credentials do not meet the requirements of the Presentation Definition. +- The Verifiable Credentials are expired, not trusted or invalid. +- The Verifiable Credentials are not issued to the signer of the Verifiable Presentation. ## 5. Presentation Definition endpoint From 38a97c8e78dc77f8c759b8952d66e9623d69f9ea Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Thu, 23 Nov 2023 10:53:30 +0100 Subject: [PATCH 25/28] redefine assertion param --- rfc/rfc021-vp_token-grant-type.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 3e5ffa5..badedec 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -63,10 +63,7 @@ To use a VP as an authorization grant, the client uses an access token request a The value of the `grant_type` is `vp_token-bearer`. -The value of the `assertion` parameter MUST contain a Verifiable Presentation. The Verifiable Presentation MUST be encoded as either: - -* JSON object using the application/x-www-form-urlencoded content type. -* JWT according to section §6.3.1 of the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. +The `assertion` parameter MUST follow the encoding requirements of the `vp_token` as defined in the OpenID for Verifiable Presentations specification [OpenID4VP]. The `scope` parameter MUST be used, as defined in the OAuth Assertion Framework [RFC6749], to indicate the requested scope. The scope parameter determines the set of credentials the Authorization Server expects. From 67c6ae17637de41e45050f88091ac6507abf7eb9 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Mon, 27 Nov 2023 13:19:33 +0100 Subject: [PATCH 26/28] PR feedback --- rfc/rfc021-vp_token-grant-type.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index badedec..ce90d66 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -112,17 +112,17 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 4. The `kid` header MUST be a DID URL and MUST resolve to a verificationMethod in the DID Document. The DID part of the DID URL MUST match the `iss` field. 5. The `sub` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. 6. The `aud` field MUST match the DID of the Authorization Server. -7. The `iat` field MUST be present and contain a valid unix timestamp. It MUST be before the the current time (time at which the JWT is processed). +7. The `nbf` field MUST be present and contain a valid unix timestamp. It MUST be before the the current time (time at which the JWT is processed). 8. The `exp` field MUST be present and contain a valid unix timestamp. It MUST be after the current time (time at which the JWT is processed). -9. The difference between the `exp` and `iat` fields MUST be equal or less than 5 seconds. +9. The difference between the `exp` and `nbf` fields MUST be equal or less than 5 seconds. 10. The `jti` field MUST be present and contain a string that is unique for each access token request. ### 4.3 JSON-LD format requirements 1. The assertion MUST be a valid JSON object according to §4.10 the Verifiable Credentials Data Model 1.1 [VC-DATA-MODEL]. 2. The proof of the VP MUST be a valid [JSONWebSignature2020] object. Additional requirements for the proof object: - 1. The `challenge` field MUST be a string that is unique for each token request. - 2. The `domain` field MUST be a DID under control of the Authorization Server. + 1. The `nonce` field MUST be a string that is unique for each token request. + 2. The `domain` field MUST match the DID of the Authorization Server. 3. The `verificationMethod` field MUST be a DID URL. 4. The ID part of the DID in the `verificationMethod` field MUST match the `credentialSubject.id` field from all the Verifiable Credentials that are used to request the access token. 5. The `created` field MUST be present and contain a valid ISO8601 formatted date string. It MUST be before the current time (time at which the assertion is processed). @@ -131,7 +131,7 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. ### 4.4 Preventing Token Replay -The Authorization Server MUST reject any request that uses the a value for `jti` (JWT proofs) or `challenge` (JSON Web Proofs) that has been used before. +The Authorization Server MUST reject any request that uses the a value for `jti` (JWT proofs) or `nonce` (JSON Web Proofs) that has been used before. This approach has been chosen over the `nonce` field because there's no initial request to get a nonce from the Authorization Server. The Authorization Server MUST store the unique value for 10 seconds and MUST reject any request that uses a unique value that has been used before. The 10 seconds is based on the 5-second clock skew and the 5-second maximum difference between the expires and issued fields. @@ -175,14 +175,14 @@ The introspection endpoint SHOULD map the fields as follows: * `sub`: The subject of the access token (DID), this is the resource owner. Usually the same as the `iss` field. * `client_id`: The client (DID) that requested the access token. * `exp`: The expiration time of the access token. -* `iat`: The time the access token was issued. +* `nbf`: The time the access token was issued. * `scope`: The granted scope. * `vps`: The Verifiable Presentations that were used to request the access token using the same encoding as used in the access token request. * `presentation_submission`: The Presentation Submission that was used to request the access token. ## 7. Security Considerations -The jti/challenge (further called nonce) is used to prevent replay attacks. The nonce is a random string that is generated by the client. +The jti/nonce (further called nonce) is used to prevent replay attacks. The nonce is a random string that is generated by the client. The nonce is included in the signed data. The Authorization Server MUST reject any request that uses a nonce that has been used before. All endpoints MUST be protected by TLS, version 1.2 as a minimum. From 062a5e74ae75ff8e440c1e8f3d32a14894c86f38 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Tue, 28 Nov 2023 09:46:59 +0100 Subject: [PATCH 27/28] jti to nonce --- rfc/rfc021-vp_token-grant-type.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index ce90d66..7be4304 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -115,7 +115,7 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. 7. The `nbf` field MUST be present and contain a valid unix timestamp. It MUST be before the the current time (time at which the JWT is processed). 8. The `exp` field MUST be present and contain a valid unix timestamp. It MUST be after the current time (time at which the JWT is processed). 9. The difference between the `exp` and `nbf` fields MUST be equal or less than 5 seconds. -10. The `jti` field MUST be present and contain a string that is unique for each access token request. +10. The `nonce` field MUST be present and contain a string that is unique for each access token request. ### 4.3 JSON-LD format requirements @@ -131,8 +131,8 @@ The second paragraph describes the requirements that apply to JWT encoded VP's. ### 4.4 Preventing Token Replay -The Authorization Server MUST reject any request that uses the a value for `jti` (JWT proofs) or `nonce` (JSON Web Proofs) that has been used before. -This approach has been chosen over the `nonce` field because there's no initial request to get a nonce from the Authorization Server. +The Authorization Server MUST reject any request that uses a `nonce` that has been used before. +The `nonce` field in this case is determined by the client because there's no initial request to get a nonce from the Authorization Server. The Authorization Server MUST store the unique value for 10 seconds and MUST reject any request that uses a unique value that has been used before. The 10 seconds is based on the 5-second clock skew and the 5-second maximum difference between the expires and issued fields. From 221c386412037baac21839f37bc66b069b54d4b1 Mon Sep 17 00:00:00 2001 From: Wout Slakhorst Date: Wed, 29 Nov 2023 14:59:07 +0100 Subject: [PATCH 28/28] Update rfc/rfc021-vp_token-grant-type.md Co-authored-by: Gerard Snaauw <33763579+gerardsn@users.noreply.github.com> --- rfc/rfc021-vp_token-grant-type.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfc/rfc021-vp_token-grant-type.md b/rfc/rfc021-vp_token-grant-type.md index 7be4304..32850bb 100644 --- a/rfc/rfc021-vp_token-grant-type.md +++ b/rfc/rfc021-vp_token-grant-type.md @@ -182,7 +182,7 @@ The introspection endpoint SHOULD map the fields as follows: ## 7. Security Considerations -The jti/nonce (further called nonce) is used to prevent replay attacks. The nonce is a random string that is generated by the client. +The nonce is used to prevent replay attacks. The nonce is a random string that is generated by the client. The nonce is included in the signed data. The Authorization Server MUST reject any request that uses a nonce that has been used before. All endpoints MUST be protected by TLS, version 1.2 as a minimum.