stdin

├── reviews ├── 2021-05 │ ├── analysis │ │ ├── analysis-fapi-draft06-and-final.md │ │ ├── docs │ │ │ ├── analysis-cds_admin-json-v1.10.0.html │ │ │ └── analysis-cds_full-json-v1.10.0.html │ │ ├── analysis-rfc2119-rfc8174-20210519.md │ │ ├── analysis-par-20210704.md │ │ ├── analysis-fapi-part2-20210621.md │ │ └── analysis-fapi-part1-20210614.md │ ├── raw │ │ ├── rfc2119.txt │ │ ├── rfc8174.txt │ │ ├── docs │ │ │ └── cds_admin.json │ │ └── draft-ietf-oauth-par-01.txt │ ├── README.md │ └── diff │ │ └── diff-rfc2119-rfc8174.txt └── README.md ├── .github └── ISSUE_TEMPLATE │ ├── question-or-clarification-request.md │ ├── a_standards-maintenance-backlog-item.md │ └── b_cx-guidelines-request.md └── README.md /reviews/2021-05/analysis/analysis-fapi-draft06-and-final.md: -------------------------------------------------------------------------------- 1 | # Overview 2 | 3 | # Changes 4 | 5 | ## FAPI Baseline 6 | 7 | ## FAPI Advanced 8 | 9 | # Implementation considerations 10 | 11 | * TBA 12 | 13 | # Recommendations 14 | 15 | * TBA 16 | 17 | # Transitioning the CDR ecosystem 18 | 19 | ## Step 1 20 | 21 | * TBA 22 | 23 | ## Step 2 24 | 25 | * TBA 26 | 27 | ## Step 3 28 | 29 | * TBA 30 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/question-or-clarification-request.md: -------------------------------------------------------------------------------- 1 | # PLEASE NOTE - Superseded request 2 | The Consumer Data Right Support Portal is the preferred way to search for answers, raise questions and request clarification of the standards. 3 | We kindly ask that you raise your questions or clarifications to either [email](mailto:support@cdr-support.zendesk.com) or via the [web form](https://cdr-support.zendesk.com/hc/en-us/requests/new) 4 | 5 | --- 6 | name: Question or clarification request 7 | about: Used to raise a question or request clarification of the standards 8 | title: "[Brief summary of question]" 9 | labels: query 10 | assignees: '' 11 | 12 | --- 13 | 14 | # Request For Clarification 15 | Brief description of the issue that is leading to the change being required 16 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/a_standards-maintenance-backlog-item.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Standards maintenance backlog item 3 | about: Create a new standards maintenance backlog item for consideration by the community 4 | title: "[Descriptive Issue Title]" 5 | labels: change request 6 | assignees: '' 7 | 8 | --- 9 | 10 | # Description 11 | Brief description of the issue that is leading to the change being required. 12 | 13 | # Intention and Value of Change 14 | Please include details on the intended benefit of the change and the value it brings to the requester and ecosystem participants. 15 | 16 | # Area Affected 17 | Describe the area of the standard that is proposed to be amended. This could be one or more API end points or a specific section of the information security profile. 18 | 19 | # Change Proposed 20 | A detailed description of the specific change (or options for change) proposed. The more specific the proposal the easier investigation and consultation on the issue will be. 21 | -------------------------------------------------------------------------------- /reviews/2021-05/analysis/docs/analysis-cds_admin-json-v1.10.0.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | stdin 8 | 9 | 10 |

11 |         "description": "Indicate that a critical update to the metadata for Accredited Data Recipients has been made and should be obtained",
12 |       "description": "Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between [x-min-v](#request-headers) and [x-v](#request-headers). If the value of [x-min-v](#request-headers) is equal to or higher than the value of [x-v](#request-headers) then the [x-min-v](#request-headers) header should be treated as absent. If all versions requested are not supported then the data holder should respond with a 406 Not Acceptable. See [HTTP Headers](#request-headers)",
13 |       "description": "Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between [x-min-v](#request-headers) and [x-v](#request-headers). If all versions requested are not supported then the data holder should respond with a 406 Not Acceptable.",
14 |

