OAuth 2.0 Rich Authorization Requests

1.1. Conventions and Terminology

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 [RFC2119] [RFC8174] 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 [RFC6749].¶

2.1. Authorization data elements types

The allowable contents of the authorization details object are determined by the type parameter.¶

type:

The type of authorization data as a string. This field MAY define which other elements are allowed in the request. This element is REQUIRED.¶

This field MUST be compared using an exact byte match of the string value against known types by the AS. The AS MUST ensure that there is no collision between different authorization data types that it supports. The AS MUST NOT do any collation or normalization of data types during comparison.¶

This draft defines a set of common data elements that are designed to be usable across different types of APIs. These data elements MAY be combined in different ways depending on the needs of the API. All data elements are OPTIONAL.¶

locations:

An array of strings representing the location of the resource or resource server. This is typically composed of URIs.¶

actions:

An array of strings representing the kinds of actions to be taken at the resource. The values of the strings are determined by the API being protected.¶

datatypes:

An array of strings representing the kinds of data being requested from the resource.¶

identifier:

A string identifier indicating a specific resource available at the API.
¶

When different element types are used in combination, the permissions the client requests is the cartesian product of the values. That is to say, the object represents a request for all action values listed within the object to be used at all locations values listed within the object for all datatype values listed within the object. In the following example, the client is requesting read and write access to both the contacts and photos belonging to customers in a customer_information API. If this request is granted, the client would assume it would be able to use any combination of rights defined by the API, such as reading the photos and writing the contacts.¶

[
   {
      "type": "customer_information",
      "locations": [
         "https://example.com/customers",
      ]
      "actions": [
         "read",
         "write"
      ],
      "datatypes": [
         "contacts",
         "photos"
      ]
   }
]

If the client wishes to have finer control over its access, it can send multiple objects. In this example, the client is asking for read access to the contacts and write access to the photos in the same API endpoint. If this request is granted, the client would not be able to write to the contacts.¶

[
   {
      "type": "customer_information",
      "locations": [
         "https://example.com/customers"
      ],
      "actions": [
         "read"
      ],
      "datatypes": [
         "contacts"
      ]
   },
   {
      "type": "customer_information",
      "locations": [
         "https://example.com/customers"
      ],
      "actions": [
         "write"
      ],
      "datatypes": [
         "photos"
      ]
   }
]

An API MAY define its own extensions, subject to the type of the respective authorization object. It is anticipated that API designers will use a combination of common fields defined in this specification as well as fields specific to the API itself. The following non-normative example shows the use of both common and API-specific fields as part of two different fictitious API type values. The first access request includes the actions, locations, and datatypes fields specified here as well as the API-specific geolocation field. The second access request includes the actions and identifier fields specified here as well as the API-specific currency field.¶

    "resources": [
        {
            "type": "photo-api",
            "actions": [
                "read",
                "write"
            ],
            "locations": [
                "https://server.example.net/",
                "https://resource.local/other"
            ],
            "datatypes": [
                "metadata",
                "images"
            ],
            "geolocation": [
                { lat: -32.364, lng: 153.207 },
                { lat: -35.364, lng: 158.207 }
            ]
        },
        {
            "type": "financial-transaction",
            "actions": [
                "withdraw"
            ],
            "identifier": "account-14-32-32-3",
            "currency": "USD"
        }
    ]

If this request is approved, the resulting access token's access rights will be the union of the requested types of access for each of the two APIs, just as above.¶

2.2. Authorization Data Types

Interpretation of the value of the type parameter, and the object elements that the type parameter allows, is under the control of the AS. However, the value of the type parameter is also generally documented and intended to be used by developers, it is RECOMMENDED that API designers choose type values that are easily copied without ambiguity. For example, some glyphs have multiple unicode code points for the same visual character, and a developer could potentially type a different character depending than what the AS has defined. Possible means of reducing potential confusion are limiting the value to ASCII characters, providing a machine-readable listing of data type values, or instructing developers to copy and paste directly from documentation.¶

If an application or API is expected to be deployed across different servers, such as the case in an open standard, the API designer is RECOMMENDED to use a collision-resistant namespace under their control, such as a URI that the API designer controls.¶

