Cedar Profile for OAuth 2.0 Rich Authorization RequestsAmazonsarahcec@amazon.com
Security
OAuth Working GroupOAuth
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.
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:
Example of a Cedar Authorization Request for a Credit Transfer
{
"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.
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.
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.
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. shows an authorization_details of type payment_initiation using the example data shown above:Example of "authorization_details" for a Credit Transfer
[
{
"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\"
};
"
}
]
shows a combined request asking for access to account information and permission to initiate a payment:Example of "authorization_details" for a Combined Request
[
{
"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\"
};
"
}
]
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:Example Token Response
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\"
};
"
}
]
}
[[todo]]
[[todo]]
[[todo]]
[[todo]]