Cedar Profile for OAuth 2.0 Rich Authorization Requests

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

Table of Contents

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

{
"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\"
        };
"
}

Finally, this specification provides security and privacy considerations meant to prevent common mistakes and anti patterns that are likely to occur.¶

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".¶

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 3 shows a combined request asking for access to account information and permission to initiate a payment:¶

[
 {
   "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\"
                                };
                        "
        }
]

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

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\"
                                        };
                                "
                        }
   ]
}

4. Security Considerations

[[todo]]¶

5. Privacy Considerations

[[todo]]¶

6. IANA Considerations

[[todo]]¶

Appendix A. Acknowledgements

[[todo]]¶

Appendix B. Document History

Author's Address