The following example shows how an implementation could utilize the namespace https://scheme.example.org/ to ensure collision resistant element names.¶

{
   "type": "https://scheme.example.org/files",
   "locations": [
      "https://example.com/files"
   ],
   "permissions": [
      {
         "path": "/myfiles/A",
         "access": [
            "read"
         ]
      },
      {
         "path": "/myfiles/A/X",
         "access": [
            "read",
            "write"
         ]
      }
   ]
}

3.1. Relationship to "scope" parameter

authorization_details and scope can be used in the same authorization request for carrying independent authorization requirements.¶

The AS MUST consider both sets of requirements in combination with each other for the given authorization request. The details of how the AS combines these parameters are specific to the APIs being protected and outside the scope of this specification.¶

It is RECOMMENDED that a given API uses only one form of requirement specification.¶

When gathering user consent, the AS MUST present the merged set of requirements represented by the authorization request.¶

If the resource owner grants the client the requested access, the AS will issue tokens to the client that are associated with the respective authorization_details (and scope values, if applicable).¶

3.2. Relationship to "resource" parameter

The resource authorization request parameter as defined in [RFC8707] can be used to further determine the resources where the requested scope can be applied. The resource parameter does not have any impact on the way the AS processes the authorization_details parameter.¶

7.1. Enriched authorization details in Token Response

The authorization details attached to the access token MAY differ from what the client requests. In addition to the user authorizing less than what the client requested, there are use cases where the authorization server enriches the data in an authorization details object. For example, a client may ask for access to account information but leave the decision about the accounts it will be able to access to the user. The user would select the sub set of accounts they wants the client to entitle to access in the course of the authorization process. In order to allow the client to determine the accounts it is entitled to access, the authorization server will add this information to the respective authorization details object.¶

As an example, the requested authorization detail parameter could look like this:¶

"authorization_details": [
   {
      "type": "account_information",
      "access": {
         "accounts": [],
         "balances": [],
         "transactions": []
      },
      "recurringIndicator":true
   }
]

The authorization server then would expand the authorization details object and add the respective account identifiers.¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache, no-store

{
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "token_type":"example",
   "expires_in":3600,
   "refresh_token":"tGzv3JokF0XG5Qx2TlKWIA",
   "authorization_details":[
      {
         "type":"account_information",
         "access":{
            "accounts":[
               {
                  "iban":"DE2310010010123456789"
               },
               {
                  "maskedPan":"123456xxxxxx1234"
               }
            ],
            "balances":[
               {
                  "iban":"DE2310010010123456789"
               }
            ],
            "transactions":[
               {
                  "iban":"DE2310010010123456789"
               },
               {
                  "maskedPan":"123456xxxxxx1234"
               }
            ]
         },
         "recurringIndicator":true
      }
   ]
}

For another example, the client is asking for access to a medical record but does not know the record number at request time. In this example, the client specifies the type of access it wants but doesn't specify the location or identifier of that access.¶

