add RFC021 vp_token-brearer grant type for oauth2 #265

woutslakhorst · 2023-09-12T07:53:50Z

It specifies a new grant type that can be used to get an access_token.

RFC relations.

rfc/rfc021-vp_token-grant-type.md

gerardsn

first pass

rfc/rfc021-vp_token-grant-type.md

gerardsn

round 2

rfc/rfc021-vp_token-grant-type.md

reinkrul · 2023-10-06T06:43:51Z

I think it's missing error codes (default and/or new ones?), e.g. when not all VCs have a, or the same, credentialSubject.id

woutslakhorst · 2023-10-09T07:08:59Z

I think it's missing error codes (default and/or new ones?), e.g. when not all VCs have a, or the same, credentialSubject.id

Added error codes

rfc/rfc021-vp_token-grant-type.md

gerardsn

good enough for a draft version

gerardsn · 2023-11-01T17:13:52Z

rfc/rfc021-vp_token-grant-type.md

+* `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.


add active: (required per rfc7662) boolean indicating if the token is valid (syntax, iat < now > exp, valid signature, not revoked, etc.).

vcs should be replaced by the PDP map and friends as discussed, see nuts-foundation/nuts-node#2567. I'm fine updating this at a later point though.

gerardsn · 2023-11-01T17:22:12Z

rfc/rfc021-vp_token-grant-type.md

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


Does the grant always contain a single VP (makes sense for s2s flow) or can it contain a VP array as in OpenID4VP?

Theoretically a server could combine multiple wallets... (like vendor and tenant). Let's start with 1 and see how far we get.

rfc/rfc021-vp_token-grant-type.md

gerardsn · 2023-11-01T17:37:06Z

rfc/rfc021-vp_token-grant-type.md

+
+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 single Presentation Definition that corresponds with the requested scope.


OAuth generally allows the AS to return an answer for a smaller scope than requested. Probably doesn't make sense for our use cases, but might if we want publish outside our domain. In that case the endpoint also needs to return the scope the PD is for.

Let's see if we get that feedback from the rest of the world, since it would change the return value of the API.

gerardsn · 2023-11-01T17:38:19Z

rfc/rfc021-vp_token-grant-type.md

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


point to standard OAuth definition for scope?

There it's mostly used as form encoded value and not as query param?

rfc/rfc021-vp_token-grant-type.md

reinkrul · 2023-11-02T06:00:21Z

rfc/rfc021-vp_token-grant-type.md


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


this section is not really add anything useful?

Entire chapter 6 or specific fields?

May be useful after all, since we don't have a separate introspection RFC, and it adds some claims specific for this RFC (regarding the input descriptors)

reinkrul · 2023-11-06T05:47:54Z

rfc/rfc021-vp_token-grant-type.md

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


do we need to support JSON-LD?

rfc/rfc021-vp_token-grant-type.md

reinkrul · 2023-11-06T05:54:28Z

rfc/rfc021-vp_token-grant-type.md

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


I think we discussed adding fields specified by input descriptors?

I'd prefer only to include credentials in the response, that were input for the access token, meaning only those matched by the presentation definition. Why do you think we need the whole VP?

Adding fields later on is a lot easier than removing them (which is breaking)

You shouldn't need any of them if all is done correctly. If we're including any data that was used as input then best to include the raw data which are the vps. The vps will also tell you which wallet signed which vcs. Only including vcs won't give you that info. But we can remove it from the spec and just add them to the implementation?

If the vps are always the vp_token (which is true here), then I think we also need to return the presentation_submission to interpret the contents of the vps.

That's also fine. Might want to choose a style short (acronyms), or long form, though

rfc/rfc021-vp_token-grant-type.md

reinkrul · 2023-11-06T05:56:37Z

rfc/rfc021-vp_token-grant-type.md


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


May be useful after all, since we don't have a separate introspection RFC, and it adds some claims specific for this RFC (regarding the input descriptors)

rfc/rfc021-vp_token-grant-type.md

reinkrul · 2023-11-20T10:14:39Z

rfc/rfc021-vp_token-grant-type.md

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


client or relying party? Client is the software instance, relying party the entity using the software instance to communicate with the AS

These point use client and AS as the actual systems doing the requests.

rfc/rfc021-vp_token-grant-type.md

reinkrul · 2023-11-20T10:28:31Z

rfc/rfc021-vp_token-grant-type.md

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


should it be "invalid assertion"? (as that reflects the parameter name)

removed all custom errors since it creates too much confusion amongst reviewers.

reinkrul · 2023-11-20T10:31:49Z

rfc/rfc021-vp_token-grant-type.md

+* `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. 


Kinda ambiguous with "invalid_verifiable_presentation"; if the contained credentials are invalid, it could also be seen as "invalid_verifiable_presentation"?

Also, I think there (ideally) should not be any other "trust" anchors than the one specified by the Presentation Definition. Otherwise, RP and AS still have to agree on a set of trust anchors outside of this specification.

We currently decided on putting trust anchors in the PDs, that does not mean that this is mandatory through this RFC. 'Trust' is therefore still required, but undefined how it's solved.

reinkrul · 2023-11-20T10:33:13Z

rfc/rfc021-vp_token-grant-type.md

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


but it only needs to store them for as long as the presentation is valid

implementation opzitmization.

rfc/rfc021-vp_token-grant-type.md

reinkrul

Just @gerardsn 's comment on nbf/iat left, i.m.o.

rfc/rfc021-vp_token-grant-type.md

gerardsn

last one

gerardsn · 2023-11-27T17:10:03Z

rfc/rfc021-vp_token-grant-type.md

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


