Internet-Draft OAuth Access Token JWT Profile February 2024
Cecchetti Expires 24 August 2024 [Page]
Workgroup:
OAuth Working Group
Internet-Draft:
draft-cecchetti-oauth-rar-cedar-01
Published:
Intended Status:
Standards Track
Expires:
Author:
S. Cecchetti
Amazon

Cedar Profile for OAuth 2.0 Rich Authorization Requests

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.

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

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:

[
 {
   "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:

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

7.2. Informative References

Appendix A. Acknowledgements

[[todo]]

Appendix B. Document History

Author's Address

Sarah Cecchetti
Amazon