{
"authorization_details": [
   {
      "type": "medical_record",
      "sens": [ "HIV", "ETH", "MART" ],
      "actions": [ "read" ],
      "datatypes": [ "Patient", "Observation", "Appointment" ]
   }
]

When the user interacts with the AS, they select which of the medical records they are responsible for to give to the client. This information gets returned with the access token.¶

{
   "access_token":"2YotnFZFEjr1zCsicMWpAA",
   "token_type":"example",
   "expires_in":3600,
   "refresh_token":"tGzv3JokF0XG5Qx2TlKWIA",
   "authorization_details":[
    {
      "type": "medical_record",
      "sens": [ "HIV", "ETH", "MART" ],
      "actions": [ "read" ],
      "datatypes": [ "Patient", "Observation", "Appointment" ]
      "identifier": "patient-541235",
      "locations": [ "https://records.example.com/" ]
     }
  ]
}

Note: the client needs to be aware upfront of the possibility that a certain authorization details object can be enriched. It is assumned that this property is part of the definition of the respective authorization details type.¶

8.1. JWT-based Access Tokens

If the access token is a JWT [RFC7519], the AS is RECOMMENDED to add the authorization_details object, filtered to the specific audience, as top-level claim.¶

The AS will typically also add further claims to the JWT the RS requires for request processing, e.g., user id, roles, and transaction specific data. What claims the particular RS requires is defined by the RS-specific policy with the AS.¶

The following shows the contents of an example JWT for the payment initation example above:¶

{
   "iss": "https://as.example.com",
   "sub": "24400320",
   "aud": "a7AfcPcsl2",
   "exp": 1311281970,
   "acr": "psd2_sca",
   "txn": "8b4729cc-32e4-4370-8cf0-5796154d1296",
   "authorization_details": [
      {
         "type": "https://www.someorg.com/payment_initiation",
         "actions": [
            "initiate",
            "status",
            "cancel"
         ],
         "locations": [
            "https://example.com/payments"
         ],
         "instructedAmount": {
            "currency": "EUR",
            "amount": "123.50"
         },
         "creditorName": "Merchant123",
         "creditorAccount": {
            "iban": "DE02100100109307118603"
         },
         "remittanceInformationUnstructured": "Ref Number Merchant"
      }
   ],
   "debtorAccount": {
      "iban": "DE40100100103307118608",
      "user_role": "owner"
   }
}

In this case, the AS added the following example claims:¶

• sub: conveys the user on which behalf the client is asking for payment initation¶

• txn: transaction id used to trace the transaction across the services of provider example.com¶

• debtorAccount: API-specific element containing the debtor account. In the example, this account was not passed in the authorization details but selected by the user during the authorization process. The field user_role conveys the role the user has with respect to this particuar account. In this case, they is the owner. This data is used for access control at the payment API (the RS).¶

8.2. Token Introspection

In case of opaque access tokens, the data provided to a certain RS is determined using the RS's identifier with the AS (see [I-D.ietf-oauth-jwt-introspection-response], section 3).¶

The token endpoint response provides the RS with the authorization details applicable to it as a top-level JSON element along with the claims the RS requires for request processing.¶

Here is an example for the payment initation example RS:¶

{
   "active": true,
   "sub": "24400320",
   "aud": "s6BhdRkqt3",
   "exp": 1311281970,
   "acr": "psd2_sca",
   "txn": "8b4729cc-32e4-4370-8cf0-5796154d1296",
   "authorization_details": [
      {
         "type": "https://www.someorg.com/payment_initiation",
         "actions": [
            "initiate",
            "status",
            "cancel"
         ],
         "locations": [
            "https://example.com/payments"
         ],
         "instructedAmount": {
            "currency": "EUR",
            "amount": "123.50"
         },
         "creditorName": "Merchant123",
         "creditorAccount": {
            "iban": "DE02100100109307118603"
         },
         "remittanceInformationUnstructured": "Ref Number Merchant"
      }
   ],
   "debtorAccount": {
      "iban": "DE40100100103307118608",
      "user_role": "owner"
   }
}

11.1. Using authorization details in a certain deployment

Using authorization details in a certain deployment will require the follwowing steps:¶

• Define authorization details types (might include definition and publication of JSON schemas)¶

• Publish authorization details types in the OAuth server metadata¶

• Determine how authorization details are shown to the user in the user consent¶

• (if needed) Enrich authorization details in the user consent process (e.g. add selected accounts or set expirations)¶

• (if needed) Determine how authorization details are reflected in access token content or introspection responses¶

• Determine how the resource server(s) process(s) the authorization details or token data derived from authorization details¶

11.2. Minimal product support

Products supporting this specification should provide the following basic functions:¶

• Support advertisement of supported authorization details types in OAuth server metadata¶

• Accept authorization_details parameter in authorization requests including basic syntax check for compliance with this specification¶

• Support storage of consented authorization_details as part of a grant¶

• Implement default behavior for adding authorization details to access tokens and token introspection responses in order to make them available to resource servers (similar to scope values). This should work with any grant type, espceially authorization_code and refresh_token.¶

• If the product supports resource indicators, it should also support filtering of the authorization details to be assigned to access tokens using the resource token request parameter.¶

Processing and presentation of authorization details will vary significantly among different authorization data types. Products should therefore support customization of the respective behavior. In particular products should¶

• allow deployments to determine presentation of the authorization_details¶

• allow deployments to modify requested authorization_details in the user consent process, e.g. adding fields¶

• allow deployments to merge requested and pre-existing authorization_details¶

One option would be to have a mechanism allowing the registration of extension modules, each of them responsible for rendering the respective user consent and any transformation needed to provide the data needed to the resource server by way of structured access tokens or token introspection responses.¶

11.3. Large requests

Authorization request URIs containing authorization details in a request parameter or a request object can become very long. Implementers SHOULD therefore consider using the request_uri parameter as defined in [I-D.ietf-oauth-jwsreq] in combination with the pushed request object mechanism as defined in [I-D.ietf-oauth-par] to pass authorization details in a reliable and secure manner. Here is an example of such a pushed authorization request that sends the authorization request data directly to the AS via a HTTPS-protected connection:¶

  POST /as/par HTTP/1.1
  Host: as.example.com
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3

  response_type=code&
  client_id=s6BhdRkqt3
  &state=af0ifjsldkj
  &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
  &code_challenge_method=S256
  &code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U
  &authorization_details=%5B%7B%22type%22%3A%22account_information%22
  %2C%22actions%22%3A%5B%22list_accounts%22%2C%22read_balances%22%2C%
  22read_transactions%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fe
  xample.com%2Faccounts%22%5D%7D%2C%7B%22type%22%3A%22payment_initiat
  ion%22%2C%22actions%22%3A%5B%22initiate%22%2C%22status%22%2C%22canc
  el%22%5D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample.com%2Fpaym
  ents%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22%3A%22EUR%22
  %2C%22amount%22%3A%22123.50%22%7D%2C%22creditorName%22%3A%22Merchan
  t123%22%2C%22creditorAccount%22%3A%7B%22iban%22%3A%22DE021001001093
  07118603%22%7D%2C%22remittanceInformationUnstructured%22%3A%22Ref%2
  0Number%20Merchant%22%7D%5D

A.1. OpenID Connect

These hypothetical examples try to encapsulate all details specific to the OpenID Connect part of an authorization process into an authorization JSON object.¶

The top-level elements are based on the definitions given in [OIDC]:¶

• claim_sets: names of predefined claim sets, replacement for respective scope values, such as profile¶

• max_age: Maximum Authentication Age¶

• acr_values: array of ACR values¶

• claims: the claims JSON structure as defined in [OIDC]¶

This is a simple request for some claim sets.¶

[
   {
      "type": "openid",
      "locations": [
         "https://op.example.com/userinfo"
      ],
      "claim_sets": [
         "email",
         "profile"
      ]
   }
]

Note: locations specifies the location of the userinfo endpoint since this is the only place where an access token is used by a client (RP) in OpenID Connect to obtain claims.¶

A more sophisticated example is shown in the following¶

[
   {
      "type": "openid",
      "locations": [
         "https://op.example.com/userinfo"
      ],
      "max_age": 86400,
      "acr_values": "urn:mace:incommon:iap:silver",
      "claims": {
         "userinfo": {
            "given_name": {
               "essential": true
            },
            "nickname": null,
            "email": {
               "essential": true
            },
            "email_verified": {
               "essential": true
            },
            "picture": null,
            "http://example.info/claims/groups": null
         },
         "id_token": {
            "auth_time": {
               "essential": true
            }
         }
      }
   }
]

A.2. Remote Electronic Signing

The following example is based on the concept layed out for remote electronic signing in ETSI TS 119 432 [ETSI] and the CSC API for remote signature creation [CSC].¶

[
   {
      "type": "sign",
      "locations": [
         "https://signing.example.com/signdoc"
      ],
      "credentialID": "60916d31-932e-4820-ba82-1fcead1c9ea3",
      "documentDigests": [
         {
            "hash": "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=",
            "label": "Credit Contract"
         },
         {
            "hash": "HZQzZmMAIWekfGH0/ZKW1nsdt0xg3H6bZYztgsMTLw0=",
            "label": "Contract Payment Protection Insurance"
         }
      ],
      "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1"
   }
]

The top-level elements have the following meaning:¶

• credentialID: identifier of the certificate to be used for signing¶

• documentDigests: array containing the hash of every document to be signed (hash elements). Additionally, the corresponding label element identifies the respective document to the user, e.g. to be used in user consent.¶

• hashAlgorithm: algomrithm that was used to calculate the hash values.¶

The AS is supposed to ask the user for consent for the creation of signatues for the documents listed in the structure. The client uses the access token issued as result of the process to call the sign doc endpoint at the respective signing service to actually create the signature. This access token is bound to the client, the user id and the hashes (and signature algorithm) as consented by the user.¶

A.3. Access to Tax Data

This example is inspired by an API allowing third parties to access citizen's tax declarations and income statements, for example to determine their credit worthiness.¶

[
    {
        "type": "tax_data",
        "locations": [
            "https://taxservice.govehub.no"
        ],
        "actions":"read_tax_declaration",
        "periods": ["2018"],
        "duration_of_access": 30,
        "tax_payer_id": "23674185438934"
    }
]

The top-level elements have the following meaning:¶

• periods: determines the periods the client wants to access¶

• duration_of_access: how long does the client intend to access the data in days¶

• tax_payer_id: identifier of the tax payer (if known to the client)¶

A.4. eHealth

These two examples are inspired by requirements for APIs used in the Norwegian eHealth system.¶

In this use case the physical therapist sits in front of her computer using a local Electronic Health Records (EHR) system. They wants to look at the electronic patient records of a certain patient and they also wants to fetch the patients journal entries in another system, perhaps at another institution or a national service. Access to this data is provided by an API.¶

The information necessary to authorize the request at the API is only known by the EHR system, and must be presented to the API.¶

In the first example the authorization details object contains the identifier of an organization. In this case the API needs to know if the given organization has the lawful basis for processing personal health information to give access to sensitive data.¶

"authorization_details":{
    "type":"patient_record",
    "requesting_entity": {
        "type": "Practitioner",
        "identifier": [
        {
            "system": " urn:oid:2.16.578.1.12.4.1.4.4",
            "value": "1234567"
        }],
        "practitioner_role":{
            "organization":{
                "identifier": {
                    "system":"urn:oid:2.16.578.1.12.4.1.2.101",
                    "type":"ENH",
                    "value":"[organizational number]"
                }
            }
        }
    }
}

In the second example the API requires more information to authorize the request. In this case the authorization details object contains additional information about the health institution and the current profession the user has at the time of the request. The additional level of detail could be used for both authorization and data minimization.¶

[
   {
      "type": "patient_record",
      "location": "https://fhir.example.com/patient",
      "actions": [
         "read"
      ],
      "patient_identifier": [
         {
            "system": "urn:oid:2.16.578.1.12.4.1.4.1",
            "value": "12345678901"
         }
      ],
      "reason_for_request": "Clinical treatment",
      "requesting_entity": {
         "type": "Practitioner",
         "identifier": [
            {
               "system": " urn:oid:2.16.578.1.12.4.1.4.4",
               "value": "1234567"
            }
         ],
         "practitioner_role": {
            "organization": {
               "identifier": [
                  {
                     "system": "urn:oid:2.16.578.1.12.4.1.2.101",
                     "type": "ENH",
                     "value": "<organizational number>"
                  }
               ],
               "type": {
                  "coding": [
                     {
                        "system":
                           "http://hl7.org/fhir/organization-type",
                        "code": "dept",
                        "display": "Hospital Department"
                     }
                  ]
               },
               "name": "Akuttmottak"
            },
            "profession": {
               "coding": [
                  {
                     "system": "http://snomed.info/sct",
                     "code": "36682004",
                     "display": "Physical therapist"
                  }
               ]
            }
         }
      }
   }
]

Description of the elements:¶

• patient_identifier: the identifier of the patient composed of a system identifier in OID format (namespace) and the acutal value within this namespace.¶

• reason_for_request: the reason why the user wants to access a certain API¶

• requesting_entity: specification of the requester by means of identity, role and organizational context. This data is provided to facilitate authorization and for auditing purposes.¶

In this use case, the AS authenticates the requester, who is not the patient, and approves access based on policies.¶