15 | 16 | 17 | -------------------------------------------------------------------------------- /reviews/2021-05/analysis/analysis-rfc2119-rfc8174-20210519.md: -------------------------------------------------------------------------------- 1 | # Overview 2 | 3 | * **Specification:** Key words for use in RFCs to Indicate Requirement Levels 4 | * **Baseline Version:** [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119) 5 | * **Target Version:** [RFC8174](https://datatracker.ietf.org/doc/html/rfc8174) 6 | 7 | This document summarises the changes between the RFC2119 on Requirements Level and the amendments made in RFC8174 and identifies the impacts to the Consumer Data Standards. 8 | 9 | Impact analysis is compared against v1.10.0 of the Consumer Data Standards. 10 | 11 | # Summary of key changes 12 | 13 | * RFC8174 clarifies that only keywords in UPPERCASE have the meaning of a requirement level keyword. Where the lowercase is used in documentation, it does not take on the meaning of a requirement level keyword. 14 | * It introduced the new keyword "NOT RECOMMENDED" 15 | 16 | # Analysis 17 | 18 | | Section | Change | Summary | 19 | | --- | --- | --- | 20 | | 2. Clarifying Capitalization of Key Words | Definition of a keyword | Use of keywords is only implied when the keyword is provided in UPPERCASE | 21 | | 2. Clarifying Capitalization of Key Words | "NOT RECOMMENDED" | "NOT RECOMMENDED" is explicitly defined as a synonym for "SHOULD NOT" | 22 | 23 | # Impact analysis to the Consumer Data Standards 24 | 25 | * Any intended use of a requirement level keyword needs to be UPPERCASE 26 | * Does not give rise to any breaking changes because the correct interpretation of RFC2119 is that lowercase usage of keywords is permitted 27 | 28 | # Recommendations 29 | 30 | * Adopt RFC8174 _in addition to_ RFC2119. Because RFC8174 is a clarification on best practice when applying RFC2119 both RFCs apply. 31 | * RFC8174 should be introduced as an informative reference. 32 | * All references to requirement level keywords that **are not** UPPERCASE must be reviewed in the Consumer Data Standards. Where a requirement level is implied, the word must be changed to UPPERCASE. Where the use of the word is not intended to imply a requirement level, a different word should be used to reduce possible ambiguity for implementers 33 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/b_cx-guidelines-request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: CX Guidelines request 3 | about: Create a request for CX Guidelines. This can be a request for new guidelines 4 | or a change request to existing guidelines. 5 | title: "[CX Guidelines | Descriptive Issue Title]" 6 | labels: change request, consumer experience, cx guideline 7 | assignees: CDR-CX-Stream 8 | 9 | --- 10 | 11 | 12 | # Description 13 | Briefly described the CX Guideline(s) being requested for development or revision. 14 | 15 | # Intention and Value of Change 16 | Please include details on the intended benefit of the change and the value it brings to the requester and ecosystem participants. 17 | 18 | # Area affected 19 | Specify the area(s) to be covered or revised. This should include specific CDR Rules, Data Standards, or CX Guidelines that relate to the request. 20 | 21 | # New item or change proposed 22 | Clear outline of the requirement, journey, or flow for which CX Guidelines are requested to cover or demonstrate. 23 | 24 | 25 | ----- 26 | :warning: **Disclaimer** :warning: 27 | The [CX Guidelines](https://cx.cds.gov.au/) provide optional implementation examples for key rules, standards, and best practice recommendations. 28 | 29 | They demonstrate key aspects of the consent model, but certain areas may be considered out of scope. This may include, for example, where the rules and/or standards are silent or non-prescriptive to provide CDR participants with flexibility or discretion according to their own systems or protocols. 30 | 31 | :heavy_exclamation_mark:The CX Guidelines span policy, rules, standards, and best practice, so requests will be considered on a case by case basis and timings may not fall within a Maintenance Iteration cycle. 32 | 33 | Importantly, the [CX Guidelines](https://cx.cds.gov.au/) are optional to follow, but the CDR rules require CDR participants to have regard to them. The [CX Standards](https://consumerdatastandardsaustralia.github.io/standards/#consumer-experience) differ in that they are binding data standards that must be followed. 34 | 35 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Consumer Data Right Standards - Maintenance 2 | 3 | This repository is used to contain discussions and contributions from the community of participants and other interested parties in the Australian [Consumer Data Right](https://www.cdr.gov.au/). Please refer to the [Standards repository](https://github.com/ConsumerDataStandardsAustralia/standards) for more information. 4 | 5 | See the Consumer Data Standards support portal article [Standards Maintenance](https://cdr-support.zendesk.com/hc/en-us/articles/900005585003) for details of the maintenance cycle. The details for the next maintenance iteration are below. 6 | 7 | ## Getting involved 8 | If you would like to participate in the Standards Maintenance fortnightly meetings and contribute to the discussion, send a request via email to contact@dsb.gov.au 9 | 10 | You can also sign up to our [mailing list](https://consumerdatastandards.us18.list-manage.com/subscribe?u=fb3bcb1ec5662d9767ab3c414&id=a4414b3906) to stay up to date on DSB News. 11 | 12 | The Agenda, Minutes and Actions for Maintenance Iterations are available on the [Meetings page](https://github.com/ConsumerDataStandardsAustralia/standards/wiki/MI%20meetings). 13 | 14 | 15 | ## Raising issues 16 | 17 | If you would like to propose an enhancement, fix or change to the Data Standards you can raise an issue on [this repository](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues). 18 | 19 | If you would like to suggest a documentation fix, you can post a comment on the holistic feedback issue created for each Maintenance Iteration. See [Getting involved](#getting-involved) above. 20 | 21 | If you would like to request clarification or ask a question you can search the [CDR Support Portal](https://cdr-support.zendesk.com/hc/en-us) for existing guidance or raise a query if you're unable to find an answer. 22 | 23 | ## Rules of engagement for this repository 24 | 25 | We're committed to undertaking conversations relating to the technical standards in the open. Questions or comments that participants might ask us via email or private message are likely to be questions or comments other participants have as well. Our answers will be of interest to everyone. There are likely to be experiences and lessons everybody working in this ecosystem can learn from. Having these conversations transparently helps us reduce duplication, resolve issues faster and keep everyone up to date with the conversation. 26 | 27 | We ask that all contributors to the Consumer Data Standards repositories comply with the [GitHub Community Forum Code of Conduct](https://help.github.com/articles/github-community-forum-code-of-conduct/) and DSB’s [Community Guidelines](https://cdr-support.zendesk.com/hc/en-us/articles/10222408124047-Consultation-meeting-information-and-community-guidelines). 28 | 29 | In addition, it would be appreciated if the following rules are adhered to when commenting or contributing: 30 | * Please provide a single, considered response to each proposal covering all feedback concerning the proposal. 31 | * For transparency, if you work at or are associated with an organisation with an interest in the standards, please indicate this in your response. 32 | * Please ensure you are aware of and compliant with any social media guidelines or internal processes for response set by your organisation before providing feedback. 33 | * The creation of new issues by contributors is encouraged in this repository. 34 | -------------------------------------------------------------------------------- /reviews/2021-05/raw/rfc2119.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Network Working Group S. Bradner 8 | Request for Comments: 2119 Harvard University 9 | BCP: 14 March 1997 10 | Category: Best Current Practice 11 | 12 | 13 | Key words for use in RFCs to Indicate Requirement Levels 14 | 15 | Status of this Memo 16 | 17 | This document specifies an Internet Best Current Practices for the 18 | Internet Community, and requests discussion and suggestions for 19 | improvements. Distribution of this memo is unlimited. 20 | 21 | Abstract 22 | 23 | In many standards track documents several words are used to signify 24 | the requirements in the specification. These words are often 25 | capitalized. This document defines these words as they should be 26 | interpreted in IETF documents. Authors who follow these guidelines 27 | should incorporate this phrase near the beginning of their document: 28 | 29 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 30 | NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 31 | "OPTIONAL" in this document are to be interpreted as described in 32 | RFC 2119. 33 | 34 | Note that the force of these words is modified by the requirement 35 | level of the document in which they are used. 36 | 37 | 1. MUST This word, or the terms "REQUIRED" or "SHALL", mean that the 38 | definition is an absolute requirement of the specification. 39 | 40 | 2. MUST NOT This phrase, or the phrase "SHALL NOT", mean that the 41 | definition is an absolute prohibition of the specification. 42 | 43 | 3. SHOULD This word, or the adjective "RECOMMENDED", mean that there 44 | may exist valid reasons in particular circumstances to ignore a 45 | particular item, but the full implications must be understood and 46 | carefully weighed before choosing a different course. 47 | 48 | 4. SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean that 49 | there may exist valid reasons in particular circumstances when the 50 | particular behavior is acceptable or even useful, but the full 51 | implications should be understood and the case carefully weighed 52 | before implementing any behavior described with this label. 53 | 54 | 55 | 56 | 57 | 58 | Bradner Best Current Practice [Page 1] 59 | 60 | RFC 2119 RFC Key Words March 1997 61 | 62 | 63 | 5. MAY This word, or the adjective "OPTIONAL", mean that an item is 64 | truly optional. One vendor may choose to include the item because a 65 | particular marketplace requires it or because the vendor feels that 66 | it enhances the product while another vendor may omit the same item. 67 | An implementation which does not include a particular option MUST be 68 | prepared to interoperate with another implementation which does 69 | include the option, though perhaps with reduced functionality. In the 70 | same vein an implementation which does include a particular option 71 | MUST be prepared to interoperate with another implementation which 72 | does not include the option (except, of course, for the feature the 73 | option provides.) 74 | 75 | 6. Guidance in the use of these Imperatives 76 | 77 | Imperatives of the type defined in this memo must be used with care 78 | and sparingly. In particular, they MUST only be used where it is 79 | actually required for interoperation or to limit behavior which has 80 | potential for causing harm (e.g., limiting retransmisssions) For 81 | example, they must not be used to try to impose a particular method 82 | on implementors where the method is not required for 83 | interoperability. 84 | 85 | 7. Security Considerations 86 | 87 | These terms are frequently used to specify behavior with security 88 | implications. The effects on security of not implementing a MUST or 89 | SHOULD, or doing something the specification says MUST NOT or SHOULD 90 | NOT be done may be very subtle. Document authors should take the time 91 | to elaborate the security implications of not following 92 | recommendations or requirements as most implementors will not have 93 | had the benefit of the experience and discussion that produced the 94 | specification. 95 | 96 | 8. Acknowledgments 97 | 98 | The definitions of these terms are an amalgam of definitions taken 99 | from a number of RFCs. In addition, suggestions have been 100 | incorporated from a number of people including Robert Ullmann, Thomas 101 | Narten, Neal McBurnett, and Robert Elz. 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | Bradner Best Current Practice [Page 2] 115 | 116 | RFC 2119 RFC Key Words March 1997 117 | 118 | 119 | 9. Author's Address 120 | 121 | Scott Bradner 122 | Harvard University 123 | 1350 Mass. Ave. 124 | Cambridge, MA 02138 125 | 126 | phone - +1 617 495 3864 127 | 128 | email - sob@harvard.edu 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | Bradner Best Current Practice [Page 3] 171 | 172 | -------------------------------------------------------------------------------- /reviews/README.md: -------------------------------------------------------------------------------- 1 | # Data Standards Normative and Informative Reference Analysis 2 | 3 | The following document contains a summary of each review the Data Standards Body has conducted of the normative and informative standards relied upon by the Consumer Data Standards. 4 | 5 | ## Summary 6 | 7 | ### Reviews 8 | 9 | | Review Date | Review Archive | 10 | | --- | ---- | 11 | | 2021-05 | [Archive Link](2021-05/README.md) | 12 | 13 | ### Normative References 14 | 15 | | **Reference** | **Description** | **Baseline Version** | **05-2021 Version** | 16 | | --- | --- | --- | --- | 17 | | **[FAPI-R]** | Financial-grade API - Part 1: Read Only API Security Profile: |[Draft-06](https://openid.net/specs/openid-financial-api-part-1-ID2.html) | [1.0 Final - March 12, 2021](https://openid.net/specs/openid-financial-api-part-1-1_0.html) | 18 | | **[FAPI-RW]** | Financial-grade API - Part 2: Read and Write API Security Profile: |[Draft-06](https://openid.net/specs/openid-financial-api-part-2-ID2.html) | [1.0 Final - March 12, 2021](https://openid.net/specs/openid-financial-api-part-2-1_0.html) | 19 | | **[JSON]** | The JavaScript Object Notation (JSON) Data Interchange Format | [Dec 2017](https://tools.ietf.org/html/rfc8259) | No change | 20 | | **[JWA]** | JSON Web Algorithms (JWA) | [May 2015](https://tools.ietf.org/html/rfc7518) | No change | 21 | | **[JWK]** | JSON Web Key (JWK) | [May 2015](https://tools.ietf.org/html/rfc7517) | No change | 22 | | **[JWT]** | JSON Web Token (JWT) | [May 2015](https://tools.ietf.org/html/rfc7519) | No change | 23 | | **[JWS]** | JSON Web Signature (JWS) | [Feb 2016](https://tools.ietf.org/html/rfc7797) | No change | 24 | | **[JWE]** | JSON Web Encryption (JWE) | [May 2015](https://tools.ietf.org/html/rfc7516) | No change | 25 | | **[MTLS]** | OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens | [Feb 2020](https://tools.ietf.org/html/rfc8705) | No change | 26 | | **[OAUTH2]** | The OAuth 2.0 Authorization Framework | [Oct 2012](https://tools.ietf.org/html/rfc6749)| No change | 27 | | **[OIDC]** | OpenID Connect Core 1.0 incorporating errata set 1 | [Nov 2014](http://openid.net/specs/openid-connect-core-1_0.html) | No change | 28 | | **[OIDD]** | OpenID Connect Discovery 1.0 incorporating errata set 1 | [Nov 2014](http://openid.net/specs/openid-connect-discovery-1_0.html)| No change | 29 | | **[TDIF]** | Digital Transformation Agency - Trusted Digital Identity Framework | [Apr 2019](https://www.dta.gov.au/our-projects/digital-identity/trusted-digital-identity-framework) | **_in review_** | 30 | | **[RFC2119]** | Key words for use in RFCs to Indicate Requirement Levels | [RFC2119 - Mar 1997](https://datatracker.ietf.org/doc/html/rfc2119) | [RFC8174 - May 2017](https://datatracker.ietf.org/doc/html/rfc8174) | 31 | | **[RFC7009]** | OAuth 2.0 Token Revocation | [Aug 2013](https://tools.ietf.org/html/rfc7009) | No change | 32 | | **[RFC7523]** | JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants | [May 2015](https://tools.ietf.org/html/rfc7523) | No change | 33 | | **[RFC7662]** | OAuth 2.0 Token Introspection | [RFC7662 - Oct 2015](https://tools.ietf.org/html/rfc7662) | [RFC8996 - March 2021](https://datatracker.ietf.org/doc/html/rfc8996) | 34 | | **[RFC6750]** | The OAuth 2.0 Authorization Framework: Bearer Token Usage | [Oct 2012](https://tools.ietf.org/html/rfc6750) | No change | 35 | | **[PAR]** | OAuth 2.0 Pushed Authorization Requests | [Draft 01 - Feb 2020](https://tools.ietf.org/html/draft-ietf-oauth-par-01) | [Draft 08 - May 2021](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-par-08) | 36 | 37 | 38 | ## Informative References 39 | 40 | The following informative references were current at the time of review. For each reference, the version relied upon in the Consumer Data Standards as well as the most current version available of the reference are listed. 41 | 42 | | **Reference** | **Description** | **Baseline Version** | **05-2021 Version** | 43 | |----------------|-----------------|----------------------|---------------------| 44 | | **[BCP195]** | Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) | [May 2015](https://tools.ietf.org/html/bcp195) | [March 2021](https://tools.ietf.org/html/bcp195) | 45 | | **[RFC7231]** | Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content | [June 2014](https://tools.ietf.org/html/rfc7231) | [Updated by RFC2817](https://datatracker.ietf.org/doc/html/rfc2817)| 46 | | **[CDR]** | Consumer Data Right: | [Link](https://www.accc.gov.au/focus-areas/consumer-data-right) | [**New Link**](https://www.cdr.gov.au) | 47 | | **[FAPI]** | Financial-Grade API - Home Page | [Link](https://openid.net/wg/fapi/) | No change | 48 | | **[RFC4122]** | A Universally Unique Identifier (UUID) URN Namespace | [July 2005](https://tools.ietf.org/html/rfc4122) | No change | 49 | | **[X.1254]** | X.1254 - Entity authentication assurance framework | [Sept 2012](https://www.itu.int/rec/T-REC-X1254-201209-I/en) | [Sept 2020](https://www.itu.int/rec/T-REC-X.1254-202009-I/en) 50 | -------------------------------------------------------------------------------- /reviews/2021-05/raw/rfc8174.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | Internet Engineering Task Force (IETF) B. Leiba 8 | Request for Comments: 8174 Huawei Technologies 9 | BCP: 14 May 2017 10 | Updates: 2119 11 | Category: Best Current Practice 12 | ISSN: 2070-1721 13 | 14 | 15 | Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words 16 | 17 | Abstract 18 | 19 | RFC 2119 specifies common key words that may be used in protocol 20 | specifications. This document aims to reduce the ambiguity by 21 | clarifying that only UPPERCASE usage of the key words have the 22 | defined special meanings. 23 | 24 | Status of This Memo 25 | 26 | This memo documents an Internet Best Current Practice. 27 | 28 | This document is a product of the Internet Engineering Task Force 29 | (IETF). It represents the consensus of the IETF community. It has 30 | received public review and has been approved for publication by the 31 | Internet Engineering Steering Group (IESG). Further information on 32 | BCPs is available in Section 2 of RFC 7841. 33 | 34 | Information about the current status of this document, any errata, 35 | and how to provide feedback on it may be obtained at 36 | http://www.rfc-editor.org/info/rfc8174. 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | Leiba Best Current Practice [Page 1] 59 | 60 | RFC 8174 RFC 2119 Clarification May 2017 61 | 62 | 63 | Copyright Notice 64 | 65 | Copyright (c) 2017 IETF Trust and the persons identified as the 66 | document authors. All rights reserved. 67 | 68 | This document is subject to BCP 78 and the IETF Trust's Legal 69 | Provisions Relating to IETF Documents 70 | (http://trustee.ietf.org/license-info) in effect on the date of 71 | publication of this document. Please review these documents 72 | carefully, as they describe your rights and restrictions with respect 73 | to this document. Code Components extracted from this document must 74 | include Simplified BSD License text as described in Section 4.e of 75 | the Trust Legal Provisions and are provided without warranty as 76 | described in the Simplified BSD License. 77 | 78 | Table of Contents 79 | 80 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 81 | 2. Clarifying Capitalization of Key Words . . . . . . . . . . . 3 82 | 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 83 | 4. Security Considerations . . . . . . . . . . . . . . . . . . . 4 84 | 5. Normative References . . . . . . . . . . . . . . . . . . . . 4 85 | Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 4 86 | 87 | 1. Introduction 88 | 89 | RFC 2119 specifies common key words, such as "MUST", "SHOULD", and 90 | "MAY", that may be used in protocol specifications. It says that the 91 | key words "are often capitalized," which has caused confusion about 92 | how to interpret non-capitalized words such as "must" and "should". 93 | 94 | This document updates RFC 2119 by clarifying that only UPPERCASE 95 | usage of the key words have the defined special meanings. This 96 | document is part of BCP 14. 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | Leiba Best Current Practice [Page 2] 115 | 116 | RFC 8174 RFC 2119 Clarification May 2017 117 | 118 | 119 | 2. Clarifying Capitalization of Key Words 120 | 121 | The following change is made to [RFC2119]: 122 | 123 | === OLD === 124 | In many standards track documents several words are used to signify 125 | the requirements in the specification. These words are often 126 | capitalized. This document defines these words as they should be 127 | interpreted in IETF documents. Authors who follow these guidelines 128 | should incorporate this phrase near the beginning of their document: 129 | 130 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 131 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 132 | document are to be interpreted as described in RFC 2119. 133 | 134 | 135 | === NEW === 136 | In many IETF documents, several words, when they are in all capitals 137 | as shown below, are used to signify the requirements in the 138 | specification. These capitalized words can bring significant clarity 139 | and consistency to documents because their meanings are well defined. 140 | This document defines how those words are interpreted in IETF 141 | documents when the words are in all capitals. 142 | 143 | o These words can be used as defined here, but using them is not 144 | required. Specifically, normative text does not require the use 145 | of these key words. They are used for clarity and consistency 146 | when that is what's wanted, but a lot of normative text does not 147 | use them and is still normative. 148 | 149 | o The words have the meanings specified herein only when they are in 150 | all capitals. 151 | 152 | o When these words are not capitalized, they have their normal 153 | English meanings and are not affected by this document. 154 | 155 | Authors who follow these guidelines should incorporate this phrase 156 | near the beginning of their document: 157 | 158 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 159 | NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", 160 | "MAY", and "OPTIONAL" in this document are to be interpreted as 161 | described in BCP 14 [RFC2119] [RFC8174] when, and only when, they 162 | appear in all capitals, as shown here. 163 | 164 | === END === 165 | 166 | 167 | 168 | 169 | 170 | Leiba Best Current Practice [Page 3] 171 | 172 | RFC 8174 RFC 2119 Clarification May 2017 173 | 174 | 175 | 3. IANA Considerations 176 | 177 | This document does not require any IANA actions. 178 | 179 | 4. Security Considerations 180 | 181 | This document is purely procedural; there are no related security 182 | considerations. 183 | 184 | 5. Normative References 185 | 186 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 187 | Requirement Levels", BCP 14, RFC 2119, 188 | DOI 10.17487/RFC2119, March 1997, 189 | . 190 | 191 | Author's Address 192 | 193 | Barry Leiba 194 | Huawei Technologies 195 | 196 | Phone: +1 646 827 0648 197 | Email: barryleiba@computer.org 198 | URI: http://internetmessagingtechnology.org/ 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 | 224 | 225 | 226 | Leiba Best Current Practice [Page 4] 227 | 228 | -------------------------------------------------------------------------------- /reviews/2021-05/README.md: -------------------------------------------------------------------------------- 1 | # Normative references analysis 2 | 3 | **Review Date:** May 2021 4 | 5 | ## Overview 6 | 7 | The following document contains a review of the normative and informative references the Consumer Data Standards rely upon. It provides a gap analysis of the existing normative and informative references in version 1.9.0 of the Consumer Data Standards compared to the latest versions of those references. Where a referenced RFC has been superseded with a newer RFC, this analysis is also provided. 8 | 9 | This review is to be conducted bi-annualy under the DSB's Future Plan [DSB Item - Normative Standards Review](https://github.com/ConsumerDataStandardsAustralia/future-plan/issues/34). 10 | 11 | A previous external FAPI specification analysis was conducted by the OpenID Foundation in January 2020. It can be found [here](https://bitbucket.org/openid/fapi/src/master/cds-spec-analysis/). 12 | 13 | ## Summary of changes 14 | This document will summarise the key differences of the proposed Consumer Data Standards when compared against the normative references adopted. The Consumer Data Standards are the underlying technical standards to deliver on the Australian Government's Consumer Data Right legislation, which was passed 1 August 2019. 15 | 16 | Non-breaking and breaking changes will be documented here. Where changes result in breaking changes to Data Recipients and/or Data Holders, consultation will be conducted on these changes to specifically address the transition arrangements, technical standards solution and the obligation dates to be considered. 17 | 18 | ## Outcomes 19 | 20 | Performing this review achieves several outcomes, notably: 21 | * Ensures the Consumer Data Standards are current and maintain interoperability with supported international standards 22 | * Identify any breaking changes due to the uplift to current international standards and determine transition stages and obligation dates arising from those changes to transition the ecosystem in a stable and reliable way 23 | * Reduce legacy maintenance costs and technical debt 24 | * Maintain improved vendor support for implementers 25 | * Maintain interoperability within the CDR and internationally 26 | 27 | ### Considerations 28 | This purpose of this impact analysis is to identify key changes between current baseline versions of normative references relied upon in v1.11.0 of the Consumer Data Standards and the current stable target version of these normative references. Changes identified may broadly fall into one of three categories: 29 | 30 | 1. Non-material changes: Changes in the documentation text, format or presentation of the normative standards that don't materially change the intent of of the baseline standard. These changes do not impact the Consumer Data Standards or participants. 31 | 2. Implicit breaking changes: Breaking changes that impact participants but do not change statements presented in the Consumer Data Standards. The scope of these changes are considerations for phasing and implementation timeframes but they don't give rise to explicit changes in the Consumer Data Standards themselves. Participants would be impacted with changes required to existing implementations to be compliant with the target-state normative references. 32 | 3. Explicit breaking changes: Changes that directly impact the Consumer Data Standards and result in changes to statements presented within the Consumer Data Standards. These by definition will create implementation impacts for participants and require sufficient phasing with new obligation dates to be determined. 33 | 34 | Breaking changes documented in this analyses may result in a number of outcomes, notably: 35 | - Existing implementations must be changed, requiring new builds to meet the desired requirements 36 | - Deviations of the Consumer Data Standards from the normative references. In some circumstances, for example, the lack of vendor adoption, or considerations of co-existence with existing functionality and maintaining ecosystem interoperability, or diverse phasing, testing and deployment across the ecosystem may necessitate deviation or staggered adoption of certain requirements defined within normative references. 37 | - Interoperability between implementations will, potentially significantly, be impacted. The result of this lack of interoperability has significant flow on effects with respect to software vendor diversity and competition 38 | - Changes to certification and testing processes provided by CDR regulators and commercial vendors 39 | - Changes to accreditation and existing industry certification processes may be non-functional requiring a separate certification process to be established and maintained by the creating entity 40 | - Impacts to other non-functional requirements such as performance 41 | 42 | ## Normative References 43 | 44 | The following normative references were current at the time of review. For each reference, the version relied upon in the Consumer Data Standards as well as the most current version available of the reference are listed. 45 | 46 | | **Reference** | **Description** | **Baseline Version** | **05-2021 Version** | **Spec Diff** | **Spec Analysis** | 47 | | --- | --- | --- | --- | --- | --- | 48 | | **[FAPI-R]** | Financial-grade API - Part 1: Read Only API Security Profile: |[Draft-06](https://openid.net/specs/openid-financial-api-part-1-ID2.html) | [1.0 Final - March 12, 2021](https://openid.net/specs/openid-financial-api-part-1-1_0.html) | [diff-fapi-draft06-part1-fapi-1.0-part1](./diff/diff-fapi-draft06-part1-fapi-1.0-part1.html) | [analysis-fapi-part1](./analysis/analysis-fapi-part1-20210614.md) | 49 | | **[FAPI-RW]** | Financial-grade API - Part 2: Read and Write API Security Profile |[Draft-06](https://openid.net/specs/openid-financial-api-part-2-ID2.html) | [1.0 Final - March 12, 2021](https://openid.net/specs/openid-financial-api-part-2-1_0.html) | [diff-fapi-draft06-part2-fapi-1.0-part2](./diff/diff-fapi-draft06-part2-fapi-1.0-part2.html) | [analysis-fapi-part2](./analysis/analysis-fapi-part2-20210621.md) | 50 | | **[JSON]** | The JavaScript Object Notation (JSON) Data Interchange Format | [Dec 2017](https://tools.ietf.org/html/rfc8259) | No change | N/A | N/A | 51 | | **[JWA]** | JSON Web Algorithms (JWA) | [May 2015](https://tools.ietf.org/html/rfc7518) | No change |N/A | N/A | 52 | | **[JWK]** | JSON Web Key (JWK) | [May 2015](https://tools.ietf.org/html/rfc7517) | No change |N/A | N/A | 53 | | **[JWT]** | JSON Web Token (JWT) | [May 2015](https://tools.ietf.org/html/rfc7519) | No change |N/A | N/A | 54 | | **[JWS]** | JSON Web Signature (JWS) | [Feb 2016](https://tools.ietf.org/html/rfc7797) | No change |N/A | N/A | 55 | | **[JWE]** | JSON Web Encryption (JWE) | [May 2015](https://tools.ietf.org/html/rfc7516) | No change |N/A | N/A | 56 | | **[MTLS]** | OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens | [Feb 2020](https://tools.ietf.org/html/rfc8705) | No change |N/A | N/A | 57 | | **[OAUTH2]** | The OAuth 2.0 Authorization Framework | [Oct 2012](https://tools.ietf.org/html/rfc6749)| No change |N/A | N/A | 58 | | **[OIDC]** | OpenID Connect Core 1.0 incorporating errata set 1 | [Nov 2014](http://openid.net/specs/openid-connect-core-1_0.html) | No change |N/A | N/A | 59 | | **[OIDD]** | OpenID Connect Discovery 1.0 incorporating errata set 1 | [Nov 2014](http://openid.net/specs/openid-connect-discovery-1_0.html)| No change |N/A | N/A | 60 | | **[TDIF]** | Digital Transformation Agency - Trusted Digital Identity Framework | [Apr 2019](https://www.dta.gov.au/our-projects/digital-identity/trusted-digital-identity-framework) | **_in review_** | pending | pending | 61 | | **[RFC2119]** | Key words for use in RFCs to Indicate Requirement Levels | [RFC2119 - Mar 1997](https://tools.ietf.org/html/rfc2119) | [RFC8175 - May 2017](https://datatracker.ietf.org/doc/html/rfc8174) | [diff-rfc2119-rfc8175](./diff/diff-rfc2119-rfc8174.txt) | [analysis-rfc2119-rfc8174-20210519](./analysis/analysis-rfc2119-rfc8174-20210519.md) | 62 | | **[RFC7009]** | OAuth 2.0 Token Revocation | [Aug 2013](https://tools.ietf.org/html/rfc7009) | No change |N/A | N/A | 63 | | **[RFC7523]** | JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants | [May 2015](https://tools.ietf.org/html/rfc7523) | No change | N/A | N/A | 64 | | **[RFC7662]** | OAuth 2.0 Token Introspection | [RFC7662 - Oct 2015](https://tools.ietf.org/html/rfc7662) | [RFC8996 - March 2021](https://datatracker.ietf.org/doc/html/rfc8996) | pending | pending | 65 | | **[RFC6750]** | The OAuth 2.0 Authorization Framework: Bearer Token Usage | [Oct 2012](https://tools.ietf.org/html/rfc6750) | No change |N/A | N/A | 66 | | **[PAR]** | OAuth 2.0 Pushed Authorization Requests | [Draft 01 - Feb 2020](https://tools.ietf.org/html/draft-ietf-oauth-par-01) | [Draft 08 - May 2021](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-par-08) |[diff-par01-par08](./diff/diff-par01-par08.html) | [analysis-par-20210704](./analysis/analysis-par-20210704.md) | 67 | 68 | 69 | ## Informative References 70 | 71 | The following informative references were current at the time of review. For each reference, the version relied upon in the Consumer Data Standards as well as the most current version available of the reference are listed. 72 | 73 | | **Reference** | **Description** | **Baseline Version** | **05-2021 Version** |**Spec Diff** | **Spec Analysis** | 74 | | --- | --- | --- | --- | --- | --- | 75 | | **[BCP195]** | Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) | [May 2015](https://tools.ietf.org/html/bcp195) | [March 2021](https://tools.ietf.org/html/bcp195) | pending | pending | 76 | | **[RFC7231]** | Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content | [June 2014](https://tools.ietf.org/html/rfc7231) | [Updated by RFC2817](https://datatracker.ietf.org/doc/html/rfc2817)| pending | pending | 77 | | **[CDR]** | Consumer Data Right: | [Link](https://www.accc.gov.au/focus-areas/consumer-data-right) | [**New Link**](https://www.cdr.gov.au) |N/A | N/A | 78 | | **[FAPI]** | Financial-Grade API - Home Page | [Link](https://openid.net/wg/fapi/) | No change |N/A | N/A | 79 | | **[RFC4122]** | A Universally Unique Identifier (UUID) URN Namespace | [July 2005](https://tools.ietf.org/html/rfc4122) | No change |N/A | N/A | 80 | | **[X.1254]** | X.1254 - Entity authentication assurance framework | [Sept 2012](https://www.itu.int/rec/T-REC-X1254-201209-I/en) | [Sept 2020](https://www.itu.int/rec/T-REC-X.1254-202009-I/en)| N/A | N/A | 81 | 82 | ## Additional Specifications 83 | These specifications are relied upon within the Consumer Data Standards but are not currently listed in either the normative or informative references. 84 | 85 | Name | Title | URL 86 | :-- | :-- | :-- 87 | WCAG 2.1 | Web Content Accessibility Guidelines (WCAG) 2.1 | https://www.w3.org/TR/WCAG21/ 88 | Australia Post Data Guide | Guidelines for using Australia Post data | https://auspost.com.au/content/dam/auspost_corp/media/documents/australia-post-data-guide.pdf 89 | RFC: 5246 | The Transport Layer Security (TLS) Protocol Version 1.2 | https://www.ietf.org/rfc/rfc5246.txt 90 | RFC: 3339 | Date and Time on the Internet: Timestamps | https://tools.ietf.org/html/rfc3339.html 91 | RFC: 3966 | The tel URI for Telephone Numbers | https://tools.ietf.org/html/rfc3966 92 | ISO 9362 | Business Identifier Code (BIC) | https://www.iso9362.org/, https://www.iso.org/standard/60390.html 93 | ISO 8601 | Data elements and interchange formats – Information interchange – Representation of dates and times| https://www.iso.org/standard/70907.html 94 | ISO 3166 | Country Codes | https://www.iso.org/iso-3166-country-codes.html 95 | ISO 4217 | Current currency & funds code list | https://www.currency-iso.org/en/home/tables/table-a1.html 96 | ISO 17442 | Legal Entity Identifier | https://www.iso.org/standard/59771.html 97 | -------------------------------------------------------------------------------- /reviews/2021-05/analysis/analysis-par-20210704.md: -------------------------------------------------------------------------------- 1 | # Overview 2 | 3 | * **Specification:** Pushed Authorization Requests (PAR) 4 | * **Baseline Version:** [Pushed Authorization Requests Draft 01](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-par-01) 5 | * **Target Version:** [Pushed Authorization Requests Draft 08](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-par-08) 6 | 7 | This document summarises the changes between Pushed Authorization Requests Draft 01 and Pushed Authorization Requests Draft 08 and the impacts to the Consumer Data Standards. 8 | 9 | Impact analysis is compared against v1.11.0 of the Consumer Data Standards. 10 | 11 | **Please note:** [Draft 09](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-par-09) has now been published (12 July 2021) . A diff of Draft 08 to Draft 09 is [available here](https://www.ietf.org/rfcdiff?difftype=--hwdiff&url2=draft-ietf-oauth-par-09.txt). Whilst this analysis compared Draft 02 to Draft 08, no material differences have been identified between Draft 08 and Draft 09 that impact this analysis. 12 | 13 | # Summary of key changes 14 | 15 | At the time of review, the PAR specification is currently draft version 08. Because the PAR specification remains in draft, there are likely future draft revisions that will be published. One consideration the DSB is seeking feedback from the community is whether the data standards should continue to specify an explicit draft version (08) or refer to PAR as being what ever the latest revision is. This would have the advantage that whatever the most recent version is, implementations can rely upon it and potentially use the version provided out of the box by their IAM vendor provided that vendor remains up to date with the most recent version. The downside is that the implementation of new draft versions would be immediate and there would be no future dated obligation if a newer draft version were to create breaking changes. 16 | 17 | ## Requires community feedback 18 | 19 | - Should the CDS explicitly define the `request_uri` must only be used once and cannot be replayed? 20 | - Should the CDS explicitly define the upper lifetime of the `request_uri`? 21 | - Determine the appropriate HTTP status code and oAuth error code to respond with when the `request_uri` is re-used. Currently presumed this is a 400 (Bad Request) and oAuth error `invalid_request` or `access_denied`. 22 | - Implications with recently introduced CDR Register standards for `sector_identifier_uri` is unknown 23 | - Introduces the new OIDD metadata parameter `require_pushed_authorization_requests`. Recommended that DHs can choose whether to require this and if so ADRs MUST only use PAR if true. This would give DHs more discretion over security and simplification of implementation. The CDS doesn't need to override or preclude this. If there is a desire to simplify the CDS, it may be preferred to limit the CDS to always require PAR for better interoperability in a many-to-many ecosystem and reduce interoperability choices. 24 | 25 | ## Clients (ADRs) 26 | 27 | - § 4.: Clients MUST only use a "request_uri" value once 28 | - § 2.: If the Authorisation Server includes `require_pushed_authorization_requests` = `true` in their OIDD, then the client MUST use PAR and MUST NOT pass the request object to the authorisation endpoint 29 | 30 | ## OpenID Provider / Authorisation Server (Data Holders) 31 | 32 | - § 4.: Data Holders should respond with an error if the `request_uri` is re-used 33 | - § 5.: If the Authorisation Server MAY include `require_pushed_authorization_requests` in their OIDD (defaults to `false` otherwise) 34 | - § 5.: If the Authorisation Server sets `require_pushed_authorization_requests` = `true`, they MUST reject request objects passed to the authorisation endpoint 35 | - § 3.: Drops the requirement of "401 Unauthorized" where the client signature, "client_id" or "iss" fail validation 36 | - § 3.: DH may respond with invalid_client or invalid_authorization error response as per [RFC6749 section 5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2). 37 | 38 | ## Conformance Testing 39 | 40 | - § 2.: It may be worthwhile for completeness for the CTS to assert correct values in the "token_endpoint_auth_method" and "token_endpoint_auth_method_supported" values 41 | - § 3.: DH may respond with `invalid_client` or `invalid_authorization` error response as per [RFC6749 section 5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2). 42 | * **NOTE:** This may result in some implementation and CTS changes or at the very least regression testing by DHs and ADRs 43 | 44 | # Analysis 45 | 46 | ## 1. Introduction 47 | 48 | * The Draft 08 Introduction provides a more detailed explanation behind the intent and use of PAR but has no material differences that change implementation. 49 | 50 | ### 1.1. Introductory Example 51 | 52 | * No material differences 53 | 54 | ### 1.2. Conventions and Terminology 55 | 56 | * No material differences 57 | 58 | ## 2. Pushed Authorization Request Endpoint 59 | 60 | * § 2. &‌para; 1: requires HTTPS 61 | * § 2. &‌para; 2: Authorisation servers SHOULD include their PAR endpoint using the OIDD "pushed_authorization_request_endpoint" parameter. **NOTE:** CDS requires that this MUST be published in the OIDD. This removes ambiguity in the CDR's many-to-many environment 62 | 63 | * § 2. &‌para; 4: Introduces client authentication can be negotiated via "token_endpoint_auth_methods_supported" (currently supported in the CDS) or "token_endpoint_auth_method" (this also existed in PAR Draft 01) 64 | 65 | **NOTE:** For completeness, it may be beneficial for the CTS to provide test cases that verify correct implementation for client and server of the "token_endpoint_auth_methods_supported" and "token_endpoint_auth_method" parameters including where both are provided. 66 | 67 | CDS uses "private_key_jwt". Currently the behaviour is ambiguous if the AS provides different values in these two metadata parameters and one is not "private_key_jwt". 68 | 69 | ### 2.1. Request 70 | 71 | * No material differences 72 | 73 | ### 2.2. Successful Response 74 | 75 | * § 2.2.: Drops mention that the `request_uri` is intended for one time use. There is currently no clause in FAPI 1.0 that restricts this meaning that Authorisation Servers MAY implement the `request_uri` in such a way that it can be re-used within its lifetime or be recycled. This is still cryptographically bound to the oAuth client however there may be issues where it could be replayed within a short period of time. 76 | 77 | **Old clause** 78 | 79 | > Since the request URI can be replayed, its lifetime SHOULD be short 80 | > and preferably limited to one-time use. 81 | 82 | * **NOTE:** Should the CDS prevent this, or is this replay not seen as an issue - it may be useful where the client attempts to go through the authorisation flow but encounters a technical issue and can replay the `request_uri` without re-staging it though this seems to be of little benefit. It is pre-authentication so again, there is limited opportunity for malicious use/replay attack. The only question is whether a simplified authentication flow may be impacted if the consumer is not required to authenticate. 83 | * Further to this, there is a change in § 4. ¶ 3 which details these requirements. 84 | 85 | * The PAR spec also doesn't suggest the appropriate error for the AS to respond with when replay is not supported or denied. Presumably this is a 400 (Bad Request) per § 2.3. 86 | 87 | ### 2.3. Error Response 88 | 89 | * No material differences 90 | 91 | ### 2.4. Management of Client Redirect URIs 92 | 93 | **New section** 94 | 95 | * Allows for the provision of per-request `redirect_uris` that have not been previously registered with the Authorisation Server. 96 | 97 | > The authorization server MAY allow such 98 | > clients to specify "redirect_uri" values that were not previously 99 | > registered with the authorization server. 100 | 101 | * This is not currently permitted in the CDR which requires valid `redirect_uris` to be registered. 102 | * It is worth reviewing this in light of other provisions such as `sector_identifier_uri` and may also have implications for PPID generation if this allowance is adopted or considered in a future iteration of the standards. 103 | * This may provide (with consideration) a way to deal with ADR SaaS / Outsourced Service Provider arrangements where the client is managed by a trusted third-part of the ADR 104 | 105 | ## 3. The "request" Request Parameter 106 | 107 | * The following sections have been removed: 108 | * 3.1. Error responses for Request Object 109 | * 3.1.1. Authentication Required 110 | 111 | * Drops the requirement of "401 Unauthorized" where the client signature, "client_id" or "iss" fail validation 112 | * This means that [RFC6749 section 5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2) takes effect. 113 | * **NOTE:** This may result in some implementation and CTS changes or at the very least regression testing by DHs and ADRs 114 | 115 | ## 4. Authorization Request 116 | 117 | * No material differences 118 | 119 | * § 4. ¶ 3: Implies that `request_uri` should only be treated as a one-time code. However it does allow for it to be re-used. The spec makes in mandatory that clients only use the `request_uri` once. 120 | 121 | > Since parts of the authorization request content, e.g. the 122 | > "code_challenge" parameter value, are unique to a particular 123 | > authorization request, the client MUST only use a "request_uri" value 124 | > once. Authorization servers SHOULD treat "request_uri" values as 125 | > one-time use but MAY allow for duplicate requests due to a user 126 | > reloading/refreshing their user-agent. 127 | 128 | ## 5. Authorization Server Metadata 129 | 130 | * Introduces a new "require_pushed_authorization_requests" parameter. For the CDS this would default to "false" because it is not mandatory. Presently, the request object can be passed by value for authorisation requests unless it is an amending consent flow where the cdr_arrangement_id is passed. 131 | 132 | ## 6. Client Metadata 133 | 134 | **New section** 135 | 136 | * Introduces a new "require_pushed_authorization_requests" parameter. 137 | 138 | ## 7. Security Considerations 139 | 140 | * No differences 141 | 142 | ### 7.1. Request URI Guessing 143 | 144 | * No material differences 145 | 146 | ### 7.2. Open Redirection 147 | 148 | * No material differences 149 | 150 | ### 7.3. Request Object Replay 151 | 152 | * No material differences 153 | 154 | ### 7.4. Client Policy Change 155 | 156 | * No material differences 157 | 158 | ### 7.5. Request URI Swapping 159 | 160 | **New section** 161 | 162 | * Clients SHOULD use PKCE 163 | * Additionally request_uri is cryptographically bound to the client and the client is authenticated at the PAR endpoint before the AS returns the request_uri so this attack should be obviated 164 | 165 | > Clients SHOULD make use of PKCE 166 | > [RFC7636], a unique "state" parameter [RFC6749], or the OIDC "nonce" 167 | > parameter [OIDC] in the pushed request object to prevent this attack. 168 | 169 | ## 8. Privacy Considerations 170 | * No material differences 171 | 172 | ## 9. Acknowledgements 173 | 174 | * Not applicable 175 | 176 | ## 10. IANA Considerations 177 | ### 10.1. OAuth Authorization Server Metadata 178 | 179 | * Adds the following registered property" `require_pushed_authorization_requests` - this will need to be considered if the CDS mandated authorisation requests always use PAR or DHs can choose not to support request objects sent by value delivered to the authorisation endpoint. There may be advantaged for DHs to secure & simplify their implementations to only support PAR and perform request object validation at the PAR endpoint after client authentication as opposed to receiving the request object at the authorisation endpoint. 180 | 181 | **Feedback welcome from DHs and ADRs** 182 | 183 | ### 10.2. OAuth Dynamic Client Registration Metadata 184 | 185 | * Refer to § 10.1. 186 | 187 | ### 10.3. OAuth URI Registration 188 | 189 | * Refer to § 10.1. 190 | 191 | ## 11. Normative References 192 | 193 | * Depends on the most recent draft of JWT Secured Authorization Requests (JAR): draft-ietf-oauth-jwsreq-34, 8 April 2021. 194 | * Previously Draft 20, 21 October 2019 195 | * Drops explicit reference to OIDC and RFC6749 and moves them to the informative references 196 | 197 | ## 12. Informative References 198 | 199 | * No material differences 200 | -------------------------------------------------------------------------------- /reviews/2021-05/diff/diff-rfc2119-rfc8174.txt: -------------------------------------------------------------------------------- 1 | 7,9c7,10 2 | < Network Working Group S. Bradner 3 | < Request for Comments: 2119 Harvard University 4 | < BCP: 14 March 1997 5 | --- 6 | > Internet Engineering Task Force (IETF) B. Leiba 7 | > Request for Comments: 8174 Huawei Technologies 8 | > BCP: 14 May 2017 9 | > Updates: 2119 10 | 10a12,40 11 | > ISSN: 2070-1721 12 | > 13 | > 14 | > Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words 15 | > 16 | > Abstract 17 | > 18 | > RFC 2119 specifies common key words that may be used in protocol 19 | > specifications. This document aims to reduce the ambiguity by 20 | > clarifying that only UPPERCASE usage of the key words have the 21 | > defined special meanings. 22 | > 23 | > Status of This Memo 24 | > 25 | > This memo documents an Internet Best Current Practice. 26 | > 27 | > This document is a product of the Internet Engineering Task Force 28 | > (IETF). It represents the consensus of the IETF community. It has 29 | > received public review and has been approved for publication by the 30 | > Internet Engineering Steering Group (IESG). Further information on 31 | > BCPs is available in Section 2 of RFC 7841. 32 | > 33 | > Information about the current status of this document, any errata, 34 | > and how to provide feedback on it may be obtained at 35 | > http://www.rfc-editor.org/info/rfc8174. 36 | > 37 | > 38 | > 39 | > 40 | 13d42 41 | < Key words for use in RFCs to Indicate Requirement Levels 42 | 15d43 43 | < Status of this Memo 44 | 17,19d44 45 | < This document specifies an Internet Best Current Practices for the 46 | < Internet Community, and requests discussion and suggestions for 47 | < improvements. Distribution of this memo is unlimited. 48 | 21d45 49 | < Abstract 50 | 23,27d46 51 | < In many standards track documents several words are used to signify 52 | < the requirements in the specification. These words are often 53 | < capitalized. This document defines these words as they should be 54 | < interpreted in IETF documents. Authors who follow these guidelines 55 | < should incorporate this phrase near the beginning of their document: 56 | 29,32d47 57 | < The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 58 | < NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 59 | < "OPTIONAL" in this document are to be interpreted as described in 60 | < RFC 2119. 61 | 34,35d48 62 | < Note that the force of these words is modified by the requirement 63 | < level of the document in which they are used. 64 | 37,38d49 65 | < 1. MUST This word, or the terms "REQUIRED" or "SHALL", mean that the 66 | < definition is an absolute requirement of the specification. 67 | 40,41d50 68 | < 2. MUST NOT This phrase, or the phrase "SHALL NOT", mean that the 69 | < definition is an absolute prohibition of the specification. 70 | 43,46d51 71 | < 3. SHOULD This word, or the adjective "RECOMMENDED", mean that there 72 | < may exist valid reasons in particular circumstances to ignore a 73 | < particular item, but the full implications must be understood and 74 | < carefully weighed before choosing a different course. 75 | 48,52d52 76 | < 4. SHOULD NOT This phrase, or the phrase "NOT RECOMMENDED" mean that 77 | < there may exist valid reasons in particular circumstances when the 78 | < particular behavior is acceptable or even useful, but the full 79 | < implications should be understood and the case carefully weighed 80 | < before implementing any behavior described with this label. 81 | 58c58 82 | < Bradner Best Current Practice [Page 1] 83 | --- 84 | > Leiba Best Current Practice [Page 1] 85 | 60c60 86 | < RFC 2119 RFC Key Words March 1997 87 | --- 88 | > RFC 8174 RFC 2119 Clarification May 2017 89 | 63,73c63 90 | < 5. MAY This word, or the adjective "OPTIONAL", mean that an item is 91 | < truly optional. One vendor may choose to include the item because a 92 | < particular marketplace requires it or because the vendor feels that 93 | < it enhances the product while another vendor may omit the same item. 94 | < An implementation which does not include a particular option MUST be 95 | < prepared to interoperate with another implementation which does 96 | < include the option, though perhaps with reduced functionality. In the 97 | < same vein an implementation which does include a particular option 98 | < MUST be prepared to interoperate with another implementation which 99 | < does not include the option (except, of course, for the feature the 100 | < option provides.) 101 | --- 102 | > Copyright Notice 103 | 75c65,66 104 | < 6. Guidance in the use of these Imperatives 105 | --- 106 | > Copyright (c) 2017 IETF Trust and the persons identified as the 107 | > document authors. All rights reserved. 108 | 77,83c68,76 109 | < Imperatives of the type defined in this memo must be used with care 110 | < and sparingly. In particular, they MUST only be used where it is 111 | < actually required for interoperation or to limit behavior which has 112 | < potential for causing harm (e.g., limiting retransmisssions) For 113 | < example, they must not be used to try to impose a particular method 114 | < on implementors where the method is not required for 115 | < interoperability. 116 | --- 117 | > This document is subject to BCP 78 and the IETF Trust's Legal 118 | > Provisions Relating to IETF Documents 119 | > (http://trustee.ietf.org/license-info) in effect on the date of 120 | > publication of this document. Please review these documents 121 | > carefully, as they describe your rights and restrictions with respect 122 | > to this document. Code Components extracted from this document must 123 | > include Simplified BSD License text as described in Section 4.e of 124 | > the Trust Legal Provisions and are provided without warranty as 125 | > described in the Simplified BSD License. 126 | 85c78 127 | < 7. Security Considerations 128 | --- 129 | > Table of Contents 130 | 87,94c80,85 131 | < These terms are frequently used to specify behavior with security 132 | < implications. The effects on security of not implementing a MUST or 133 | < SHOULD, or doing something the specification says MUST NOT or SHOULD 134 | < NOT be done may be very subtle. Document authors should take the time 135 | < to elaborate the security implications of not following 136 | < recommendations or requirements as most implementors will not have 137 | < had the benefit of the experience and discussion that produced the 138 | < specification. 139 | --- 140 | > 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 141 | > 2. Clarifying Capitalization of Key Words . . . . . . . . . . . 3 142 | > 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 143 | > 4. Security Considerations . . . . . . . . . . . . . . . . . . . 4 144 | > 5. Normative References . . . . . . . . . . . . . . . . . . . . 4 145 | > Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 4 146 | 96c87 147 | < 8. Acknowledgments 148 | --- 149 | > 1. Introduction 150 | 98,101c89,92 151 | < The definitions of these terms are an amalgam of definitions taken 152 | < from a number of RFCs. In addition, suggestions have been 153 | < incorporated from a number of people including Robert Ullmann, Thomas 154 | < Narten, Neal McBurnett, and Robert Elz. 155 | --- 156 | > RFC 2119 specifies common key words, such as "MUST", "SHOULD", and 157 | > "MAY", that may be used in protocol specifications. It says that the 158 | > key words "are often capitalized," which has caused confusion about 159 | > how to interpret non-capitalized words such as "must" and "should". 160 | 102a94,96 161 | > This document updates RFC 2119 by clarifying that only UPPERCASE 162 | > usage of the key words have the defined special meanings. This 163 | > document is part of BCP 14. 164 | 114c108,114 165 | < Bradner Best Current Practice [Page 2] 166 | --- 167 | > 168 | > 169 | > 170 | > 171 | > 172 | > 173 | > Leiba Best Current Practice [Page 2] 174 | 116c116 175 | < RFC 2119 RFC Key Words March 1997 176 | --- 177 | > RFC 8174 RFC 2119 Clarification May 2017 178 | 119c119 179 | < 9. Author's Address 180 | --- 181 | > 2. Clarifying Capitalization of Key Words 182 | 121,124c121 183 | < Scott Bradner 184 | < Harvard University 185 | < 1350 Mass. Ave. 186 | < Cambridge, MA 02138 187 | --- 188 | > The following change is made to [RFC2119]: 189 | 126c123,150 190 | < phone - +1 617 495 3864 191 | --- 192 | > === OLD === 193 | > In many standards track documents several words are used to signify 194 | > the requirements in the specification. These words are often 195 | > capitalized. This document defines these words as they should be 196 | > interpreted in IETF documents. Authors who follow these guidelines 197 | > should incorporate this phrase near the beginning of their document: 198 | > 199 | > The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 200 | > "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 201 | > document are to be interpreted as described in RFC 2119. 202 | > 203 | > 204 | > === NEW === 205 | > In many IETF documents, several words, when they are in all capitals 206 | > as shown below, are used to signify the requirements in the 207 | > specification. These capitalized words can bring significant clarity 208 | > and consistency to documents because their meanings are well defined. 209 | > This document defines how those words are interpreted in IETF 210 | > documents when the words are in all capitals. 211 | > 212 | > o These words can be used as defined here, but using them is not 213 | > required. Specifically, normative text does not require the use 214 | > of these key words. They are used for clarity and consistency 215 | > when that is what's wanted, but a lot of normative text does not 216 | > use them and is still normative. 217 | > 218 | > o The words have the meanings specified herein only when they are in 219 | > all capitals. 220 | 128c152,153 221 | < email - sob@harvard.edu 222 | --- 223 | > o When these words are not capitalized, they have their normal 224 | > English meanings and are not affected by this document. 225 | 129a155,162 226 | > Authors who follow these guidelines should incorporate this phrase 227 | > near the beginning of their document: 228 | > 229 | > The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 230 | > NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", 231 | > "MAY", and "OPTIONAL" in this document are to be interpreted as 232 | > described in BCP 14 [RFC2119] [RFC8174] when, and only when, they 233 | > appear in all capitals, as shown here. 234 | 130a164 235 | > === END === 236 | 135a170,177 237 | > Leiba Best Current Practice [Page 3] 238 | > 239 | > RFC 8174 RFC 2119 Clarification May 2017 240 | > 241 | > 242 | > 3. IANA Considerations 243 | > 244 | > This document does not require any IANA actions. 245 | 136a179 246 | > 4. Security Considerations 247 | 137a181,182 248 | > This document is purely procedural; there are no related security 249 | > considerations. 250 | 138a184 251 | > 5. Normative References 252 | 139a186,189 253 | > [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 254 | > Requirement Levels", BCP 14, RFC 2119, 255 | > DOI 10.17487/RFC2119, March 1997, 256 | > . 257 | 140a191 258 | > Author's Address 259 | 141a193,194 260 | > Barry Leiba 261 | > Huawei Technologies 262 | 142a196,198 263 | > Phone: +1 646 827 0648 264 | > Email: barryleiba@computer.org 265 | > URI: http://internetmessagingtechnology.org/ 266 | 170c226 267 | < Bradner Best Current Practice [Page 3] 268 | --- 269 | > Leiba Best Current Practice [Page 4] 270 | -------------------------------------------------------------------------------- /reviews/2021-05/analysis/analysis-fapi-part2-20210621.md: -------------------------------------------------------------------------------- 1 | # Overview 2 | 3 | * **Specification:** Financial-grade API Security Profile 1.0 - Part 2: Advanced 4 | * **Baseline Version:** [FAPI Draft06, Part 2](https://openid.net/specs/openid-financial-api-part-2-wd-06.html) 5 | * **Target Version:** [FAPI 1.0 Final, Advanced](https://openid.net/specs/openid-financial-api-part-2-1_0.html) 6 | 7 | This document summarises the changes between FAPI Draft 06 Part 2 and FAPI 1.0 Final Part 2 and the impacts to the Consumer Data Standards. 8 | 9 | Impact analysis is compared against v1.10.0 of the Consumer Data Standards. 10 | 11 | # Summary of key changes 12 | 13 | ## Clients (ADRs) 14 | 15 | * § 5.2.2. (15): Clients MUST send an `aud` claim in the request object that is the OP's issuer identifier URL or an array that contains the OP's issuer identifier URL 16 | 17 | ## OpenID Provider / Authorisation Server (Data Holders) 18 | 19 | * Shall support PKCE when supporting PAR 20 | * Shall only support S256 as the code challenge method 21 | * § 5.2.2. (15): DHs MUST validate that the client sends the `aud` claim in the request object AND that it is or includes the DH's issuer identifier URL 22 | * § 8.5 (3): When `TLS_DHE_RSA_WITH_AES_128_GCM_SHA256` or `TLS_DHE_RSA_WITH_AES_256_GCM_SHA384` are used, requires a key length of **at least** 2048. 23 | 24 | ## Trust Authority (CDR Register) 25 | 26 | * TBA 27 | 28 | # Analysis 29 | 30 | ## 1. Scope 31 | 32 | No differences. 33 | 34 | ## 2. Normative references 35 | 36 | FAPI 1.0 Final Part 2 adds the following normative references, not present in Draft 06: 37 | - RFC7591 - OAuth 2.0 Dynamic Client Registration Protocol 38 | - RFC7592 - OAuth 2.0 Dynamic Client Registration Management Protocol 39 | - BCP195 - Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) 40 | - PAR - OAuth 2.0 Pushed Authorization Requests 41 | - JAR - OAuth 2.0 JWT Secured Authorization Request 42 | 43 | 44 | ## 3. Terms and definitions 45 | FAPI 1.0 Final Part 2 adds the following: 46 | 47 | - ISO29100 ("Information technology — Security techniques — Privacy framework") 48 | 49 | ## 4. Symbols and Abbreviated terms 50 | 51 | No material differences. 52 | 53 | ## 5. Advanced security profile 54 | 55 | No differences. 56 | 57 | ### 5.1. Introduction 58 | 59 | * Moves statements related to ID tokens as detached signatures to section 5.1.1 60 | * Still requires s_hash 61 | * Permits JARM, which is detailed in 5.1.2 62 | 63 | #### 5.1.1. ID Token as Detached Signature 64 | 65 | No differences. 66 | 67 | #### 5.1.2. JWT Secured Authorization Response Mode for OAuth 2.0 (JARM) 68 | 69 | * Moves majority of the statements from section 5.2.5 of Draft 06 into this section 70 | * Defers some statements to the JARM spec - notably recommending the AuthZ Server should advertise supported response modes using the `response_modes_supported` metadata parameter 71 | 72 | ### 5.2. Advanced security provisions 73 | 74 | No differences. 75 | 76 | #### 5.2.1. Introduction 77 | 78 | No material differences. 79 | 80 | #### 5.2.2. Authorization server 81 | 82 | Changes from Draft 06: 83 | 84 | - Part 1 section 5.2.2 clause 7 is not required to be supported (code challenge method for PKCE) 85 | 86 | > shall require RFC7636 with S256 as the code challenge method; 87 | 88 | - § 5.2.2. (1): remains effectively the same 89 | - § 5.2.2. (2): Drops allowed support of "code id_token token" for response_type 90 | - § 5.2.2. (2): For JARM, response_mode is `jwt` 91 | - § 5.2.2. (3): moved to 5.2.2.1 92 | - § 5.2.2. (4): moved to 5.2.2.1 93 | - § 5.2.2. (5): Requires sender constrained tokens 94 | **NOTE:** Currently required, no impact to CDS 95 | - § 5.2.2. (6): Requires MTLS for sender constrained tokens. 96 | **NOTE:** No impact to CDS 97 | - § 5.2.2. (7): Withdraws requirement of LoA 3 for write access. 98 | **NOTE:** This is good in that it helps the CDS align to the Future Directions report of principles based authentication and leveraging risk-based analysis of each action (be it read or write) 99 | - § 5.2.2. (8): moved to 5.2.2.1 100 | - § 5.2.2. (9): moved to 5.2.2.1 101 | - § 5.2.2. (10): Change to requirement implies the AuthZ Server shouldn't reject authorisation requests where parameters are presented outside the request object but SHALL NOT rely on or use any parameters presented outside the request object: 102 | 103 | > shall only use the parameters included in the signed request object passed via the request or request_uri parameter; 104 | 105 | - § 5.2.2. (11): Allows AuthZ Servers to support PAR 106 | **NOTE:** No direct impact to the CDS however FAPI 1.0 depends upon the newest reference to PAR (currently draft 08) 107 | 108 | - § 5.2.2. (12): Withdrawn, not relevant to CDS as this was related to public clients 109 | 110 | - § 5.2.2. (13): 111 | > shall require the request object to contain an `exp` claim that has a **lifetime of no longer than 60 minutes after the `nbf` claim** 112 | 113 | (emphasis added) 114 | 115 | **Breaking Change** - most likely a config change to implementations but some IAM vendors don't currently cater for OOTB configuration of the `exp` validation lifetime. 116 | 117 | - § 5.2.2. (14): No change 118 | - § 5.2.2. (15): **NOTE:** new clause. 119 | 120 | > shall require the `aud` claim in the request object to be, or to be an array containing, the OP's Issuer Identifier URL 121 | 122 | **Breaking Change** - what was a SHOULD in [OIDC] is now a SHALL (must). The audience must be the OP's issuer identifier URL or an array that contains the OP's issuer identifier URL 123 | 124 | [OIDC]: 125 | > The `aud` value SHOULD be or include the OP's Issuer Identifier URL. 126 | 127 | FAPI 1.0: 128 | > shall require the `aud` claim in the request object to be, or to be an array containing, the OP's Issuer Identifier URL 129 | 130 | - § 5.2.2. (16): **NOTE:** new clause. 131 | 132 | Precludes public clients. This does not impact the CDS which currently does not support public clients. 133 | 134 | - § 5.2.2. (17): **NOTE:** new clause. 135 | 136 | - Sets validation time requirement on the `nbf` claim: 137 | 138 | > shall require the request object to contain an `nbf` claim that is no longer than 60 minutes in the past 139 | 140 | - **Breaking Change** 141 | - ADRs must provide the `nbf` claim with a value no longer than 60 minutes prior to the authorisation request 142 | - DHs must validate that the `nbf` claim's value is no longer than 60 minutes from receipt of the authorisation request 143 | 144 | - § 5.2.2. (18): **NOTE:** new change. 145 | - Requires ADRs to use PKCE where PAR is used for authorisation requests 146 | > shall require PAR requests, if supported, to use PKCE (RFC7636) with S256 as the code challenge method. 147 | 148 | - **Breaking Change** Currently PAR is used by the CDS without the need for PKCE. We either need to transition clients towards PKCE and, at least, as a minimum support a period of transition where the ID Token is used as a detached signature rather than PKCE as an alternative. 149 | - Moving towards PKCE support will be a key step in a transition towards FAPI 2.0 supportability 150 | - [PKCE](https://datatracker.ietf.org/doc/html/rfc7636) offers some significant advantages vs hybrid flow most notably simplifying the client implementation 151 | - It may also be worth considering what is required to support ADR software products that require interactivity without browsers or are otherwise using constrained input devices. See [RFC8628](https://datatracker.ietf.org/doc/html/rfc8628) 152 | - **NOTE:** there is a current issue with loss of authorisation code in exchange for tokens causing real production issues in the CDR. Could the introduction of PKCE and the code verifier method alleviate this? Because the `code_challenge_method` is bound to the authorisation code can the `authorization_code` be re-usable where it has not been successfully exchanged. Within a window - say 60 seconds or 5 minutes, the authorisation code can be replayed with the code verifier (as proof the client requesting tokens is the client that initiated the request) and the `authorization_code` is expired upon an `authorization_code` lifetime. If the `authorization_code` is replayed the AuthZ Server would issue the same tokens it did (or thought it had) issued the first time. 153 | 154 | #### 5.2.2.1. ID Token as detached signature 155 | 156 | No material changes. No impacts to the CDS. 157 | 158 | #### 5.2.2.2. JARM 159 | 160 | - § 5.2.2.2. (1): "if the `response_type` value code is used in conjunction with the `response_mode` value `jwt`" then JWT secured authorisation responses are to be used in accordance with [JARM] 161 | 162 | - **Impacts to the CDS.** Currently the CDS does not support JARM. This was originally a finding of the [Fortian review](https://github.com/ConsumerDataStandardsAustralia/standards-maintenance/issues/7) and has also been recommended by the OIDF. 163 | - Should the CDS transition to supporting JARM and PKCE exclusively and not the Hybrid Flow with `response_type` "`code id_token`"? 164 | - Suggest that this change should be adopted. However, in doing so, there would be breaking change and a transition period required. 165 | 166 | #### 5.2.3. Confidential client 167 | 168 | - Collapses some of the original (Draft 06) public client statements into the confidential client section. 169 | 170 | - § 5.2.3. (1): No change from 5.2.4.1 171 | - § 5.2.3. (2): No change 172 | - § 5.2.3. (3): Relased LoA requirement - effectively delegates to the standards specific to the jurisdiction. No changes to the CDS are required because LoAs for read access are already stated. 173 | - § 5.2.3. (4): moved to 5.2.3.1 - only applies when JARM is not used 174 | - § 5.2.3. (5): withdrawn - ADRs must still validate that the acr represents an LoA of sufficient strength as defined by the CDS for the action being taken 175 | - § 5.2.3. (6): withdrawn - Currently the CDS defines authentication methods within the bounds of the Data Holder - clients cannot send or negotiate authentication methods 176 | - § 5.2.3. (7): moved to 5.2.3.1 - only applies when JARM is not used 177 | - § 5.2.3. (8): No change 178 | - § 5.2.3. (9): **NEW** No change unless using PAR, in which case the additional claims outside the request object aren't required. For backwards compatibility, it doesn't hurt if the client continues to send these to the authorisation endpoint. 179 | - § 5.2.3. (10): **NEW** Constrains the `aud` claim value to only be the OP's issuer identifier URL. **NOTE:** this conflicts with 5.2.2 clause 13. **Breaking Change** 180 | - § 5.2.3. (11): **NEW** Client requirement for lifetime of the `exp`. Note that to avoid rejection from the AuthZ Server, it is advisable that a value slightly shorter than 60 min is chosen otherwise there is a likelihood of AuthZ Server rejection at the boundary of the time limit. **Breaking Change** 181 | - § 5.2.3. (12): **NEW** Says this has moved to 5.2.3.1 but there wasn't a clause 12 in Draft 06 182 | - § 5.2.3. (13): **NEW** Says this has moved to 5.2.3.1 but there wasn't a clause 12 in Draft 06 183 | - § 5.2.3. (14): **NEW** Clients must send an nbf claim in the requst. **Breaking change** 184 | - § 5.2.3. (15): **NEW** Requires PKCE for PAR using code challenge method S256. **Breaking change** In PAR Draft 01 this was implied but not mandated. 185 | - § 5.2.3. (16): **NEW** Client must always send the client_id to the authorisation endpoint even when using PAR. This is not an impact to the CDS - it was already covered by the CDS. 186 | 187 | #### 5.2.3.1. ID Token as detached signature 188 | 189 | No material changes. 190 | 191 | #### 5.2.3.2. JARM 192 | 193 | - § 5.2.3.2. (1): When "`response_type` value `code` is used in conjunction with the `response_mode` value `jwt`" then the client must verify the authorisation response in accordance with the [JARM] spec. 194 | 195 | **Breaking Change** Will impact ADR client implementations. 196 | 197 | #### 5.2.4. (withdrawn) 198 | 199 | Covered by 5.2.3.1 200 | 201 | #### 5.2.5. (withdrawn) 202 | 203 | Covered by 5.2.3.2 204 | 205 | ## 6. Accessing protected resources (using tokens) 206 | 207 | No changes. 208 | 209 | ### 6.1. Introduction 210 | 211 | No changes. 212 | 213 | ### 6.2. Advanced access provisions 214 | 215 | No changes. 216 | 217 | ### 6.2.1. Protected resources provisions 218 | 219 | No material changes. 220 | 221 | ### 6.2.2. Client provisions 222 | 223 | No material changes. 224 | 225 | ## 7. (Withdrawn) 226 | 227 | Request object endpoint is retired and replaced by PAR. No impact to the CDS. 228 | 229 | ## 8. Security considerations 230 | 231 | No changes. 232 | 233 | ### 8.1. Introduction 234 | 235 | No material changes. 236 | 237 | ### 8.2. Uncertainty of resource server handling of access tokens 238 | 239 | - Support for oAuth token binding [OAUTB] has been dropped. This doesn't affect the CDS. 240 | 241 | ### 8.3. Attacks using weak binding of authorization server endpoints 242 | 243 | No changes. 244 | 245 | #### 8.3.1. Introduction 246 | 247 | No material changes. 248 | 249 | #### 8.3.2. Client credential and authorization code phishing at token endpoint 250 | 251 | * Drops reference to [OAUTB], otherwise no material changes 252 | 253 | #### 8.3.3. Identity provider (IdP) mix-up attack 254 | 255 | - Provides reference to prior oAuth security analysis (2016) 256 | - Adds reference to JARM, not just Hybrid Flow 257 | 258 | #### 8.3.4. (removed) 259 | 260 | - The removal of this section does not give rise to impacts to the CDS. 261 | 262 | #### 8.3.5. Access token phishing 263 | 264 | No material changes. 265 | 266 | ### 8.4. Attacks that modify authorization requests and responses 267 | 268 | No changes. 269 | 270 | #### 8.4.1. Introduction 271 | 272 | No material changes. 273 | 274 | #### 8.4.2. Authorization request parameter injection attack 275 | 276 | No material changes. 277 | 278 | #### 8.4.3. Authorization response parameter injection attack 279 | 280 | - Adds JARM 281 | 282 | ### 8.5. TLS considerations 283 | 284 | - § 8.5 (1): Where TLS 1.3+ is used, no cipher constraints are defined. For TLS 1.2 and below, the constrained list of ciphers remains. No impact to the CDS. 285 | - § 8.5 (3): Requires a key length of **at least** 2048 when `TLS_DHE_RSA_WITH_AES_128_GCM_SHA256` or `TLS_DHE_RSA_WITH_AES_256_GCM_SHA384` are used. **Breaking Change** This may impact implementation choices currently chosen by Data Holders. Requires confirmation. 286 | 287 | ### 8.6. Algorithm considerations 288 | 289 | No change. 290 | 291 | #### 8.6.1. Encryption algorithm considerations 292 | **New section** 293 | 294 | - § 8.6.1 (1): Clients and Authorisation Servers are not allowed to use the `RSA1_5` algorithm 295 | 296 | ### 8.7. Incomplete or incorrect implementations of the specifications 297 | 298 | No material changes. 299 | 300 | ### 8.8. Session Fixation 301 | **New section** 302 | 303 | No material impact. The CDR also adds additional controls by requiring only _accredited_ third parties to be allowed to initiate authorisation requests to DHs. [PAR] increases this security for Authorisation Servers because client authentication can be executed before receipt of the authorisation request. 304 | 305 | ### 8.9. JWKS URIs 306 | **New section** 307 | 308 | - § 8.9 (1) requires that `jwks_uri` endpoints shall be served over TLS. No impact to the CDS 309 | - § 8.9 (2) recommends that JOSE headers for `x5u` and `jku` should not be used. **Breaking Change** May impact some implementations - requires verification 310 | - § 8.9 (3) does not allow the same kid to be used by multiple keys within a JWKS 311 | 312 | ### 8.10. Multiple clients sharing the same key 313 | **New section** 314 | 315 | - Clarifies the risks of using certificates issued at the organisation level to protect many clients (ADR software products). **Impact** It may be worth adding a statement in the CDR Register that ADR clients are recommended to have separate certificates for each software product. Consultation should be conducted as to whether this be made a MUST, not just a SHOULD 316 | 317 | 318 | ### 8.11. Duplicate Key Identifiers 319 | **New section** 320 | 321 | - No impact to the CDR Register or CDS. A similar statement is currently used by the CDR Register. **Impact** The CDR Register standards would be best to remove their statements to similar effect and reference section 8.11 of FAPI Advanced. 322 | 323 | ## 9. Privacy considerations 324 | 325 | Informational, no material impact. 326 | 327 | ### 9.1. Introduction 328 | 329 | Informational, no material impact. 330 | -------------------------------------------------------------------------------- /reviews/2021-05/analysis/analysis-fapi-part1-20210614.md: -------------------------------------------------------------------------------- 1 | # Overview 2 | 3 | * **Specification:** Financial-grade API Security Profile 1.0 - Part 1: Baseline 4 | * **Baseline Version:** [FAPI Draft06, Part 1](https://openid.net/specs/openid-financial-api-part-1-wd-06.html) 5 | * **Target Version:** [FAPI 1.0 Final, Baseline](https://openid.net/specs/openid-financial-api-part-1-1_0.html) 6 | 7 | This document summarises the changes between FAPI Draft 06 Part 1 and FAPI 1.0 Final Part 1 and the impacts to the Consumer Data Standards. 8 | 9 | Impact analysis is compared against v1.10.0 of the Consumer Data Standards. 10 | 11 | # Summary of key changes 12 | 13 | ## Clients (ADRs) 14 | 15 | * § 5.2.3 (10) **token response `scope` value** shall verify that the scope received in the token response is either an exact match, or contains a subset of the scope sent in the authorization request 16 | * § 6.2.1 (9): **Value of Content-Type header** shall send the Content-type HTTP header Content-Type: application/json if applicable; 17 | 18 | ## OpenID Provider / Authorisation Server (Data Holders) 19 | 20 | The following changes were identified as impacts to Data Holders. The course of action is to be discussed with the community prior to recommendation. 21 | 22 | * § 5.2.2. (15): The DH only returns scopes where the list granted is different to the list the client requested 23 | * § 6.2.1. (9): **Validation of Content-Type header** shall send the Content-type HTTP header `Content-Type: application/json` if applicable; 24 | * 6.2.1. (13): **`x-fapi-customer-ip-address`** shall not reject requests with a `x-fapi-customer-ip-address` header containing a valid IPv4 or IPv6 address. 25 | * § 7.1.: **TLS and DNSSEC considerations** Endpoints for the use by web browsers should use mechanisms to ensure that connections cannot be downgraded using TLS Stripping attacks 26 | * § 7.1.: **TLS and DNSSEC considerations** all endpoints should additionally use DNSSEC to protect against DNS spoofing attacks that can lead to the issuance of rogue domain-validated TLS certificates 27 | * § 7.7.: **Data Holder Registration** Organizations who need to support multiple "brands" with individual authorization endpoints from a single Authorization Server deployment shall use a separate `issuer` per brand. 28 | 29 | ### § 5.2.2 (15) Scope response 30 | There are benefits to *always* returning the list of scopes in the token response because the CDR deals with the phasing of obligations yet uses the Information Security profile to convey some of this context to ADRs. Until such time that RAR is supported, it may be preferable to retain the requirement that scopes are *always* returned to ADR clients. This will benefit ADRs in that there is no breaking change for this. 31 | 32 | Community consultation on the CDS requiring scopes to be returned (always) to improve reliability for clients. 33 | 34 | ### Content-Type header 35 | Determination is either to retain more flexible support as a constraint to FAPI 1 or a breaking change to clients to send Content-Type without charset. 36 | 37 | ## Trust Authority (CDR Register) 38 | * § 7.7.: **Data Holder Registration** Organizations who need to support multiple "brands" with individual authorization endpoints from a single Authorization Server deployment shall use a separate `issuer` per brand. 39 | 40 | **Note:** Although this does not require the AS to return scopes when receiving a call via the backchannel from an integrity protected request, per section 5.1 of RFC6749 (https://datatracker.ietf.org/doc/html/rfc6749#section-5.1) the scope value is only “OPTIONAL, if identical to the scope requested by the client; otherwise, REQUIRED.“ suggesting that at the very least the AS return the granted scopes where they differ to what was requested. In this situation, clients also need to test the absence of the scopes in the response inferring _all_ scopes requested were granted. There is clearly an onus on the DH to only grant the client the scopes that it supports and not additional scopes it doesn't support. With the phasing of obligations in the ecosystem creates something of an undefined behaviour. 41 | 42 | For this reason, it is probably worth the CDS explicitly requiring the scopes be returned because this removes ambiguity for clients without having to have conditional logic. The DH can be directed to only respond with scopes that it currently supports per phasing obligations. 43 | 44 | **Note 2:** This is no longer an issue when RAR (Rich Authorisation Requests) and Grant Management are supported per FAPI 2.0 because the client has a reliable way to get _all_ of the details of the authorisation from the AS including scopes and other rich authorisation details 45 | 46 | **Note 3:** The DSB has an open DP on participant capability discovery that is intended to better support clients discovering obligations and capabilities of the DHs (e.g. phasing obligations). This is not OIDD metadata but instead intends to describe specific capabilities and functionalities of the DH. By introducing this, clients would have a mechanism to ascertain when a DH supports future obligations and can update authorisation requests when new scopes become available (contingent on the consumer's consent). 47 | 48 | ## Conformance Testing 49 | 50 | - § 5.2.2 (15) 51 | - § 6.2.1. (9) 52 | - § 6.2.1. (13) 53 | - § 5.2.3. (10) 54 | - § 7.7. 55 | 56 | # Analysis 57 | 58 | ## 1. Scope 59 | 60 | No differences. 61 | 62 | ## 2. Normative References 63 | 64 | The 1.0 Final spec adds two additional normative references: 65 | * OIDD - [OpenID Connect Discovery 1.0 incorporating errata set 1](http://openid.net/specs/openid-connect-discovery-1_0.html) 66 | * RFC7231 - [Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content](https://tools.ietf.org/html/rfc7231) 67 | 68 | **NOTE:** Both are currently references in the CDS as normative and informative references respectively. These changes arising in v1.0 Final spec create no additional impact to the CDS. 69 | 70 | ## 3. Terms and definitions 71 | 72 | No material differences. 73 | 74 | ## 4. Symbols and abbreviated terms 75 | 76 | ## 5. Baseline security profile 77 | 78 | ### 5.1. Introduction 79 | 80 | No material differences. 81 | **NOTE:** Part 1 is now defined as baseline security profile rather than the read-only profile to better describe the core set of security provisions applicable to read and write InfoSec. 82 | 83 | ### 5.2. Baseline security provisions 84 | 85 | No differences. 86 | 87 | #### 5.2.1. Introduction 88 | 89 | No material differences. 90 | 91 | #### 5.2.2. Authorization server 92 | * § 5.2.2. (11): Delegates required levels of assurance to the downstream jurisdiction / standards implementation where previously this was LoA2 or above. **NOTE:** **This will not impact the CDS which requires LoA2 or above** 93 | * § 5.2.2. (12): Changes the use of the word 'consent' to be 'approval' noting consent has legal connotations. **NOTE:** **This will not impact the CDS** 94 | * § 5.2.2. (13): Previous authorisation codes MUST be rejected (previously this was a should). **NOTE:** **This will not impact the CDS as it is already required** 95 | > shall reject an authorization code (Section 1.3.1 of RFC6749) if it has been previously used 96 | 97 | * § 5.2.2. (22): Qualifies the requirements to follow [OIDD] for discovery metadata. **NOTE:** **This will not impact the CDS, already required** 98 | * Recommends the use of refresh tokens rather than the practice of long-lived access tokens for public and private clients. **NOTE:** **This will have not impact the CDS, already required** 99 | 100 | * § 5.2.2 (15): changes the requirement to such that scopes must be returned with the access token if "the request was passed in the front channel and was not integrity protected". This will likely have breaking impacts to ADR clients that rely on the scopes being present when the access token is requested via the back channel. It will mean that clients need to obtain the authorised list of scopes by calling the token endpoint or token introspection endpoint. The point of "integrity protected" also warrants discussion. There are significant benefits in the AS returning the authorised list of scopes to the client to ascertain the final consumer's directives for consent. Where a DH does not support a scope, the list will be a subset of what the client originally requested. 101 | 102 | > shall return the list of granted scopes with the issued access token if the request was passed in the front channel and was not integrity protected; 103 | 104 | **Note:** Although this does not require the AS to return scopes when receiving a call via the backchannel from an integrity protected request, per section 5.1 of RFC6749 (https://datatracker.ietf.org/doc/html/rfc6749#section-5.1) the scope value is only “OPTIONAL, if identical to the scope requested by the client; otherwise, REQUIRED.“ suggesting that at the very least the AS return the granted scopes where they differ to what was requested. In this situation, clients also need to test the absence of the scopes in the response inferring _all_ scopes requested were granted. There is clearly an onus on the DH to only grant the client the scopes that it supports and not additional scopes it doesn't support. With the phasing of obligations in the ecosystem creates something of an undefined behaviour. 105 | 106 | For this reason, it is probably worth the CDS explicitly requiring the scopes be returned because this removes ambiguity for clients without having to have conditional logic. The DH can be directed to only respond with scopes that it currently supports per phasing obligations. 107 | 108 | **Note 2:** This is no longer an issue when RAR (Rich Authorisation Requests) and Grant Management are supported per FAPI 2.0 because the client has a reliable way to get _all_ of the details of the authorisation from the AS including scopes and other rich authorisation details 109 | 110 | **Note 3:** The DSB has an open DP on participant capability discovery that is intended to better support clients discovering obligations and capabilities of the DHs (e.g. phasing obligations). This is not OIDD metadata but instead intends to describe specific capabilities and functionalities of the DH. By introducing this, clients would have a mechanism to ascertain when a DH supports future obligations and can update authorisation requests when new scopes become available (contingent on the consumer's consent). 111 | 112 | #### 5.2.2.1. Returning authenticated user's identifier 113 | Was "5.2.2.1. Returning authenticated user's identifier Authorization server" in Draft 06 114 | 115 | No material differences. 116 | 117 | #### 5.2.2.2. Client requesting openid scope 118 | (*New section*) 119 | 120 | > If the client requests the openid scope, the authorization server 121 | > - shall require the nonce parameter defined in Section 3.1.2.1 of OIDC in the authentication request. 122 | 123 | **NOTE:** This was previously covered in Draft 06 Part 1 in section "5.2.3 Public Client" which section "5.2.4 Confidential Client" inherits. 124 | 125 | #### 5.2.2.3. Clients not requesting openid scope 126 | (*New section*) 127 | 128 | No applicable. 129 | 130 | #### 5.2.3. Public client 131 | **Note:** This section is required as the baseline for confidential clients. 132 | 133 | - § 5.2.3. (5): Requirement #5 has been withdrawn: 134 | 135 | > shall adhere to the best practice stated by [BCP212]; 136 | 137 | - Adds two new requirements: 138 | 139 | > 10. shall verify that the scope received in the token response is either an exact match, or contains a subset of the scope sent in the authorization request; and 140 | > 11. shall only use Authorization Server metadata obtained from the metadata document published by the Authorization Server at its well known endpoint as defined in OIDD or RFC8414. 141 | 142 | - § 5.2.3 (10): Requires token response scope list to be validated as a subset or equal to the scopes requested in the authorisation request 143 | 144 | **Note:** Although this now requires clients to explicitly validate the scopes returned 5.2.2 (15) essentially overrides this from the perspective that the CDR uses token responses in the back channel that integrity protected. In this situation, ADR clients would not receive a list of scopes and this leaves consent in a somewhat ambigous state. There is also clearly an onus on the DH to only grant the client the scopes that it supports and not additional scopes it doesn't support. With the phasing of obligations in the ecosystem creates something of an undefined behaviour. 145 | 146 | For this reason, it is probably worth the CDS explicitly requiring the scopes be returned because this removes ambiguity for clients without having to have conditional logic. The DH can be directed to only respond with scopes that it currently supports per phasing obligations. 147 | 148 | **Note 2:** This is no longer an issue when RAR (Rich Authorisation Requests) and Grant Management are supported per FAPI 2.0 because the client has a reliable way to get _all_ of the details of the authorisation from the AS including scopes and other rich authorisation details 149 | 150 | **Note 3:** The DSB has an open DP on participant capability discovery that is intended to better support clients discovering obligations and capabilities of the DHs (e.g. phasing obligations). This is not OIDD metadata but instead intends to describe specific capabilities and functionalities of the DH. By introducing this, clients would have a mechanism to ascertain when a DH supports future obligations and can update authorisation requests when new scopes become available (contingent on the consumer's consent). 151 | 152 | #### 5.2.4. Confidential client 153 | 154 | No differences. 155 | 156 | ## 6. Accessing Protected Resources 157 | No differences. 158 | 159 | ### 6.1. Introduction 160 | No differences. 161 | 162 | ### 6.2. Baseline access provisions 163 | No differences. 164 | 165 | #### 6.2.1. Protected resources provisions 166 | - § 6.2.1. (9): Content-type header requirement has changed from `Content-Type: application/json; charset=UTF-8` to `Content-Type: application/json`. 167 | 168 | The CDS requires conformance to [RFC7231] which means the content type's media type must be `application/json` but `Content-Type` may include wildcard, and charsets. The interpretation is currently clear in the CDS that a DH can't reject a request where the `Content-Type` value is well-formed according to [RFC7231]. 169 | 170 | **CDS requirement** which requires consultation. 171 | 172 | - § 6.2.1. (13) Adds additional requirement: 173 | 174 | > shall not reject requests with a `x-fapi-customer-ip-address` header containing a valid IPv4 or IPv6 address. 175 | 176 | This means that DHs cannot reject requests based on the contents of the `x-fapi-customer-ip-address` is a valid IPv4 or IPv6. That said, this may be a value inspected by the DHs WAF and rejections made based on its contents or the IP address of the requesting client for one or more security reasons. 177 | 178 | #### 6.2.2. Client provisions 179 | 180 | No material differences. 181 | 182 | 183 | ## 7. Security considerations 184 | 185 | No differences. 186 | 187 | ### 7.1. TLS and DNSSEC considerations 188 | 189 | * FAPI 1.0 Final includes statements regarding prevention of TLS stripping attacks. 190 | 191 | > Endpoints for the use by web browsers should use mechanisms to ensure that connections cannot be downgraded using TLS Stripping attacks. A preloaded HTTP Strict Transport Security policy (see PRELOAD and RFC6797) can be used for this purpose. Some top-level domains, like .bank and .insurance, have set such a policy and therefore protect all second-level domains below them. 192 | > 193 | > For a comprehensive protection against network attackers, all endpoints should additionally use DNSSEC to protect against DNS spoofing attacks that can lead to the issuance of rogue domain-validated TLS certificates. 194 | > 195 | > NOTE: Even if an endpoint uses only organization validated (OV) or extended validation (EV) TLS certificates, rogue domain-validated certificates can be used to impersonate the endpoints and conduct man-in-the-middle attacks. CAA records RFC8659 can help to mitigate this risk. 196 | 197 | * Expected that the CDS will defer to FAPI 1.0 specs in this regard. DH feedback is warranted to understand any impacts DHs foresee to existing implementations. 198 | 199 | ### 7.2. Message source authentication failure 200 | 201 | No material differences. 202 | 203 | ### 7.3. Message integrity protection failure 204 | 205 | No material differences. 206 | 207 | ### 7.4. Message containment failure 208 | 209 | No differences. 210 | 211 | #### 7.4.1. Authorization request and response 212 | 213 | No differences. 214 | 215 | #### 7.4.2. Token request and response 216 | 217 | No differences. 218 | 219 | #### 7.4.3. Resource request and response 220 | 221 | No material differences. 222 | 223 | ### 7.5. Native Apps 224 | 225 | No material differences. 226 | 227 | ### 7.6. Incomplete or incorrect implementations of the specifications 228 | 229 | No material differences. 230 | 231 | ### 7.7. Discovery & Multiple Brands 232 | (*New section*) 233 | 234 | * Multiple brands as separate tenants under one Authorization Server must use separate issuers. This may be done at the domain or path level. 235 | 236 | ## 8. Privacy considerations 237 | 238 | Recommendations for privacy impact assessments have been removed. 239 | 240 | ### 8.1. Introduction 241 | 242 | Provides useful statements regarding privacy, security and consent. No material differences related to the standards. 243 | -------------------------------------------------------------------------------- /reviews/2021-05/raw/docs/cds_admin.json: -------------------------------------------------------------------------------- 1 | { 2 | "swagger": "2.0", 3 | "info": { 4 | "title": "Consumer Data Standards Administration End Points", 5 | "description": "Data Holder Consumer Data Standards Administration End Points", 6 | "version": "1.10.0", 7 | "contact": { 8 | "name": "Consumer Data Standards Administration End Points", 9 | "url": "https://consumerdatastandards.org.au/", 10 | "email": "cdr-data61@csiro.au" 11 | }, 12 | "license": { 13 | "name": "MIT License", 14 | "url": "https://opensource.org/licenses/MIT" 15 | } 16 | }, 17 | "host": "data.holder.com.au", 18 | "basePath": "/cds-au/v1", 19 | "schemes": [ 20 | "https" 21 | ], 22 | "consumes": [ 23 | "application/json" 24 | ], 25 | "produces": [ 26 | "application/json" 27 | ], 28 | "paths": { 29 | "/admin/register/metadata": { 30 | "post": { 31 | "summary": "Metadata Update", 32 | "description": "Indicate that a critical update to the metadata for Accredited Data Recipients has been made and should be obtained", 33 | "operationId": "metadataUpdate", 34 | "tags": [ 35 | "Admin", 36 | "Register" 37 | ], 38 | "x-scopes": [ 39 | "admin:metadata:update" 40 | ], 41 | "x-restricted-access": true, 42 | "parameters": [ 43 | { 44 | "in": "body", 45 | "name": "action", 46 | "required": true, 47 | "schema": { 48 | "$ref": "#/definitions/RequestMetaDataUpdate" 49 | } 50 | }, 51 | { 52 | "$ref": "#/parameters/RequestHeader_x-v" 53 | }, 54 | { 55 | "$ref": "#/parameters/RequestHeader_x-min-v" 56 | } 57 | ], 58 | "responses": { 59 | "200": { 60 | "description": "Success", 61 | "headers": { 62 | "x-v": { 63 | "type": "string", 64 | "description": "The [version](#response-headers) of the API end point that the data holder has responded with." 65 | } 66 | } 67 | }, 68 | "4xx": { 69 | "description": "The following error codes MUST be supported:

