search

ConsumerDataStandardsAustralia / standards-maintenance

This repository houses the interactions, consultations and work management to support the maintenance of baselined components of the Consumer Data Right API Standards and Information Security profile.
41 stars 9 forks source link

Fix documentation defect for CDR Arrangement JWT method #503

Closed CDR-API-Stream closed 1 year ago

CDR-API-Stream commented 2 years ago

Description

A merge issue in v1.15.0 meant that the documentation for the CDR Arrangement Form Parameter method and CDR Arrangement JWT method were not correctly incorporated. The staged change as recommended in #426 included provisions for the CDR Arrangement JWT method for the Data Recipient hosted CDR Arrangement Revocation Endpoint.

Area Affected

CDR Arrangement Revocation End Point

Change Proposed

This change corrects the merge issue to correct the documentation as follows:

CDR Arrangement Form Parameter method

The request MUST include the following parameters using the application/x-www-form-urlencoded format in the HTTP request entity-body:

CDR Arrangement JWT method

The request MUST include the following parameters using the application/x-www-form-urlencoded format in the HTTP request entity-body:

CDR-API-Stream commented 2 years ago

This documentation fix will be targeted for v1.17.0 release. A staged change will be published this week. If there is any feedback in regards to this item we'd welcome feedback this week.

CDR-API-Stream commented 2 years ago

This change has been staged for review: https://github.com/ConsumerDataStandardsAustralia/standards-staging/compare/release/1.17.0...maintenance/503

perlboy commented 2 years ago

Just to be very clear here. The only thing required in the JWT signed payload is the cdr_arrangement_id? JWT specifies all other attributes as Optional which is the only Standards reference in this change so there is no requirement for iss, aud etc.

How is the JWT in the payload binded to the Holder and client assertion making the call? Does the JWT that is received via cdr_arrangement_jwt get verified implicitly from the details in the Bearer token?

It seems without more required fields in the posted payload that there is now a deeper binding between the Bearer token and the information being conveyed.

CDR-API-Stream commented 2 years ago

Hi @perlboy, the CDR Arrangement ID must include the parameters in accordance to the Self-Signed JWT Client Authentication section as they apply to Data Holders calling Data Recipients (specifically iss, sub, aud, jti, exp and iat (optional)). For clarity, the CDR Arrangement JWT Method section could be updated as follows:

The cdr_arrangement_jwt MUST be a newly signed JWT with the following parameters in accordance with [JWT]:

  • All parameters required by Data Holders calling Data Recipients using Self-Signed JWT Client Authentication.
  • cdr_arrangement_id: The ID of the arrangement that the client wants to revoke.

This would also include fixing the non-normative example to show the other required claims in the example.

Would this proposal better articulate the requirements, or do you have an alternative suggestion for expressing these requirements?

This change can be updated in the staged code change.

CDR-API-Stream commented 2 years ago

The staged change has been updated to reflect the above content: https://github.com/ConsumerDataStandardsAustralia/standards-staging/compare/release/1.17.0...maintenance/503

Note: the bullet point "All parameters required by Data Holders calling Data Recipients using Self-Signed JWT Client Authentication." has been modified to read "All parameters in accordance with Data Holders calling Data Recipients using Self-Signed JWT Client Authentication." because the referenced section includes optional parameters which may be included.