OAuth Working Group S. Cecchetti Internet-Draft Amazon Intended status: Standards Track 21 February 2024 Expires: 24 August 2024 Cedar Profile for OAuth 2.0 Rich Authorization Requests draft-cecchetti-oauth-rar-cedar-02 Abstract This specification defines a profile of OAuth 2.0 Rich Authorization Requests in Cedar policy format within the authorization_details JSON object. Authorization servers and resource servers from different vendors can leverage this profile to distribute and recieve relevant Cedar policy sets in an interoperable manner. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 24 August 2024. Copyright Notice Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Cecchetti Expires 24 August 2024 [Page 1] Internet-Draft OAuth Access Token JWT Profile February 2024 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1.1. Requirements Notation and Conventions . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 2. Request in Cedar Policy Format . . . . . . . . . . . . . . . 3 7. Token Response . . . . . . . . . . . . . . . . . . . . . . . 5 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 5. Privacy Considerations . . . . . . . . . . . . . . . . . . . 6 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 7.1. Normative References . . . . . . . . . . . . . . . . . . 6 7.2. Informative References . . . . . . . . . . . . . . . . . 7 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 7 Appendix B. Document History . . . . . . . . . . . . . . . . . . 7 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction The original Auth 2.0 Rich Authorization Requests specification does not mandate any specific format for an authorization_detail parameter. This specification aims to provide a standardized and interoperable profile as an alternative to proprietary authorization_detail formats. The purpose of a Cedar policy response format is to enable an authorization server to provide a client with a set of permissions in the format of Cedar policies which enable the client and the resource server to have a shared understanding, signed by the authorization server, of what actions are permissable in what contexts. For example, an authorization request for a credit transfer (designated as "payment initiation" in several open banking initiatives) can be represented using a Cedar policy within a JSON object with double quote marks escaped like this: Cecchetti Expires 24 August 2024 [Page 2] Internet-Draft OAuth Access Token JWT Profile February 2024 { "type": "payment_initiation" "rarFormat": "cedar", "policySet": " permit ( principal == BankA::User::\"696d28c8-8912-41d2-b182-aa7087323318\", action == BankA::Action::\"initiate\", resource == Creditor::\"https://example.com/payments\" ) when { context.instructedAmount.currency == \"EUR\" && context.instructedAmount.amount == decimal(\"123.50\") && resource.creditorName == \"Merchant A\" && resource.creditorAccount.bic == \"ABCIDEFFXXX\" && resource.creditorAccount.iban == \"DE02100100109307118603\" && context.remittanceInformationUnstructured == \"Ref Number Merchant\" }; " } Figure 1: Example of a Cedar Authorization Request for a Credit Transfer Finally, this specification provides security and privacy considerations meant to prevent common mistakes and anti patterns that are likely to occur. 1.1. Requirements Notation and Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. 1.2. Terminology This specification uses the terms "access token", "refresh token", "authorization server", "resource server", "authorization endpoint", "authorization request", "authorization response", "token endpoint", "grant type", "access token request", "access token response", and "client" defined by The OAuth 2.0 Authorization Framework. 2. Request in Cedar Policy Format The authorization_details parameter in a Rich Authorization Request token request MAY contain the field "rarFormat" and in order to be compliant with this profile that field MUST equal the value "cedar". Cecchetti Expires 24 August 2024 [Page 3] Internet-Draft OAuth Access Token JWT Profile February 2024 An authorization_details array MAY contain multiple entries of the same type. Figure 2 shows an authorization_details of type payment_initiation using the example data shown above: [ { "type": "payment_initiation" "rarFormat": "cedar", "policySet": " permit ( principal == BankA::User::\"696d28c8-8912-41d2-b182-aa7087323318\", action in [BankA::Action::\"initiate\", BankA::Action::\"status\", BankA::Action::\"cancel\"], resource == Creditor::\"https://example.com/payments\" ) when { context.instructedAmount.currency == \"EUR\" && context.instructedAmount.amount == decimal(\"123.50\") && resource.creditorName == \"Merchant A\" && resource.creditorAccount.iban == \"DE02100100109307118603\" && context.remittanceInformationUnstructured == \"Ref Number Merchant\" }; " } ] Figure 2: Example of "authorization_details" for a Credit Transfer Figure 3 shows a combined request asking for access to account information and permission to initiate a payment: Cecchetti Expires 24 August 2024 [Page 4] Internet-Draft OAuth Access Token JWT Profile February 2024 [ { "type": "account_information" "rarFormat": "cedar", "policySet": " permit ( principal == BankA::User::\"696d28c8-8912-41d2-b182-aa7087323318\", action in [BankA::Action::\"list_accounts\", BankA::Action::\"read_balances\", BankA::Action::\"read_transactions\"], resource == BankA::\"https://example.com/accounts\" ); " }, { "type": "payment_initiation" "rarFormat": "cedar", "policySet": " permit ( principal == BankA::User::\"696d28c8-8912-41d2-b182-aa7087323318\", action in [BankA::Action::\"initiate\", BankA::Action::\"status\", BankA::Action::\"cancel\"], resource == Creditor::\"https://example.com/payments\" ) when { context.instructedAmount.currency == \"EUR\" && context.instructedAmount.amount == decimal(\"123.50\") && resource.creditorName == \"Merchant A\" && resource.creditorAccount.iban == \"DE02100100109307118603\" && context.remittanceInformationUnstructured == \"Ref Number Merchant\" }; " } ] Figure 3: Example of "authorization_details" for a Combined Request 7. Token Response The authorization_details parameter in a Rich Authorization Request token response MAY contain the field "rarFormat" and that field MUST equal the value "cedar". The AS MAY respond with policies in the authorization_details to the client which are less permissive than the policies requested. For our running example, it would look like this: Cecchetti Expires 24 August 2024 [Page 5] Internet-Draft OAuth Access Token JWT Profile February 2024 HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store { "access_token": "2YotnFZFEjr1zCsicMWpAA", "token_type": "example", "expires_in": 3600, "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA", "authorization_details": [ { "type": "payment_initiation" "rarFormat": "cedar", "policySet": " permit ( principal == BankA::User::\"696d28c8-8912-41d2-b182-aa7087323318\", action in [BankA::Action::\"initiate\", BankA::Action::\"status\", BankA::Action::\"cancel\"], resource == Creditor::\"https://example.com/payments\" ) when { context.instructedAmount.currency == \"EUR\" && context.instructedAmount.amount == decimal(\"123.50\") && resource.creditorName == \"Merchant A\" && resource.creditorAccount.iban == \"DE02100100109307118603\" && context.remittanceInformationUnstructured == \"Ref Number Merchant\" }; " } ] } Figure 4: Example Token Response 4. Security Considerations [[todo]] 5. Privacy Considerations [[todo]] 6. IANA Considerations [[todo]] 7. References 7.1. Normative References Cecchetti Expires 24 August 2024 [Page 6] Internet-Draft OAuth Access Token JWT Profile February 2024 7.2. Informative References Appendix A. Acknowledgements [[todo]] Appendix B. Document History Author's Address Sarah Cecchetti Amazon Email: sarahcec@amazon.com Cecchetti Expires 24 August 2024 [Page 7]