Skip to main content

Appendix A. Additional Examples

A.1. OpenID Connect​

OpenID Connect [OpenID.Core] defines a claims parameter to request identity claims about the end user. This parameter can be used in an authorization request as defined in Section 5.5 of [OpenID.Core] or in a request object as defined in Section 6.1 of [OpenID.Core].

With RAR, the client can alternatively use an authorization details object of type openid_credential to request issuance of an OpenID Connect ID Token with specific claims. The following example shows how the client can request issuance of an ID Token that includes the email and email_verified claims:

[
   {
      "type": "openid_credential",
      "credential_type": "id_token",
      "locations": ["https://example.com"],
      "claims": {
         "email": null,
         "email_verified": null
      }
   }
]

The authorization details object of type openid_credential with a credential_type of id_token MAY contain the following elements:

  • type: REQUIRED. String that determines the authorization details type. For issuance of an OpenID Connect ID Token, this value MUST be openid_credential.
  • credential_type: REQUIRED. String that determines the type of credential to be issued. For an OpenID Connect ID Token, this MUST be id_token.
  • locations: OPTIONAL. Array of strings, each representing a URI of a resource server where the credential will be used.
  • claims: OPTIONAL. An object describing the claims to be embedded in the credential. The value is a JSON object with the names of the requested claims as member names and null or a JSON object as member values to express specific claim requirements.

A.2. Transaction-Specific Authorization​

This example illustrates how RAR can be used to express authorization for a payment transaction. The example assumes a credit transfer between accounts.

The type value used is payment_initiation, which is the identifier of a (fictitious) authorization details type for payment initiation.

An example authorization request could look like this:

GET /authorize?response_type=code
   &client_id=s6BhdRkqt3
   &state=af0ifjsldkj
   &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
   &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bww-uCHaoeK1t8U
   &code_challenge_method=S256
   &authorization_details=%5B%7B%22type%22%3A%22payment_initiation%22%2C%0A%20%20%20%20%20%20%22actions%22%3A%5B%22initiate%22%2C%22status%22%2C%22cancel%22%5D%2C%0A%20%20%20%20%20%20%22locations%22%3A%5B%22https%3A%2F%2Fexample%2Ecom%2Fpayments%22%5D%2C%0A%20%20%20%20%20%20%22instructedAmount%22%3A%7B%0A%20%20%20%20%20%20%20%20%20%22currency%22%3A%22EUR%22%2C%0A%20%20%20%20%20%20%20%20%20%22amount%22%3A%22123%2E50%22%0A%20%20%20%20%20%20%7D%2C%0A%20%20%20%20%20%20%22creditorName%22%3A%22Merchant%20A%22%2C%0A%20%20%20%20%20%20%22creditorAccount%22%3A%7B%0A%20%20%20%20%20%20%20%20%20%22iban%22%3A%22DE02100100109307118603%22%0A%20%20%20%20%20%20%7D%2C%0A%20%20%20%20%20%20%22remittanceInformationUnstructured%22%3A%22Ref%20Number%20Merchant%22%0A%20%20%20%7D%5D HTTP/1.1
Host: as.example.com

The authorization_details parameter, URL decoded for better readability, contains the following JSON document:

[
   {
      "type": "payment_initiation",
      "actions": ["initiate", "status", "cancel"],
      "locations": ["https://example.com/payments"],
      "instructedAmount": {
         "currency": "EUR",
         "amount": "123.50"
      },
      "creditorName": "Merchant A",
      "creditorAccount": {
         "iban": "DE02100100109307118603"
      },
      "remittanceInformationUnstructured": "Ref Number Merchant"
   }
]

The authorization details object for payment initiation contains the following elements:

  • type: REQUIRED. The type of authorization details, which is payment_initiation for this example.
  • actions: OPTIONAL. Array of strings, representing the actions that the client is requesting authorization to perform. In this example, initiate means creating a new payment, status means reading the status of a payment, and cancel means canceling a payment.
  • locations: OPTIONAL. Array of strings representing the locations where the client intends to spend the access token.
  • instructedAmount: REQUIRED. Object with two elements, currency and amount, representing the amount to be transferred.
  • creditorName: REQUIRED. String representing the name of the merchant.
  • creditorAccount: REQUIRED. Object containing the account number of the merchant. In this example, the account is represented as an IBAN (International Bank Account Number), but other representations are possible.
  • remittanceInformationUnstructured: OPTIONAL. String representing the remittance information for the payment.

A.3. Multiple Access Tokens​

This example illustrates how a client can request authorization to have two different access tokens issued, one to be used at the payment_api resource and another to be used at the account_api resource.

[
   {
      "type": "payment_initiation",
      "locations": ["https://example.com/payment_api"],
      "instructedAmount": {
         "currency": "EUR",
         "amount": "123.50"
      },
      "creditorName": "Merchant A",
      "creditorAccount": {
         "iban": "DE02100100109307118603"
      }
   },
   {
      "type": "account_information",
      "locations": ["https://example.com/account_api"],
      "accounts": [
         {
            "iban": "DE40100100103307118608"
         },
         {
            "iban": "DE40100100103307118888"
         }
      ]
   }
]

In this example, the client requests authorization for two different authorization details objects:

  1. A payment_initiation authorization to be used at https://example.com/payment_api
  2. An account_information authorization to be used at https://example.com/account_api

If the AS decides to issue separate access tokens for each resource, the client can make two separate token requests:

Token Request 1 (for payment_api):

POST /token HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&code_verifier=3641c0461d016ba09c5796b3e7cc5...
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&authorization_details=%5B%7B%22type%22%3A%22payment_initiation%22%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample.com%2Fpayment_api%22%5D%7D%5D

Token Request 2 (for account_api):

POST /token HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&code_verifier=3641c0461d016ba09c5796b3e7cc5...
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
&authorization_details=%5B%7B%22type%22%3A%22account_information%22%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample.com%2Faccount_api%22%5D%7D%5D

A.4. Enriched Authorization Details in Token Response​

This example shows an authorization details object of type payment_initiation that has been enriched by the AS in the token response with additional data such as the date of the authorization:

{
   "type": "payment_initiation",
   "actions": ["initiate", "status", "cancel"],
   "locations": ["https://example.com/payments"],
   "instructedAmount": {
      "currency": "EUR",
      "amount": "123.50"
   },
   "creditorName": "Merchant A",
   "creditorAccount": {
      "iban": "DE02100100109307118603"
   },
   "remittanceInformationUnstructured": "Ref Number Merchant",
   "date": "2021-08-12"
}

The date field has been added by the AS to indicate when the authorization was granted.

Last updated on