[400 - Invalid Field](#error-400-field-invalid)
[400 - Invalid Version](#error-400-header-invalid-version)
[406 - Unsupported Version](#error-406-header-unsupported-version)

", 70 | "schema": { 71 | "$ref": "#/definitions/ResponseErrorListV2" 72 | } 73 | } 74 | }, 75 | "x-version": "1" 76 | } 77 | }, 78 | "/admin/metrics": { 79 | "get": { 80 | "summary": "Get Metrics", 81 | "description": "This end point allows the ACCC to obtain operational statistics from the Data Holder on the operation of their CDR compliant implementation. The statistics obtainable from this end point are determined by the non-functional requirements for the CDR regime.\n\nNOTE: This version must be implemented by **July 31st 2021**\n\nObsolete versions: [v1](includes/obsolete/get-metrics-v1.html). If the Data Holder supports private_key_jwt client authentication they MUST validate the scope.", 82 | "operationId": "getMetrics", 83 | "x-scopes": [ 84 | "admin:metrics.basic:read" 85 | ], 86 | "x-restricted-access": true, 87 | "tags": [ 88 | "Admin", 89 | "Metrics" 90 | ], 91 | "parameters": [ 92 | { 93 | "name": "period", 94 | "in": "query", 95 | "type": "string", 96 | "description": "The period of metrics to be requested. Values can be CURRENT (meaning metrics for current day), HISTORIC (meaning metrics for previous days or months) or ALL. If absent the default is ALL.", 97 | "enum": [ 98 | "CURRENT", 99 | "HISTORIC", 100 | "ALL" 101 | ], 102 | "default": "ALL" 103 | }, 104 | { 105 | "$ref": "#/parameters/RequestHeader_x-v" 106 | }, 107 | { 108 | "$ref": "#/parameters/RequestHeader_x-min-v" 109 | } 110 | ], 111 | "responses": { 112 | "200": { 113 | "description": "Success", 114 | "headers": { 115 | "x-v": { 116 | "type": "string", 117 | "description": "The [version](#response-headers) of the API end point that the data holder has responded with." 118 | } 119 | }, 120 | "schema": { 121 | "$ref": "#/definitions/ResponseMetricsListV2" 122 | } 123 | }, 124 | "4xx": { 125 | "description": "The following error codes MUST be supported:

[400 - Invalid Field](#error-400-field-invalid)
[400 - Invalid Version](#error-400-header-invalid-version)
[406 - Unsupported Version](#error-406-header-unsupported-version)

", 126 | "schema": { 127 | "$ref": "#/definitions/ResponseErrorListV2" 128 | } 129 | } 130 | }, 131 | "x-version": "2" 132 | } 133 | } 134 | }, 135 | "parameters": { 136 | "RequestHeader_x-v": { 137 | "name": "x-v", 138 | "description": "Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between [x-min-v](#request-headers) and [x-v](#request-headers). If the value of [x-min-v](#request-headers) is equal to or higher than the value of [x-v](#request-headers) then the [x-min-v](#request-headers) header should be treated as absent. If all versions requested are not supported then the data holder should respond with a 406 Not Acceptable. See [HTTP Headers](#request-headers)", 139 | "in": "header", 140 | "type": "string", 141 | "required": true 142 | }, 143 | "RequestHeader_x-min-v": { 144 | "name": "x-min-v", 145 | "description": "Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between [x-min-v](#request-headers) and [x-v](#request-headers). If all versions requested are not supported then the data holder should respond with a 406 Not Acceptable.", 146 | "in": "header", 147 | "type": "string" 148 | } 149 | }, 150 | "definitions": { 151 | "RequestMetaDataUpdate": { 152 | "type": "object", 153 | "required": [ 154 | "data" 155 | ], 156 | "properties": { 157 | "data": { 158 | "type": "object", 159 | "required": [ 160 | "action" 161 | ], 162 | "properties": { 163 | "action": { 164 | "type": "string", 165 | "description": "The action to take for the meta data. At the moment the only option is REFRESH which requires the data holder to call the ACCC to refresh meta data as soon as practicable", 166 | "enum": [ 167 | "REFRESH" 168 | ], 169 | "default": "REFRESH" 170 | } 171 | } 172 | }, 173 | "meta": { 174 | "$ref": "#/definitions/Meta" 175 | } 176 | } 177 | }, 178 | "ResponseMetricsListV2": { 179 | "type": "object", 180 | "required": [ 181 | "data", 182 | "links" 183 | ], 184 | "properties": { 185 | "data": { 186 | "type": "object", 187 | "required": [ 188 | "requestTime", 189 | "availability", 190 | "performance", 191 | "invocations", 192 | "averageResponse", 193 | "sessionCount", 194 | "averageTps", 195 | "peakTps", 196 | "errors", 197 | "rejections", 198 | "customerCount", 199 | "recipientCount" 200 | ], 201 | "properties": { 202 | "requestTime": { 203 | "type": "string", 204 | "description": "The date and time that the metrics in this payload were requested.", 205 | "x-cds-type": "DateTimeString" 206 | }, 207 | "availability": { 208 | "$ref": "#/definitions/AvailabilityMetrics" 209 | }, 210 | "performance": { 211 | "$ref": "#/definitions/PerformanceMetrics" 212 | }, 213 | "invocations": { 214 | "$ref": "#/definitions/InvocationMetrics" 215 | }, 216 | "averageResponse": { 217 | "$ref": "#/definitions/AverageResponseMetrics" 218 | }, 219 | "sessionCount": { 220 | "$ref": "#/definitions/SessionCountMetrics" 221 | }, 222 | "averageTps": { 223 | "$ref": "#/definitions/AverageTPSMetrics" 224 | }, 225 | "peakTps": { 226 | "$ref": "#/definitions/PeakTPSMetrics" 227 | }, 228 | "errors": { 229 | "$ref": "#/definitions/ErrorMetrics" 230 | }, 231 | "rejections": { 232 | "$ref": "#/definitions/RejectionMetricsV2" 233 | }, 234 | "customerCount": { 235 | "type": "integer", 236 | "description": "Number of customers with active authorisations at the time of the call" 237 | }, 238 | "recipientCount": { 239 | "type": "integer", 240 | "description": "Number of data recipients with active authorisations at the time of the call" 241 | } 242 | } 243 | }, 244 | "links": { 245 | "$ref": "#/definitions/Links" 246 | }, 247 | "meta": { 248 | "$ref": "#/definitions/Meta" 249 | } 250 | } 251 | }, 252 | "AvailabilityMetrics": { 253 | "type": "object", 254 | "description": "Percentage availability of the CDR platform over time", 255 | "x-conditional": [ 256 | "currentMonth", 257 | "previousMonths" 258 | ], 259 | "properties": { 260 | "currentMonth": { 261 | "type": "number", 262 | "description": "Percentage availability of the CDR platform so far for the current calendar month. 0.0 means 0%. 1.0 means 100%." 263 | }, 264 | "previousMonths": { 265 | "description": "Percentage availability of the CDR platform for previous calendar months. The first element indicates the last month and so on. A maximum of twelve entries is required if available. 0.0 means 0%. 1.0 means 100%.", 266 | "type": "array", 267 | "items": { 268 | "type": "number" 269 | } 270 | } 271 | } 272 | }, 273 | "PerformanceMetrics": { 274 | "type": "object", 275 | "description": "Percentage of calls within the performance thresholds", 276 | "x-conditional": [ 277 | "currentDay", 278 | "previousDays" 279 | ], 280 | "properties": { 281 | "currentDay": { 282 | "type": "number", 283 | "description": "Percentage of calls within the performance threshold for the current day. 0.0 means 0%. 1.0 means 100%" 284 | }, 285 | "previousDays": { 286 | "type": "array", 287 | "description": "Percentage of calls within the performance threshold for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available. 0.0 means 0%. 1.0 means 100%", 288 | "items": { 289 | "type": "number" 290 | } 291 | } 292 | } 293 | }, 294 | "InvocationMetrics": { 295 | "description": "Number of API calls in each performance tier over time", 296 | "type": "object", 297 | "required": [ 298 | "unauthenticated", 299 | "highPriority", 300 | "lowPriority", 301 | "unattended", 302 | "largePayload" 303 | ], 304 | "properties": { 305 | "unauthenticated": { 306 | "description": "API call counts for the unauthenticated tier", 307 | "x-conditional": [ 308 | "currentDay", 309 | "previousDays" 310 | ], 311 | "properties": { 312 | "currentDay": { 313 | "type": "number", 314 | "description": "API call counts for current day" 315 | }, 316 | "previousDays": { 317 | "type": "array", 318 | "description": "API call counts for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available", 319 | "items": { 320 | "type": "number" 321 | } 322 | } 323 | } 324 | }, 325 | "highPriority": { 326 | "description": "API call counts for the high priority tier", 327 | "x-conditional": [ 328 | "currentDay", 329 | "previousDays" 330 | ], 331 | "properties": { 332 | "currentDay": { 333 | "type": "number", 334 | "description": "API call counts for current day" 335 | }, 336 | "previousDays": { 337 | "type": "array", 338 | "description": "API call counts for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available", 339 | "items": { 340 | "type": "number" 341 | } 342 | } 343 | } 344 | }, 345 | "lowPriority": { 346 | "description": "API call counts for the low priority tier", 347 | "x-conditional": [ 348 | "currentDay", 349 | "previousDays" 350 | ], 351 | "properties": { 352 | "currentDay": { 353 | "type": "number", 354 | "description": "API call counts for current day" 355 | }, 356 | "previousDays": { 357 | "type": "array", 358 | "description": "API call counts for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available", 359 | "items": { 360 | "type": "number" 361 | } 362 | } 363 | } 364 | }, 365 | "unattended": { 366 | "description": "API call counts for the unattended tier", 367 | "x-conditional": [ 368 | "currentDay", 369 | "previousDays" 370 | ], 371 | "properties": { 372 | "currentDay": { 373 | "type": "number", 374 | "description": "API call counts for current day" 375 | }, 376 | "previousDays": { 377 | "type": "array", 378 | "description": "API call counts for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available", 379 | "items": { 380 | "type": "number" 381 | } 382 | } 383 | } 384 | }, 385 | "largePayload": { 386 | "description": "API call counts for the large payload tier", 387 | "x-conditional": [ 388 | "currentDay", 389 | "previousDays" 390 | ], 391 | "properties": { 392 | "currentDay": { 393 | "type": "number", 394 | "description": "API call counts for current day" 395 | }, 396 | "previousDays": { 397 | "type": "array", 398 | "description": "API call counts for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available", 399 | "items": { 400 | "type": "number" 401 | } 402 | } 403 | } 404 | } 405 | } 406 | }, 407 | "AverageResponseMetrics": { 408 | "description": "Average response time in seconds, at millisecond resolution, within each performance tier", 409 | "type": "object", 410 | "required": [ 411 | "unauthenticated", 412 | "highPriority", 413 | "lowPriority", 414 | "unattended", 415 | "largePayload" 416 | ], 417 | "properties": { 418 | "unauthenticated": { 419 | "description": "Average response time for the unauthenticated tier", 420 | "x-conditional": [ 421 | "currentDay", 422 | "previousDays" 423 | ], 424 | "properties": { 425 | "currentDay": { 426 | "type": "number", 427 | "description": "Average response time for current day" 428 | }, 429 | "previousDays": { 430 | "type": "array", 431 | "description": "Average response time for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available.", 432 | "items": { 433 | "type": "number" 434 | } 435 | } 436 | } 437 | }, 438 | "highPriority": { 439 | "description": "Average response time for the high priority tier", 440 | "x-conditional": [ 441 | "currentDay", 442 | "previousDays" 443 | ], 444 | "properties": { 445 | "currentDay": { 446 | "type": "number", 447 | "description": "Average response time for current day" 448 | }, 449 | "previousDays": { 450 | "type": "array", 451 | "description": "Average response time for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available.", 452 | "items": { 453 | "type": "number" 454 | } 455 | } 456 | } 457 | }, 458 | "lowPriority": { 459 | "description": "Average response time for the low priority tier", 460 | "x-conditional": [ 461 | "currentDay", 462 | "previousDays" 463 | ], 464 | "properties": { 465 | "currentDay": { 466 | "type": "number", 467 | "description": "Average response time for current day" 468 | }, 469 | "previousDays": { 470 | "type": "array", 471 | "description": "Average response time for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available.", 472 | "items": { 473 | "type": "number" 474 | } 475 | } 476 | } 477 | }, 478 | "unattended": { 479 | "description": "Average response time for the unattended tier", 480 | "x-conditional": [ 481 | "currentDay", 482 | "previousDays" 483 | ], 484 | "properties": { 485 | "currentDay": { 486 | "type": "number", 487 | "description": "Average response time for current day" 488 | }, 489 | "previousDays": { 490 | "type": "array", 491 | "description": "Average response time for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available.", 492 | "items": { 493 | "type": "number" 494 | } 495 | } 496 | } 497 | }, 498 | "largePayload": { 499 | "description": "Average response time for the large payload tier", 500 | "x-conditional": [ 501 | "currentDay", 502 | "previousDays" 503 | ], 504 | "properties": { 505 | "currentDay": { 506 | "type": "number", 507 | "description": "Average response time for current day" 508 | }, 509 | "previousDays": { 510 | "type": "array", 511 | "description": "Average response time for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available.", 512 | "items": { 513 | "type": "number" 514 | } 515 | } 516 | } 517 | } 518 | } 519 | }, 520 | "SessionCountMetrics": { 521 | "description": "Session counts over time. Note that a session is defined as the provisioning of an Access Token.", 522 | "x-conditional": [ 523 | "currentDay", 524 | "previousDays" 525 | ], 526 | "properties": { 527 | "currentDay": { 528 | "type": "number", 529 | "description": "Session count for current day" 530 | }, 531 | "previousDays": { 532 | "type": "array", 533 | "description": "Session count for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available", 534 | "items": { 535 | "type": "number" 536 | } 537 | } 538 | } 539 | }, 540 | "AverageTPSMetrics": { 541 | "description": "Transactions per second over time", 542 | "x-conditional": [ 543 | "currentDay", 544 | "previousDays" 545 | ], 546 | "properties": { 547 | "currentDay": { 548 | "type": "number", 549 | "description": "Average TPS for current day" 550 | }, 551 | "previousDays": { 552 | "type": "array", 553 | "description": "Average TPS for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available", 554 | "items": { 555 | "type": "number" 556 | } 557 | } 558 | } 559 | }, 560 | "PeakTPSMetrics": { 561 | "description": "Maximum record transactions per second over time", 562 | "x-conditional": [ 563 | "currentDay", 564 | "previousDays" 565 | ], 566 | "properties": { 567 | "currentDay": { 568 | "type": "number", 569 | "description": "Peak TPS for current day" 570 | }, 571 | "previousDays": { 572 | "type": "array", 573 | "description": "Peak TPS for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available", 574 | "items": { 575 | "type": "number" 576 | } 577 | } 578 | } 579 | }, 580 | "ErrorMetrics": { 581 | "description": "Number of calls resulting in error due to server execution over time", 582 | "x-conditional": [ 583 | "currentDay", 584 | "previousDays" 585 | ], 586 | "properties": { 587 | "currentDay": { 588 | "type": "number", 589 | "description": "Number of errors for current day" 590 | }, 591 | "previousDays": { 592 | "type": "array", 593 | "description": "Number of errors for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available", 594 | "items": { 595 | "type": "number" 596 | } 597 | } 598 | } 599 | }, 600 | "RejectionMetricsV2": { 601 | "description": "Number of calls rejected due to traffic thresholds over time", 602 | "required": [ 603 | "authenticated", 604 | "unauthenticated" 605 | ], 606 | "properties": { 607 | "authenticated": { 608 | "description": "Rejection counts for all authenticated end points", 609 | "x-conditional": [ 610 | "currentDay", 611 | "previousDays" 612 | ], 613 | "properties": { 614 | "currentDay": { 615 | "type": "number", 616 | "description": "Number of calls rejected for current day" 617 | }, 618 | "previousDays": { 619 | "type": "array", 620 | "description": "Number of calls rejected for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available.", 621 | "items": { 622 | "type": "number" 623 | } 624 | } 625 | } 626 | }, 627 | "unauthenticated": { 628 | "description": "Rejection counts for all uauthenticated end points", 629 | "x-conditional": [ 630 | "currentDay", 631 | "previousDays" 632 | ], 633 | "properties": { 634 | "currentDay": { 635 | "type": "number", 636 | "description": "Number of calls rejected for current day" 637 | }, 638 | "previousDays": { 639 | "type": "array", 640 | "description": "Number of calls rejected for previous days. The first element indicates yesterday and so on. A maximum of seven entries is required if available.", 641 | "items": { 642 | "type": "number" 643 | } 644 | } 645 | } 646 | } 647 | } 648 | }, 649 | "Links": { 650 | "type": "object", 651 | "required": [ 652 | "self" 653 | ], 654 | "properties": { 655 | "self": { 656 | "type": "string", 657 | "description": "Fully qualified link to this API call", 658 | "x-cds-type": "URIString" 659 | } 660 | } 661 | }, 662 | "Meta": { 663 | "type": "object" 664 | } 665 | } 666 | } 667 | -------------------------------------------------------------------------------- /reviews/2021-05/raw/draft-ietf-oauth-par-01.txt: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Web Authorization Protocol T. Lodderstedt 6 | Internet-Draft yes.com 7 | Intended status: Standards Track B. Campbell 8 | Expires: 21 August 2020 Ping Identity 9 | N. Sakimura 10 | Nomura Research Institute 11 | D. Tonge 12 | Moneyhub Financial Technology 13 | F. Skokan 14 | Auth0 15 | 18 February 2020 16 | 17 | 18 | OAuth 2.0 Pushed Authorization Requests 19 | draft-ietf-oauth-par-01 20 | 21 | Abstract 22 | 23 | This document defines the pushed authorization request endpoint, 24 | which allows clients to push the payload of an OAuth 2.0 25 | authorization request to the authorization server via a direct 26 | request and provides them with a request URI that is used as 27 | reference to the data in a subsequent authorization request. 28 | 29 | Status of This Memo 30 | 31 | This Internet-Draft is submitted in full conformance with the 32 | provisions of BCP 78 and BCP 79. 33 | 34 | Internet-Drafts are working documents of the Internet Engineering 35 | Task Force (IETF). Note that other groups may also distribute 36 | working documents as Internet-Drafts. The list of current Internet- 37 | Drafts is at https://datatracker.ietf.org/drafts/current/. 38 | 39 | Internet-Drafts are draft documents valid for a maximum of six months 40 | and may be updated, replaced, or obsoleted by other documents at any 41 | time. It is inappropriate to use Internet-Drafts as reference 42 | material or to cite them other than as "work in progress." 43 | 44 | This Internet-Draft will expire on 21 August 2020. 45 | 46 | Copyright Notice 47 | 48 | Copyright (c) 2020 IETF Trust and the persons identified as the 49 | document authors. All rights reserved. 50 | 51 | This document is subject to BCP 78 and the IETF Trust's Legal 52 | Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 | 54 | 55 | 56 | Lodderstedt, et al. Expires 21 August 2020 [Page 1] 57 | 58 | Internet-Draft OAuth PAR February 2020 59 | 60 | 61 | license-info) in effect on the date of publication of this document. 62 | Please review these documents carefully, as they describe your rights 63 | and restrictions with respect to this document. Code Components 64 | extracted from this document must include Simplified BSD License text 65 | as described in Section 4.e of the Trust Legal Provisions and are 66 | provided without warranty as described in the Simplified BSD License. 67 | 68 | Table of Contents 69 | 70 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 71 | 1.1. Conventions and Terminology . . . . . . . . . . . . . . . 4 72 | 2. Pushed Authorization Request Endpoint . . . . . . . . . . . . 4 73 | 2.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 5 74 | 2.2. Successful Response . . . . . . . . . . . . . . . . . . . 7 75 | 2.3. Error Response . . . . . . . . . . . . . . . . . . . . . 8 76 | 3. "request" Parameter . . . . . . . . . . . . . . . . . . . . . 9 77 | 3.1. Error responses for Request Object . . . . . . . . . . . 10 78 | 3.1.1. Authentication Required . . . . . . . . . . . . . . . 10 79 | 4. Authorization Request . . . . . . . . . . . . . . . . . . . . 10 80 | 5. Authorization Server Metadata . . . . . . . . . . . . . . . . 10 81 | 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 82 | 6.1. Request URI Guessing . . . . . . . . . . . . . . . . . . 11 83 | 6.2. Open Redirection . . . . . . . . . . . . . . . . . . . . 11 84 | 6.3. Request Object Replay . . . . . . . . . . . . . . . . . . 11 85 | 6.4. Client Policy Change . . . . . . . . . . . . . . . . . . 11 86 | 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 87 | 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 88 | 9. Normative References . . . . . . . . . . . . . . . . . . . . 12 89 | 10. Informative References . . . . . . . . . . . . . . . . . . . 12 90 | Appendix A. Document History . . . . . . . . . . . . . . . . . . 13 91 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 92 | 93 | 1. Introduction 94 | 95 | In OAuth [RFC6749] authorization request parameters are typically 96 | sent as URI query parameters via redirection in the user-agent. This 97 | is simple but also yields challenges: 98 | 99 | * There is no cryptographic integrity and authenticity protection, 100 | i.e. the request can be modified on its way through the user-agent 101 | and attackers can impersonate legitimate clients. 102 | 103 | * There is no mechanism to ensure confidentiality of the request 104 | parameters. 105 | 106 | * Authorization request URLs can become quite large, especially in 107 | scenarios requiring fine-grained authorization data. 108 | 109 | 110 | 111 | 112 | Lodderstedt, et al. Expires 21 August 2020 [Page 2] 113 | 114 | Internet-Draft OAuth PAR February 2020 115 | 116 | 117 | JWT Secured Authorization Request (JAR) [I-D.ietf-oauth-jwsreq] 118 | provides solutions for those challenges by allowing OAuth clients to 119 | wrap authorization request parameters in a signed, and optionally 120 | encrypted, JSON Web Token (JWT), the so-called "Request Object". 121 | 122 | In order to cope with the size restrictions, JAR introduces the 123 | "request_uri" parameter that allows clients to send a reference to a 124 | request object instead of the request object itself. 125 | 126 | This document complements JAR by providing an interoperable way to 127 | push the payload of a request object directly to the AS in exchange 128 | for a "request_uri". 129 | 130 | It also allows for clients to push the form encoded authorization 131 | request parameters to the AS in order to exchange them for a request 132 | URI that the client can use in a subsequent authorization request. 133 | 134 | For example, the following authorization request, 135 | 136 | GET /authorize?response_type=code 137 | &client_id=s6BhdRkqt3&state=af0ifjsldkj 138 | &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb HTTP/1.1 139 | Host: as.example.com 140 | 141 | could be pushed directly to the AS by the client as follows: 142 | 143 | POST /as/par HTTP/1.1 144 | Host: as.example.com 145 | Content-Type: application/x-www-form-urlencoded 146 | Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 147 | 148 | response_type=code 149 | &client_id=s6BhdRkqt3&state=af0ifjsldkj 150 | &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb 151 | 152 | The AS responds with a request URI, 153 | 154 | HTTP/1.1 201 Created 155 | Cache-Control: no-cache, no-store 156 | Content-Type: application/json 157 | 158 | { 159 | 160 | "request_uri": "urn:example:bwc4JK-ESC0w8acc191e-Y1LTC2", 161 | "expires_in": 90 162 | } 163 | 164 | 165 | 166 | 167 | 168 | Lodderstedt, et al. Expires 21 August 2020 [Page 3] 169 | 170 | Internet-Draft OAuth PAR February 2020 171 | 172 | 173 | which is used by the client in the subsequent authorization request 174 | as follows, 175 | 176 | GET /authorize?request_uri= 177 | urn%3Aexample%3Abwc4JK-ESC0w8acc191e-Y1LTC2 HTTP/1.1 178 | 179 | The pushed authorization request endpoint fosters OAuth security by 180 | providing all clients a simple means for an integrity protected 181 | authorization request, but it also allows clients requiring an even 182 | higher security level, especially cryptographically confirmed non- 183 | repudiation, to explicitly adopt JWT-based request objects. 184 | 185 | As a further benefit, the pushed authorization request allows the AS 186 | to authenticate the clients before any user interaction happens, 187 | i.e., the AS may refuse unauthorized requests much earlier in the 188 | process and has much higher confidence in the client's identity in 189 | the authorization process than before. 190 | 191 | This is directly utilized by this draft to allow confidential clients 192 | to set the redirect URI for every authorization request, which gives 193 | them more flexibility in building redirect URI. And if the client 194 | IDs and credentials are managed by some external authority (e.g. a 195 | certification authority), explicit client registration with the 196 | particular AS could practically be skipped. 197 | 198 | 1.1. Conventions and Terminology 199 | 200 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 201 | "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 202 | "OPTIONAL" in this document are to be interpreted as described in BCP 203 | 14 [RFC2119] [RFC8174] when, and only when, they appear in all 204 | capitals, as shown here. 205 | 206 | This specification uses the terms "access token", "refresh token", 207 | "authorization server", "resource server", "authorization endpoint", 208 | "authorization request", "authorization response", "token endpoint", 209 | "grant type", "access token request", "access token response", and 210 | "client" defined by The OAuth 2.0 Authorization Framework [RFC6749]. 211 | 212 | 2. Pushed Authorization Request Endpoint 213 | 214 | The pushed authorization request endpoint is an HTTP API at the 215 | authorization server that accepts POST requests with parameters in 216 | the HTTP request entity-body using the "application/x-www-form- 217 | urlencoded" format with a character encoding of UTF-8 as described in 218 | Appendix B of [RFC6749]. 219 | 220 | 221 | 222 | 223 | 224 | Lodderstedt, et al. Expires 21 August 2020 [Page 4] 225 | 226 | Internet-Draft OAuth PAR February 2020 227 | 228 | 229 | The endpoint accepts the parameters defined in [RFC6749] for the 230 | authorization endpoint as well as all applicable extensions defined 231 | for the authorization endpoint. Some examples of such extensions 232 | include PKCE [RFC7636], Resource Indicators 233 | [I-D.ietf-oauth-resource-indicators], and OpenID Connect [OIDC]. 234 | 235 | The rules for client authentication as defined in [RFC6749] for token 236 | endpoint requests, including the applicable authentication methods, 237 | apply for the pushed authorization request endpoint as well. If 238 | applicable, the "token_endpoint_auth_method" client metadata 239 | parameter indicates the registered authentication method for the 240 | client to use when making direct requests to the authorization 241 | server, including requests to the pushed authorization request 242 | endpoint. 243 | 244 | Note that there's some potential ambiguity around the appropriate 245 | audience value to use when JWT client assertion based authentication 246 | is employed. To address that ambiguity the issuer identifier URL of 247 | the AS according to [RFC8414] SHOULD be used as the value of the 248 | audience. In order to facilitate interoperability the AS MUST accept 249 | its issuer identifier, token endpoint URL, or pushed authorization 250 | request endpoint URL as values that identify it as an intended 251 | audience. 252 | 253 | 2.1. Request 254 | 255 | A client can send all the parameters that usually comprise an 256 | authorization request to the pushed authorization request endpoint. 257 | A basic parameter set will typically include: 258 | 259 | * "client_id" 260 | 261 | * "response_type" 262 | 263 | * "redirect_uri" 264 | 265 | * "scope" 266 | 267 | * "state" 268 | 269 | * "code_challenge" 270 | 271 | * "code_challenge_method" 272 | 273 | Depending on client type and authentication method, the request might 274 | also include other parameters for client authentication such as the 275 | "client_secret" parameter, the "client_assertion" parameter and the 276 | 277 | 278 | 279 | 280 | Lodderstedt, et al. Expires 21 August 2020 [Page 5] 281 | 282 | Internet-Draft OAuth PAR February 2020 283 | 284 | 285 | "client_assertion_type" parameter. The "request_uri" authorization 286 | request parameter MUST NOT be provided in this case (see Section 3). 287 | 288 | The client adds the parameters in "x-www-form-urlencoded" format with 289 | a character encoding of UTF-8 as described in Appendix B of [RFC6749] 290 | to the body of an HTTP POST request. If applicable, the client also 291 | adds client credentials to the request header or the request body 292 | using the same rules as for token endpoint requests. 293 | 294 | This is illustrated by the following example: 295 | 296 | POST /as/par HTTP/1.1 297 | Host: as.example.com 298 | Content-Type: application/x-www-form-urlencoded 299 | Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 300 | 301 | response_type=code& 302 | state=af0ifjsldkj& 303 | client_id=s6BhdRkqt3& 304 | redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb& 305 | code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U& 306 | code_challenge_method=S256& 307 | scope=ais 308 | 309 | The AS MUST process the request as follows: 310 | 311 | 1. The AS MUST authenticate the client in the same way as at the 312 | token endpoint. 313 | 314 | 2. The AS MUST reject the request if the "request_uri" authorization 315 | request parameter is provided. 316 | 317 | 3. The AS MUST validate the request in the same way as at the 318 | authorization endpoint. For example, the authorization server 319 | checks whether the redirect URI matches one of the redirect URIs 320 | configured for the client. It MUST also check whether the client 321 | is authorized for the "scope" for which it is requesting access. 322 | This validation allows the authorization server to refuse 323 | unauthorized or fraudulent requests early. 324 | 325 | The AS MAY allow confidential clients to establish per-authorization 326 | request redirect URIs with every pushed authorization request. This 327 | is possible since, in contrast to [RFC6749], this specification gives 328 | the AS the ability to authenticate and authorize clients before the 329 | actual authorization request is performed. 330 | 331 | This feature gives clients more flexibility in building redirect URIs 332 | and, if the client IDs and credentials are managed by some authority 333 | 334 | 335 | 336 | Lodderstedt, et al. Expires 21 August 2020 [Page 6] 337 | 338 | Internet-Draft OAuth PAR February 2020 339 | 340 | 341 | (CA or other type), the explicit client registration with the 342 | particular AS (manually or via dynamic client registration [RFC7591]) 343 | could practically be skipped. This makes this mechanism especially 344 | useful for clients interacting with a federation of ASs (or OpenID 345 | Connect OPs), for example in Open Banking, where the certificate is 346 | provided as part of a federated PKI. 347 | 348 | 2.2. Successful Response 349 | 350 | If the verification is successful, the server MUST generate a request 351 | URI and return a JSON response that contains "request_uri" and 352 | "expires_in" members at the top level with "201 Created" HTTP 353 | response code. 354 | 355 | * "request_uri" : The request URI corresponding to the authorization 356 | request posted. This URI is used as reference to the respective 357 | request data in the subsequent authorization request only. The 358 | way the authorization process obtains the authorization request 359 | data is at the discretion of the authorization server and out of 360 | scope of this specification. There is no need to make the 361 | authorization request data available to other parties via this 362 | URI. 363 | 364 | * "expires_in" : A JSON number that represents the lifetime of the 365 | request URI in seconds. The request URI lifetime is at the 366 | discretion of the AS. 367 | 368 | The "request_uri" value MUST be generated using a cryptographically 369 | strong pseudorandom algorithm such that it is computationally 370 | infeasible to predict or guess a valid value. 371 | 372 | The "request_uri" MUST be bound to the client that posted the 373 | authorization request. 374 | 375 | Since the request URI can be replayed, its lifetime SHOULD be short 376 | and preferably limited to one-time use. 377 | 378 | The following is an example of such a response: 379 | 380 | HTTP/1.1 201 Created 381 | Content-Type: application/json 382 | Cache-Control: no-cache, no-store 383 | 384 | { 385 | "request_uri": "urn:example:bwc4JK-ESC0w8acc191e-Y1LTC2", 386 | "expires_in": 3600 387 | } 388 | 389 | 390 | 391 | 392 | Lodderstedt, et al. Expires 21 August 2020 [Page 7] 393 | 394 | Internet-Draft OAuth PAR February 2020 395 | 396 | 397 | 2.3. Error Response 398 | 399 | For an error the authorization server sets an appropriate HTTP status 400 | code and MAY include additional error parameters in the entity-body 401 | of the HTTP response using the format specified for the token 402 | endpoint in Section 5.2 of [RFC6749]. 403 | 404 | If the authorization server sets an error code, it SHOULD be one of 405 | the defined codes for the token endpoint in Section 5.2 or for the 406 | authorization endpoint in Sections 4.1.2.1 and 4.2.2.1 of [RFC6749], 407 | or by an OAuth extension if one is involved in the initial processing 408 | of authorization request that was pushed. Since initial processing 409 | of the pushed authorisation request doesn't involve resource owner 410 | interaction, error codes related to user interaction, such as 411 | "consent_required" defined by [OIDC], are not returned. 412 | 413 | In addition to the error codes above, the pushed authorization 414 | request endpoint specifies use of the following HTTP status codes: 415 | 416 | * 405: If the request did not use POST, the authorization server 417 | responds with an HTTP 405 (Method Not Allowed) status code. 418 | 419 | * 413: If the request size was beyond the upper bound that the 420 | authorization server allows, the authorization server responds 421 | with an HTTP 413 (Payload Too Large) status code. 422 | 423 | * 429: If the request from the client for a time period goes beyond 424 | the number the authorization server allows, the authorization 425 | server responds with an HTTP 429 (Too Many Requests) status code. 426 | 427 | The following is an example of an error response from the pushed 428 | authorization request endpoint: 429 | 430 | HTTP/1.1 400 Bad Request 431 | Content-Type: application/json 432 | Cache-Control: no-cache, no-store 433 | 434 | { 435 | "error": "invalid_request", 436 | "error_description": 437 | "The redirect_uri is not valid for the given client" 438 | } 439 | 440 | 441 | 442 | 443 | 444 | 445 | 446 | 447 | 448 | Lodderstedt, et al. Expires 21 August 2020 [Page 8] 449 | 450 | Internet-Draft OAuth PAR February 2020 451 | 452 | 453 | 3. "request" Parameter 454 | 455 | Clients MAY use the "request" parameter as defined in JAR 456 | [I-D.ietf-oauth-jwsreq] to push a request object JWT to the AS. The 457 | rules for processing, signing, and encryption of the request object 458 | as defined in JAR [I-D.ietf-oauth-jwsreq] apply. When the 459 | "application/x-www-form-urlencoded" HTTP entity-body "request" 460 | parameter is used, the request object MUST contain all the 461 | authorization request parameters as claims of the JWT. Additional 462 | request parameters as required by the given client authentication 463 | method are to be included as 'application/x-www-form-urlencoded' 464 | parameters in the HTTP request entity-body (e.g. Mutual TLS client 465 | authentication [I-D.ietf-oauth-mtls] uses the "client_id" HTTP 466 | request parameter while JWT assertion based client authentication 467 | [RFC7523] uses "client_assertion" and "client_assertion_type"). 468 | 469 | The following is an example of a pushed authorization request using a 470 | signed request object. The client is authenticated by its client 471 | secret using the HTTP Basic Authentication scheme specified in 472 | Section 2.3.1 of [RFC6749]: 473 | 474 | POST /as/par HTTP/1.1 475 | Host: as.example.com 476 | Content-Type: application/x-www-form-urlencoded 477 | Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3 478 | 479 | request=eyJraWQiOiJrMmJkYyIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJzNkJoZ 480 | FJrcXQzIiwiYXVkIjoiaHR0cHM6Ly9zZXJ2ZXIuZXhhbXBsZS5jb20iLCJyZXNwb2 481 | 5zZV90eXBlIjoiY29kZSIsImNsaWVudF9pZCI6InM2QmhkUmtxdDMiLCJyZWRpcmV 482 | jdF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm9yZy9jYiIsInNjb3BlIjoi 483 | YWlzIiwic3RhdGUiOiJhZjBpZmpzbGRraiIsImNvZGVfY2hhbGxlbmdlIjoiSzItb 484 | HRjODNhY2M0aDBjOXc2RVNDX3JFTVRKM2J3dy11Q0hhb2VLMXQ4VSIsImNvZGVfY2 485 | hhbGxlbmdlX21ldGhvZCI6IlMyNTYifQ.O49ffUxRPdNkN3TRYDvbEYVr1CeAL64u 486 | W4FenV3n9WlaFIRHeFblzv-wlEtMm8-tusGxeE9z3ek6FxkhvvLEqEpjthXnyXqqy 487 | Jfq3k9GSf5ay74ml_0D6lHE1hy-kVWg7SgoPQ-GB1xQ9NRhF3EKS7UZIrUHbFUCF0 488 | MsRLbmtIvaLYbQH_Ef3UkDLOGiU7exhVFTPeyQUTM9FF-u3K-zX-FO05_brYxNGLh 489 | VkO1G8MjqQnn2HpAzlBd5179WTzTYhKmhTiwzH-qlBBI_9GLJmE3KOipko9TfSpa2 490 | 6H4JOlMyfZFl0PCJwkByS0xZFJ2sTo3Gkk488RQohhgt1I0onw 491 | 492 | The AS needs to take the following steps beyond the processing rules 493 | defined in Section 2.1: 494 | 495 | 1. If applicable, the AS decrypts the request object as specified in 496 | JAR [I-D.ietf-oauth-jwsreq], section 6.1. 497 | 498 | 2. The AS validates the request object signature as specified in JAR 499 | [I-D.ietf-oauth-jwsreq], section 6.2. 500 | 501 | 502 | 503 | 504 | Lodderstedt, et al. Expires 21 August 2020 [Page 9] 505 | 506 | Internet-Draft OAuth PAR February 2020 507 | 508 | 509 | 3. If the client is a confidential client, the authorization server 510 | MUST check whether the authenticated "client_id" matches the 511 | "client_id" claim in the request object. If they do not match, 512 | the authorization server MUST refuse to process the request. It 513 | is at the authorization server's discretion to require the "iss" 514 | claim to match the "client_id" as well. 515 | 516 | 3.1. Error responses for Request Object 517 | 518 | This section gives the error responses that go beyond the basic 519 | Section 2.3. 520 | 521 | 3.1.1. Authentication Required 522 | 523 | If the signature validation fails, the authorization server returns a 524 | "401 Unauthorized" HTTP error response. The same applies if the 525 | "client_id" or, if applicable, the "iss" claim in the request object 526 | do not match the authenticated "client_id". 527 | 528 | 4. Authorization Request 529 | 530 | The client uses the "request_uri" value returned by the authorization 531 | server as the authorization request parameter "request_uri" as 532 | defined in JAR. 533 | 534 | GET /authorize?request_uri= 535 | urn%3Aexample%3Abwc4JK-ESC0w8acc191e-Y1LTC2 HTTP/1.1 536 | 537 | Clients are encouraged to use the request URI as the only parameter 538 | in order to use the integrity and authenticity provided by the pushed 539 | authorization request. 540 | 541 | 5. Authorization Server Metadata 542 | 543 | If the authorization server has a pushed authorization request 544 | endpoint, it SHOULD include the following OAuth/OpenID Provider 545 | Metadata parameter in discovery responses: 546 | 547 | "pushed_authorization_request_endpoint" : The URL of the pushed 548 | authorization request endpoint at which the client can post an 549 | authorization request and get a request URI in exchange. 550 | 551 | 6. Security Considerations 552 | 553 | 554 | 555 | 556 | 557 | 558 | 559 | 560 | Lodderstedt, et al. Expires 21 August 2020 [Page 10] 561 | 562 | Internet-Draft OAuth PAR February 2020 563 | 564 | 565 | 6.1. Request URI Guessing 566 | 567 | An attacker could attempt to guess and replay a valid request URI 568 | value and try to impersonate the respective client. The AS MUST 569 | consider the considerations given in JAR [I-D.ietf-oauth-jwsreq], 570 | section 10.2, clause d on request URI entropy. 571 | 572 | 6.2. Open Redirection 573 | 574 | An attacker could try register a redirect URI pointing to a site 575 | under his control in order to obtain authorization codes or lauch 576 | other attacks towards the user. The AS MUST only accept new redirect 577 | URIs in the PAR request from confidential clients after sucessful 578 | authentication and authorization. 579 | 580 | 6.3. Request Object Replay 581 | 582 | An attacker could replay a request URI captured from a legitimate 583 | authorization request. In order to cope with such attacks, the AS 584 | SHOULD make the request URIs one-time use. 585 | 586 | 6.4. Client Policy Change 587 | 588 | The client policy might change between the lodging of the request 589 | object and the authorization request using a particular request 590 | object. It is therefore recommended that the AS check the request 591 | parameter against the client policy when processing the authorization 592 | request. 593 | 594 | 7. Acknowledgements 595 | 596 | This specification is based on the work towards Pushed Request Object 597 | (https://bitbucket.org/openid/fapi/src/master/ 598 | Financial_API_Pushed_Request_Object.md) conducted at the Financial- 599 | grade API working group at the OpenID Foundation. We would like to 600 | thank the members of the WG for their valuable contributions. 601 | 602 | We would like to thank Vladimir Dzhuvinov, Aaron Parecki, Joseph 603 | Heenan, and Takahiko Kawasaki for their valuable feedback on this 604 | draft. 605 | 606 | 8. IANA Considerations 607 | 608 | This specification requests registration of the following value in 609 | the IANA "OAuth Authorization Server Metadata" registry of 610 | [IANA.OAuth.Parameters] established by [RFC8414]. 611 | 612 | Metadata Name: "pushed_authorization_request_endpoint" 613 | 614 | 615 | 616 | Lodderstedt, et al. Expires 21 August 2020 [Page 11] 617 | 618 | Internet-Draft OAuth PAR February 2020 619 | 620 | 621 | Metadata Description: URL of the authorization server's pushed 622 | authorization request endpoint 623 | Change Controller: IESG 624 | Specification Document(s): [[ this document ]] 625 | 626 | 9. Normative References 627 | 628 | [RFC8414] Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 629 | Authorization Server Metadata", RFC 8414, 630 | DOI 10.17487/RFC8414, June 2018, 631 | . 632 | 633 | [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 634 | RFC 6749, DOI 10.17487/RFC6749, October 2012, 635 | . 636 | 637 | [I-D.ietf-oauth-jwsreq] 638 | Sakimura, N. and J. Bradley, "The OAuth 2.0 Authorization 639 | Framework: JWT Secured Authorization Request (JAR)", Work 640 | in Progress, Internet-Draft, draft-ietf-oauth-jwsreq-20, 641 | 21 October 2019, 642 | . 643 | 644 | [OIDC] Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and 645 | C. Mortimore, "OpenID Connect Core 1.0 incorporating 646 | errata set 1", 8 November 2014, 647 | . 648 | 649 | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 650 | Requirement Levels", BCP 14, RFC 2119, 651 | DOI 10.17487/RFC2119, March 1997, 652 | . 653 | 654 | [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 655 | 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 656 | May 2017, . 657 | 658 | 10. Informative References 659 | 660 | [I-D.ietf-oauth-resource-indicators] 661 | Campbell, B., Bradley, J., and H. Tschofenig, "Resource 662 | Indicators for OAuth 2.0", Work in Progress, Internet- 663 | Draft, draft-ietf-oauth-resource-indicators-08, 11 664 | September 2019, . 666 | 667 | [I-D.ietf-oauth-mtls] 668 | Campbell, B., Bradley, J., Sakimura, N., and T. 669 | 670 | 671 | 672 | Lodderstedt, et al. Expires 21 August 2020 [Page 12] 673 | 674 | Internet-Draft OAuth PAR February 2020 675 | 676 | 677 | Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication 678 | and Certificate-Bound Access Tokens", Work in Progress, 679 | Internet-Draft, draft-ietf-oauth-mtls-17, 23 August 2019, 680 | . 681 | 682 | [RFC7523] Jones, M., Campbell, B., and C. Mortimore, "JSON Web Token 683 | (JWT) Profile for OAuth 2.0 Client Authentication and 684 | Authorization Grants", RFC 7523, DOI 10.17487/RFC7523, May 685 | 2015, . 686 | 687 | [RFC7636] Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key 688 | for Code Exchange by OAuth Public Clients", RFC 7636, 689 | DOI 10.17487/RFC7636, September 2015, 690 | . 691 | 692 | [RFC7591] Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and 693 | P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", 694 | RFC 7591, DOI 10.17487/RFC7591, July 2015, 695 | . 696 | 697 | [IANA.OAuth.Parameters] 698 | IANA, "OAuth Parameters", 699 | . 700 | 701 | Appendix A. Document History 702 | 703 | [[ To be removed from the final specification ]] 704 | 705 | -01 706 | 707 | * Use the newish RFC v3 XML and HTML format 708 | * Added IANA registration request for 709 | "pushed_authorization_request_endpoint" 710 | * Changed abbrev to "OAuth PAR" 711 | 712 | -00 (WG draft) 713 | 714 | * Reference RFC6749 sec 2.3.1 for client secret basic rather than 715 | RFC7617 716 | * further clarify that a request object JWT contains all the 717 | authorization request parameters while client authentication 718 | params, if applicable, are outside that JWT as regular form 719 | encoded params in HTTP body 720 | 721 | -01 722 | 723 | * List "client_id" as one of the basic parameters 724 | * Explicitly forbid "request_uri" in the processing rules 725 | 726 | 727 | 728 | Lodderstedt, et al. Expires 21 August 2020 [Page 13] 729 | 730 | Internet-Draft OAuth PAR February 2020 731 | 732 | 733 | * Clarification regarding client authentication and that public 734 | clients are allowed 735 | * Added option to let clients register per-authorization request 736 | redirect URIs 737 | * General clean up and wording improvements 738 | 739 | -00 740 | 741 | * first draft 742 | 743 | Authors' Addresses 744 | 745 | Torsten Lodderstedt 746 | yes.com 747 | 748 | Email: torsten@lodderstedt.net 749 | 750 | 751 | Brian Campbell 752 | Ping Identity 753 | 754 | Email: bcampbell@pingidentity.com 755 | 756 | 757 | Nat Sakimura 758 | Nomura Research Institute 759 | 760 | Email: nat@sakimura.org 761 | 762 | 763 | Dave Tonge 764 | Moneyhub Financial Technology 765 | 766 | Email: dave@tonge.org 767 | 768 | 769 | Filip Skokan 770 | Auth0 771 | 772 | Email: panva.ip@gmail.com 773 | 774 | 775 | 776 | 777 | 778 | 779 | 780 | 781 | 782 | 783 | 784 | Lodderstedt, et al. Expires 21 August 2020 [Page 14] 785 | -------------------------------------------------------------------------------- /reviews/2021-05/analysis/docs/analysis-cds_full-json-v1.10.0.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | stdin 8 | 9 | 10 |

11 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
12 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
13 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
14 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
15 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
16 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
17 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
18 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
19 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
20 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
21 | "description": "Obtain transactions for a specific account.\n\nSome general notes that apply to all end points that retrieve transactions:\n\n- Where multiple transactions are returned, transactions should be ordered according to effective date in descending order\n- As the date and time for a transaction can alter depending on status and transaction type two separate date/times are included in the payload. There are still some scenarios where neither of these time stamps is available. For the purpose of filtering and ordering it is expected that the data holder will use the “effective” date/time which will be defined as:\n - Posted date/time if available, then\n - Execution date/time if available, then\n - A reasonable date/time nominated by the data holder using internal data structures\n- For transaction amounts it should be assumed that a negative value indicates a reduction of the available balance on the account while a positive value indicates an increase in the available balance on the account\n- For aggregated transactions (ie. groups of sub transactions reported as a single entry for the account) only the aggregated information, with as much consistent information accross the subsidiary transactions as possible, is required to be shared",
22 | "description": "ID of the account to get transactions for. Must have previously been returned by one of the account list end points.",
23 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
24 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
25 | "description": "ID of the account to get transactions for. Must have previously been returned by one of the account list end points",
26 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
27 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
28 | "description": "ID of the account to get direct debit authorisations for. Must have previously been returned by one of the account list end points.",
29 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
30 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
31 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
32 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
33 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
34 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
35 | "description": "ID of the account to get scheduled payments for. Must have previously been returned by one of the account list end points. The account specified is the source account for the payment",
36 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
37 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
38 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
39 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
40 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
41 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
42 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
43 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
44 | "description": "Obtain detailed information on a single payee.\n\nNote that the payee sub-structure should be selected to represent the payment destination only rather than any known characteristics of the payment recipient",
45 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
46 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
47 | "description": "Obtain a list of products that are currently openly offered to the market\n\nNote that the results returned by this end point are expected to be ordered in descending order according to ``lastUpdated``.\n\n### Conventions\nIn the product reference payloads there are a number of recurring conventions that are explained here, in one place.\n\n#### Arrays Of Features\n\nIn the product detail payload there are a number of arrays articulating generic features, constraints, prices, etc. The intent of these arrays is as follows:\n\n- Each element in an array has the same structure so that clients can reliably interpret the payloads\n- Each element as a type element that is an enumeration of the specific aspect of a product being described, such as types of fees.\n- Each element has a field name [additionalValue](#productfeaturetypedoc). This is a generic field with contents that will vary based on the type of object being described. The contents of this field for the ADDITIONAL_CARDS feature is the number of cards allowed while the contents of this field for the MAX_LIMIT constraint would be the maximum credit limit allowed for the product.\n- An element in these arrays of the same type may appear more than once. For instance, a product may offer two separate loyalty programs that the customer can select from. A fixed term mortgage may have different rates for different term lengths.\n- An element in these arrays may contain an additionalInfo and additionalInfoUri field. The additionalInfo field is used to provide displayable text clarifying the purpose of the element in some way when the product is presented to a customer. The additionalInfoUri provides a link to externally hosted information specifically relevant to that feature of the product.\n- Depending on the type of data being represented there may be additional specific fields.\n\n#### URIs To More Information\n\nAs the complexities and nuances of a financial product can not easily be fully expressed in a data structure without a high degree of complexity it is necessary to provide additional reference information that a potential customer can access so that they are fully informed of the features and implications of the product. The payloads for product reference therefore contain numerous fields that are provided to allow the product holder to describe the product more fully using a web page hosted on their online channels.\n\nThese URIs do not need to all link to different pages. If desired, they can all link to a single hosted page and use difference HTML anchors to focus on a specific topic such as eligibility or fees.\n\n#### Linkage To Accounts\nFrom the moment that a customer applies for a product and an account is created the account and the product that spawned it will diverge. Rates and features of the product may change and a discount may be negotiated for the account.\n\nFor this reason, while productCategory is a common field between accounts and products, there is no specific ID that can be used to link an account to a product within the regime.\n\nSimilarly, many of the fields and objects in the product payload will appear in the account detail payload but the structures and semantics are not identical as one refers to a product that can potentially be originated and one refers to an account that actual has been instantiated and created along with the associated decisions inherent in that process.\n\n#### Dates\nIt is expected that data consumers needing this data will call relatively frequently to ensure the data they have is representative of the current offering from a bank. To minimise the volume and frequency of these calls the ability to set a lastUpdated field with the date and time of the last update to this product is included. A call for a list of products can then be filtered to only return products that have been updated since the last time that data was obtained using the updated-since query parameter.\n\nIn addition, the concept of effective date and time has also been included. This allows for a product to be marked for obsolescence, or introduction, from a certain time without the need for an update to show that a product has been changed. The inclusion of these dates also removes the need to represent deleted products in the payload. Products that are no long offered can be marked not effective for a few weeks before they are then removed from the product set as an option entirely.\n\nNOTE: This version must be implemented by **February 2021**\n\nObsolete versions: [v1](includes/obsolete/get-products-v1.html) [v2](includes/obsolete/get-products-v2.html)",
48 | "description": "Obtain detailed information on a single product offered openly to the market.\n\nNOTE: This version must be implemented by **February 2021**\n\nObsolete versions: [v1](includes/obsolete/get-product-detail-v1.html) [v2](includes/obsolete/get-product-detail-v2.html)",
49 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
50 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
51 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
52 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction."
53 | "description": "Version of the API end point requested by the client. Must be set to a positive integer. The data holder should respond with the highest supported version between [x-min-v](#request-headers) and [x-v](#request-headers). If the value of [x-min-v](#request-headers) is equal to or higher than the value of [x-v](#request-headers) then the [x-min-v](#request-headers) header should be treated as absent. If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable. See [HTTP Headers](#request-headers)",
54 | "description": "Minimum version of the API end point requested by the client. Must be set to a positive integer if provided. The data holder should respond with the highest supported version between [x-min-v](#request-headers) and [x-v](#request-headers). If all versions requested are not supported then the data holder must respond with a 406 Not Acceptable.",
55 | "description": "An [RFC4122](https://tools.ietf.org/html/rfc4122) UUID used as a correlation id. If provided, the data holder must play back this value in the x-fapi-interaction-id response header. If not provided a [RFC4122] UUID value is required to be provided in the response header to track the interaction.",
56 | "description": "Filter transactions to only transactions where this string value is found as a substring of either the reference or description fields. Format is arbitrary ASCII string. This parameter is optionally implemented by data holders. If it is not implemented then a response should be provided as normal without text filtering applied and an additional boolean field named isQueryParamUnsupported should be included in the meta object and set to true (whether the text parameter is supplied or not)",
57 | "description": "The list of products returned. If the filter results in an empty set then this array may have no records",
58 | "description": "A data holder specific unique identifier for this product. This identifier must be unique to a product but does not otherwise need to adhere to ID permanence guidelines.",
59 | "description": "URI reference to a PNG, JPG or GIF image with proportions defined by ISO 7810 ID-1 and width no greater than 512 pixels. The URI reference may be a link or url-encoded data URI [RFC 2397](https://tools.ietf.org/html/rfc2397)",
60 | "description": "Array of product IDs for products included in the bundle that are available via the product end points. Note that this array is not intended to represent a comprehensive model of the products included in the bundle and some products available for the bundle may not be available via the product reference end points",
61 | "description": "An optional list of discounts to this fee that may be available",
62 | "description": "The period after which the rate is applied to the balance to calculate the amount due for the period. Calculation of the amount is often daily (as balances may change) but accumulated until the total amount is 'applied' to the account (see applicationFrequency). Formatted according to [ISO 8601 Durations](https://en.wikipedia.org/wiki/ISO_8601#Durations) (excludes recurrence syntax)",
63 | "description": "The period after which the rate is applied to the balance to calculate the amount due for the period. Calculation of the amount is often daily (as balances may change) but accumulated until the total amount is 'applied' to the account (see applicationFrequency). Formatted according to [ISO 8601 Durations](https://en.wikipedia.org/wiki/ISO_8601#Durations) (excludes recurrence syntax)",
64 | "description": "The number of tierUnitOfMeasure units that form the lower bound of the tier. The tier should be inclusive of this value",
65 | "description": "The number of tierUnitOfMeasure units that form the upper bound of the tier or band. For a tier with a discrete value (as opposed to a range of values e.g. 1 month) this must be the same as tierValueMinimum. Where this is the same as the tierValueMinimum value of the next-higher tier the referenced tier should be exclusive of this value. For example a term deposit of 2 months falls into the upper tier of the following tiers: (1 – 2 months, 2 – 3 months). If absent the tier's range has no upper bound.",
66 | "description": "The method used to calculate the amount to be applied using one or more tiers. A single rate may be applied to the entire balance or each applicable tier rate is applied to the portion of the balance that falls into that tier (referred to as 'bands' or 'steps')",
67 | "description": "The list of accounts returned. If the filter results in an empty set then this array may have no records",
68 | "description": "The display name of the account as defined by the bank. This should not incorporate account numbers or PANs. If it does the values should be masked according to the rules of the MaskedAccountString common type."
69 | "description": "The unmasked account number for the account. Should not be supplied if the account number is a PAN requiring PCI compliance. Is expected to be formatted as digits only with leading zeros included and no punctuation or spaces"
70 | "description": "Current instructions on action to be taken at maturity. This includes default actions that may be specified in the terms and conditions for the product e.g. roll-over to the same term and frequency of interest payments",
71 | "description": "The accountIDs of the configured offset accounts attached to this loan. Only offset accounts that can be accessed under the current authorisation should be included. It is expected behaviour that offsetAccountEnabled is set to true but the offsetAccountIds field is absent or empty. This represents a situation where an offset account exists but details can not be accessed under the current authorisation",
72 | "description": "BPAY CRN for the transaction (if available).<br/>Where the CRN contains sensitive information, it should be masked in line with how the Data Holder currently displays account identifiers in their existing online banking channels. If the contents of the CRN match the format of a Credit Card PAN they should be masked according to the rules applicable for MaskedPANString. If the contents are are otherwise sensitive, then it should be masked using the rules applicable for the MaskedAccountString common type."
73 | "description": "The balance of the account at this time. Should align to the balance available via other channels such as Internet Banking. Assumed to be negative if the customer has money owing",
74 | "description": "BPAY CRN of the Biller (if available).<br/>Where the CRN contains sensitive information, it should be masked in line with how the Data Holder currently displays account identifiers in their existing online banking channels. If the contents of the CRN match the format of a Credit Card PAN they should be masked according to the rules applicable for MaskedPANString. If the contents are are otherwise sensitive, then it should be masked using the rules applicable for the MaskedAccountString common type."
75 | "description": "The short display name of the scheduled payment as provided by the customer if provided. Where a customer has not provided a nickname, a display name derived by the bank for the scheduled payment should be provided that is consistent with existing digital banking channels"
76 | "description": "The set of payment amounts and destination accounts for this payment accommodating multi-part payments. A single entry indicates a simple payment with one destination account. Must have at least one entry",
77 | "description": "The amount of the next payment if known. Mandatory unless the isAmountCalculated field is set to true. Must be zero or positive if present",
78 | "description": "Present if toUType is set to payeeId. Indicates that the payment is to registered payee that can be accessed using the payee end point. If the Bank Payees scope has not been consented to then a payeeId should not be provided and the full payee details should be provided instead",
79 | "description": "The short display name of the payee as provided by the customer unless toUType is set to payeeId. Where a customer has not provided a nickname, a display name derived by the bank for payee should be provided that is consistent with existing digital banking channels"
80 | "description": "The limit date after which no more payments should be made using this schedule. If both finalPaymentDate and paymentsRemaining are present then payments will stop according to the most constraining value. If neither field is present the payments will continue indefinitely",
81 | "description": "An array of interval objects defining the payment schedule. Each entry in the array is additive, in that it adds payments to the overall payment schedule. If multiple intervals result in a payment on the same day then only one payment will be made. Must have at least one entry",
82 | "description": "The limit date after which no more payments should be made using this schedule. If both finalPaymentDate and paymentsRemaining are present then payments will stop according to the most constraining value. If neither field is present the payments will continue indefinitely",
83 | "description": "The date and time that the current outage was detected. Should only be present if the status property is PARTIAL_FAILURE or UNAVAILABLE",
84 | "description": "The date and time that full service is expected to resume (if known). Should not be present if the status property has a value of OK.",
85 | "description": "List of scheduled outages. Property is mandatory but may contain and empty list if no outages are scheduled",
86 | "description": "The date and time that this record was last updated by the customer. If no update has occurred then this date should reflect the initial creation date for the data",
87 | "description": "For people with single names this field need not be present. The single name should be in the lastName field"
88 | "description": "For people with single names the single name should be in this field"
89 | "description": "Field is mandatory but array may be empty",
90 | "description": "Value is a valid [ANZSCO](http://www.abs.gov.au/ANZSCO) Standard Occupation classification code. If the occupation code held by the data holder is not one of the supported [ANZSCO](http://www.abs.gov.au/ANZSCO) versions, then it must not be supplied.",
91 | "description": "Array is mandatory but may be empty if no phone numbers are held",
92 | "description": "May be empty",
93 | "description": "Must contain at least one address. One and only one address may have the purpose of REGISTERED. Zero or one, and no more than one, record may have the purpose of MAIL. If zero then the REGISTERED address is to be used for mail",
94 | "description": "The date and time that this record was last updated by the customer. If no update has occurred then this date should reflect the initial creation date for the data",
95 | "description": "The first name of the individual providing access on behalf of the organisation. For people with single names this field need not be present. The single name should be in the lastName field"
96 | "description": "The last name of the individual providing access on behalf of the organisation. For people with single names the single name should be in this field"
97 | "description" : "A valid [ANZSIC](http://www.abs.gov.au/ANZSIC) code for the organisation. If the industry code held by the data holder is not one of the supported [ANZSIC](http://www.abs.gov.au/ANZSIC) versions, then it must not be supplied.",
98 | "description" : "The applicable [ANZSIC](http://www.abs.gov.au/ANZSIC) release version of the industry code provided. Should only be supplied if ``industryCode`` is also supplied. If ``industryCode`` is supplied but ``industryCodeVersion`` is absent, default is ``ANZSIC_1292.0_2006_V2.0``",
99 | "description": "Must contain at least one address. One and only one address may have the purpose of REGISTERED. Zero or one, and no more than one, record may have the purpose of MAIL. If zero then the REGISTERED address is to be used for mail",
100 | "description": "May be true for one and only one entry to indicate the preferred phone number. Assumed to be 'false' if not present",
101 | "description": "If absent, assumed to be Australia (+61). The + should be included"
102 | "description": "Required for non Mobile Phones, if field is present and refers to Australian code - the leading 0 should be omitted."
103 | "description": "May be true for one and only one email record in the collection. Denotes the default email address",
104 | "description": "Free text if the country is not Australia. If country is Australia then must be one of the values defined by the [State Type Abbreviation](https://auspost.com.au/content/dam/auspost_corp/media/documents/australia-post-data-guide.pdf) in the PAF file format. NSW, QLD, VIC, NT, WA, SA, TAS, ACT, AAT"
105 | "description": "The code of the error encountered. Where the error is specific to the respondent, an application-specific error code, expressed as a string value. If the error is application-specific, the URN code that the specific error extends must be provided in the meta object. Otherwise, the value is the error code URN."
106 |

107 | 108 | 109 | --------------------------------------------------------------------------------