Internet DRAFT - draft-cecchetti-oauth-rar-cedar

draft-cecchetti-oauth-rar-cedar







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]