the vc-data-model maps jti to the VC/VP id value. A value should not have 2 meanings, so we should use nonce here too. We're then using nonce for replay prevention in both data formats which is a nice bonus I'd say.

The security considerations section needs some rewording if this is added

gerardsn · 2023-11-27T17:12:53Z

rfc/rfc021-vp_token-grant-type.md

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


After seeing more specs the nonce value (in JWTs) can be issued by both AS and RP

Suggested change

This approach has been chosen over the `nonce` field because there's no initial request to get a nonce from the Authorization Server.

rfc/rfc021-vp_token-grant-type.md

Co-authored-by: Gerard Snaauw <[email protected]>

add RFC021 vp_token-brearer grant type for oauth2

3055386

woutslakhorst requested review from reinkrul and gerardsn September 12, 2023 07:53

update vp_formats format

ac52094

woutslakhorst mentioned this pull request Sep 13, 2023

Implement server-to-server /token endpoint where vp_token is posted nuts-foundation/nuts-node#2418

Closed

11 tasks

reinkrul requested changes Sep 13, 2023

View reviewed changes

fixed technical comments from PR

ae71774

gerardsn requested changes Sep 14, 2023

View reviewed changes

woutslakhorst added 3 commits September 15, 2023 09:59

some fixes

ac552e2

fix PE version

41918d8

stuff

d6dbbf8

gerardsn reviewed Sep 19, 2023

View reviewed changes

rfc/rfc021-vp_token-grant-type.md Outdated Show resolved Hide resolved

woutslakhorst added 2 commits September 20, 2023 07:57

add scope param to example

4995470

PR feedback

fdb9f2c

woutslakhorst requested review from reinkrul and gerardsn September 20, 2023 11:49

gerardsn requested changes Sep 22, 2023

View reviewed changes

reinkrul mentioned this pull request Sep 25, 2023

OAuth2 Presentation Exchange 4 Server-to-Server nuts-foundation/nuts-node#2399

Closed

PR feedback

a4d5481

reinkrul reviewed Sep 27, 2023

View reviewed changes

rfc/rfc021-vp_token-grant-type.md Outdated Show resolved Hide resolved

reinkrul requested changes Sep 28, 2023

View reviewed changes

rfc/rfc021-vp_token-grant-type.md Outdated Show resolved Hide resolved

PR feedback

0d04aa2

woutslakhorst requested review from gerardsn and reinkrul October 2, 2023 08:16

changed use of jti/challenge over nonce and more strict scope usage

cc3d2e4

added error codes

9c39be2

woutslakhorst force-pushed the feature/s2s_bearer_token branch from c0ad69f to 9c39be2 Compare October 9, 2023 07:08

reinkrul requested changes Oct 9, 2023

View reviewed changes

gerardsn reviewed Nov 1, 2023

View reviewed changes

reinkrul reviewed Nov 2, 2023

View reviewed changes

woutslakhorst requested review from gerardsn and reinkrul November 3, 2023 11:04

PR feedback

b82d74f

reinkrul requested changes Nov 6, 2023

View reviewed changes

woutslakhorst added 2 commits November 8, 2023 08:45

PR feedback

3186b22

added presentation_submission to introspectin

39ee82d

woutslakhorst requested a review from reinkrul November 14, 2023 15:06

reinkrul reviewed Nov 15, 2023

View reviewed changes

rfc/rfc021-vp_token-grant-type.md Outdated Show resolved Hide resolved

fields as fields

c0b8639

woutslakhorst requested a review from reinkrul November 16, 2023 07:54

gerardsn approved these changes Nov 17, 2023

View reviewed changes

reinkrul requested changes Nov 20, 2023

View reviewed changes

PR feedback

8af6a96

woutslakhorst requested a review from reinkrul November 20, 2023 13:00

redefine assertion param

38a97c8

gerardsn requested changes Nov 24, 2023

View reviewed changes

rfc/rfc021-vp_token-grant-type.md Outdated Show resolved Hide resolved

reinkrul approved these changes Nov 25, 2023

View reviewed changes

reinkrul reviewed Nov 27, 2023

View reviewed changes

rfc/rfc021-vp_token-grant-type.md Outdated Show resolved Hide resolved

reinkrul reviewed Nov 27, 2023

View reviewed changes

rfc/rfc021-vp_token-grant-type.md Outdated Show resolved Hide resolved

PR feedback

67c6ae1

woutslakhorst requested a review from gerardsn November 27, 2023 12:19

gerardsn requested changes Nov 27, 2023

View reviewed changes

reinkrul approved these changes Nov 27, 2023

View reviewed changes

jti to nonce

062a5e7

gerardsn approved these changes Nov 28, 2023

View reviewed changes

rfc/rfc021-vp_token-grant-type.md Outdated Show resolved Hide resolved

Update rfc/rfc021-vp_token-grant-type.md

221c386

Co-authored-by: Gerard Snaauw <[email protected]>

woutslakhorst merged commit 469d6ee into master Nov 29, 2023

woutslakhorst deleted the feature/s2s_bearer_token branch November 29, 2023 13:59

		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.

add RFC021 vp_token-brearer grant type for oauth2 #265

add RFC021 vp_token-brearer grant type for oauth2 #265

Conversation

woutslakhorst commented Sep 12, 2023

gerardsn left a comment

Choose a reason for hiding this comment

gerardsn left a comment

Choose a reason for hiding this comment

reinkrul commented Oct 6, 2023

woutslakhorst commented Oct 9, 2023

gerardsn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

reinkrul Nov 10, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

reinkrul left a comment

Choose a reason for hiding this comment

gerardsn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

reinkrul Nov 10, 2023 •

edited

Loading