Diff: rfc9396.original.xml

	rfc9396.original.xml	rfc9396.xml

	<?xml version="1.0" encoding="utf-8"?>	<?xml version="1.0" encoding="UTF-8"?>
	<!-- name="GENERATOR" content="github.com/mmarkdown/mmark Mmark Markdown Process
	or - mmark.miek.nl" -->	<!DOCTYPE rfc [
	<rfc version="3" ipr="trust200902" docName="draft-ietf-oauth-rar-22" submissionT	<!ENTITY nbsp " ">
	ype="IETF" category="std" xml:lang="en" xmlns:xi="http://www.w3.org/2001/XInclud	<!ENTITY zwsp "">
	e" indexInclude="true" consensus="true">	<!ENTITY nbhy "‑">
		<!ENTITY wj "⁠">
		]>

		<rfc version="3" ipr="trust200902" docName="draft-ietf-oauth-rar-23" number="939
		6" submissionType="IETF" category="std" consensus="true" xml:lang="en" xmlns:xi=
		"http://www.w3.org/2001/XInclude" tocInclude="true" sortRefs="true" symRefs="tru
		e" updates="" obsoletes="" indexInclude="true">

	<front>	<front>

	<title abbrev="oauth-rar">OAuth 2.0 Rich Authorization Requests</title><seriesIn	<title abbrev="OAuth-RAR">OAuth 2.0 Rich Authorization Requests</title>
	fo value="draft-ietf-oauth-rar-22" stream="IETF" status="standard" name="Interne	<seriesInfo name="RFC" value="9396"/>
	t-Draft"></seriesInfo>	<author initials="T." surname="Lodderstedt" fullname="Torsten Lodderstedt">
	<author initials="T." surname="Lodderstedt" fullname="Torsten Lodderstedt"><orga	<organization>yes.com</organization><address><postal><street></street>
	nization>yes.com</organization><address><postal><street></street>	</postal><email>torsten@lodderstedt.net</email></address></author>
	</postal><email>torsten@lodderstedt.net</email>
	</address></author><author initials="J." surname="Richer" fullname="Justin Riche	<author initials="J." surname="Richer" fullname="Justin Richer">
	r"><organization>Bespoke Engineering</organization><address><postal><street></st	<organization>Bespoke Engineering</organization><address><postal><street></s
	reet>	treet>
	</postal><email>ietf@justin.richer.org</email>	</postal><email>ietf@justin.richer.org</email></address></author>
	</address></author><author initials="B." surname="Campbell" fullname="Brian Camp
	bell"><organization>Ping Identity</organization><address><postal><street></stree	<author initials="B." surname="Campbell" fullname="Brian Campbell">
	t>	<organization>Ping Identity</organization><address><postal><street></street>
	</postal><email>bcampbell@pingidentity.com</email>	</postal><email>bcampbell@pingidentity.com</email></address></author>
	</address></author><date/>
	<area>Security</area>	<date year="2023" month="May" />
	<workgroup>Web Authorization Protocol</workgroup>
	<keyword>security</keyword>	<area>sec</area>
	<keyword>oauth2</keyword>	<workgroup>oauth</workgroup>

		<keyword>security</keyword>
		<keyword>oauth2</keyword>

	<abstract>	<abstract>
	<t>This document specifies a new parameter <tt>authorization_details</tt> that i s	<t>This document specifies a new parameter <tt>authorization_details</tt> that i s
	used to carry fine-grained authorization data in OAuth messages.</t>	used to carry fine-grained authorization data in OAuth messages.</t>
	</abstract>	</abstract>

	</front>	</front>

	<middle>	<middle>

	<section anchor="Introduction"><name>Introduction</name>	<section anchor="Introduction"><name>Introduction</name>

	<t>The OAuth 2.0 authorization framework <xref target="RFC6749"></xref> defines the <tt>scope</tt> parameter that allows OAuth clients to	<t>"The OAuth 2.0 Authorization Framework" <xref target="RFC6749"></xref> define s the <tt>scope</tt> parameter that allows OAuth clients to
	specify the requested scope, i.e., the limited capability, of an access token.	specify the requested scope, i.e., the limited capability, of an access token.
	This mechanism is sufficient to implement static scenarios and	This mechanism is sufficient to implement static scenarios and

	coarse-grained authorization requests, such as "give me read access to	coarse-grained authorization requests, such as "give me read access to
	the resource owner's profile" but it is not sufficient to specify	the resource owner's profile." However, it is not sufficient to specify
	fine-grained authorization requirements, such as "please let me transfer an	fine-grained authorization requirements, such as "please let me transfer an amou
	amount of 45 Euros to Merchant A"	nt of 45 Euros to Merchant A"
	or "please give me read access to directory A and write access to file X&qu	or "please give me read access to directory A and write access to file X."</t>
	ot;.</t>
	<t>This specification introduces a new parameter <tt>authorization_details</tt> that allows clients to specify their fine-grained authorization requirements usi ng the expressiveness of JSON <xref target="RFC8259"></xref> data structures.</t >	<t>This specification introduces a new parameter <tt>authorization_details</tt> that allows clients to specify their fine-grained authorization requirements usi ng the expressiveness of JSON <xref target="RFC8259"></xref> data structures.</t >

	<t>For example, an authorization request for a credit transfer (designated as &q	<t>For example, an authorization request for a credit transfer (designated as "p
	uot;payment initiation" in several open banking initiatives) can be represe	ayment initiation" in several open banking initiatives) can be represented using
	nted using a JSON object like this:</t>	a JSON object like this:</t>
	<figure><name>Example authorization request for a credit transfer.	<figure><name>Example of an Authorization Request for a Credit Transfer
	</name>	</name>

	<sourcecode type="JSON">{	<sourcecode type="json">{
	"type": "payment_initiation",	"type": "payment_initiation",
	"locations": [	"locations": [
	"https://example.com/payments"	"https://example.com/payments"
	],	],

	"instructedAmount": {	"instructedAmount": {
	"currency": "EUR",	"currency": "EUR",
	"amount": "123.50"	"amount": "123.50"
	},	},

	"creditorName": "Merchant A",	"creditorName": "Merchant A",
	"creditorAccount": {	"creditorAccount": {
	"bic":"ABCIDEFFXXX",	"bic":"ABCIDEFFXXX",
	"iban": "DE02100100109307118603"	"iban": "DE02100100109307118603"
	},	},

	"remittanceInformationUnstructured": "Ref Number Merchant&quot ;	"remittanceInformationUnstructured": "Ref Number Merchant"
	}	}
	</sourcecode>	</sourcecode>
	</figure>	</figure>

	<t>This object contains detailed information about the intended payment, such as	<t>This object contains detailed information about the intended payment, such as
	amount, currency, and creditor, that are required to inform the user and obtain	amount, currency, and creditor, that is required to inform the user and obtain
	their consent. The authorization server (AS) and the respective resource server	their consent. The authorization server (AS) and the respective resource server
	(RS) (providing the payment initiation API) will together enforce this consent.	(RS) (providing the payment initiation API) will together enforce this consent.<
	</t>	/t>
	<t>For a comprehensive discussion of the challenges arising from new use cases i	<t>For a comprehensive discussion of the challenges arising from new use cases i
	n the open banking and electronic signing spaces see <xref target="transaction-a	n the open banking and electronic signing spaces, see <xref target="Transaction-
	uthorization"></xref>.</t>	Auth"></xref>.</t>
	<t>In addition to facilitating custom authorization requests, this specification also introduces a set of common data type fields for use across different APIs. </t>	<t>In addition to facilitating custom authorization requests, this specification also introduces a set of common data type fields for use across different APIs. </t>

	<section anchor="conventions-and-terminology"><name>Conventions and Terminology< /name>	<section anchor="conventions-and-terminology"><name>Conventions and Terminology< /name>

	<t>The key words "MUST", "MUST NOT", "REQUIRED", &	<t>
	quot;SHALL", "SHALL	The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQU
	NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",	IRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL
	"NOT RECOMMENDED",	NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>
	"MAY", and "OPTIONAL" in this document are to be interpreted	RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>",
	as	"<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in this document are to
	described in BCP 14 <xref target="RFC2119"></xref> <xref target="RFC8174"></xref	be interpreted as
	> when, and only when, they	described in BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/>
	appear in all capitals, as shown here.</t>	when, and only when, they appear in all capitals, as shown here.
	<t>This specification uses the terms "access token", "refresh tok	</t>
	en",	<t>This specification uses the terms "access token", "refresh token",
	"authorization server", "resource server", "authorizati	"authorization server" (AS), "resource server" (RS), "authorization endpoint",
	on endpoint",	"authorization request", "authorization response", "token endpoint",
	"authorization request", "authorization response", "tok	"grant type", "access token request", "access token response", and
	en endpoint",	"client" defined by "<xref target="RFC6749" format="title"/>" <xref target="RFC6
	"grant type", "access token request", "access token res	749" format="default"/>.</t>
	ponse", and
	"client" defined by The OAuth 2.0 Authorization Framework <xref target
	="RFC6749"></xref>.</t>
	</section>	</section>
	</section>	</section>


	<section anchor="authz_details"><name>Request parameter "authorization_deta ils"</name>	<section anchor="authz_details"><name>Request Parameter "authorization_details"< /name>
	<t>The request parameter <tt>authorization_details</tt> contains, in JSON notati on, an array of objects. Each JSON object contains the data to specify the autho rization requirements for a certain type of resource. The type of resource or ac cess requirement is determined by the <tt>type</tt> field, which is defined as f ollows:</t>	<t>The request parameter <tt>authorization_details</tt> contains, in JSON notati on, an array of objects. Each JSON object contains the data to specify the autho rization requirements for a certain type of resource. The type of resource or ac cess requirement is determined by the <tt>type</tt> field, which is defined as f ollows:</t>


	<dl spacing="compact">	<dl spacing="normal">
	<dt><tt>type</tt>:</dt>	<dt><tt>type</tt>:</dt>

	<dd>An identifier for the authorization details type as a string. The value of t he <tt>type</tt> field determines the allowable contents of the object which con tains it and is unique for the described API in the context of the AS. This fiel d is REQUIRED.</dd>	<dd>An identifier for the authorization details type as a string. The value of t he <tt>type</tt> field determines the allowable contents of the object that cont ains it. The value is unique for the described API in the context of the AS. Thi s field is <bcp14>REQUIRED</bcp14>.</dd>
	</dl>	</dl>

	<t>An <tt>authorization_details</tt> array MAY contain multiple entries of the s	<t>An <tt>authorization_details</tt> array <bcp14>MAY</bcp14> contain multiple e
	ame <tt>type</tt>.</t>	ntries of the same <tt>type</tt>.</t>
	<t>This example shows an <tt>authorization_details</tt> of type <tt>payment_init	<t><xref target="figure2"></xref> shows an <tt>authorization_details</tt> of typ
	iation</tt> using the example data shown above:</t>	e <tt>payment_initiation</tt> using the example data shown above:</t>
	<figure><name>Example <tt>authorization_details</tt> for a credit transfer.
		<figure anchor="figure2"><name>Example of "authorization_details" for a Credit T
		ransfer
	</name>	</name>

	<sourcecode type="JSON">[	<sourcecode type="json">[
	{	{

	"type": "payment_initiation",	"type": "payment_initiation",
	"actions": [	"actions": [
	"initiate",	"initiate",
	"status",	"status",
	"cancel"	"cancel"
	],	],

	"locations": [	"locations": [
	"https://example.com/payments"	"https://example.com/payments"
	],	],

	"instructedAmount": {	"instructedAmount": {
	"currency": "EUR",	"currency": "EUR",
	"amount": "123.50"	"amount": "123.50"
	},	},

	"creditorName": "Merchant A",	"creditorName": "Merchant A",
	"creditorAccount": {	"creditorAccount": {
	"iban": "DE02100100109307118603"	"iban": "DE02100100109307118603"
	},	},

	"remittanceInformationUnstructured": "Ref Number Merchant&q uot;	"remittanceInformationUnstructured": "Ref Number Merchant"
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>

	<t>This example shows a combined request asking for access to account informatio	<t><xref target="figure3"></xref> shows a combined request asking for access to
	n and permission to initiate a payment:</t>	account information and permission to initiate a payment:</t>
	<figure><name>Example <tt>authorization_details</tt> for a combined request.
		<figure anchor="figure3"><name>Example of "authorization_details" for a Combined
		Request
	</name>	</name>

	<sourcecode type="JSON">[	<sourcecode type="json">[
	{	{

	"type": "account_information",	"type": "account_information",
	"actions": [	"actions": [
	"list_accounts",	"list_accounts",
	"read_balances",	"read_balances",
	"read_transactions"	"read_transactions"
	],	],

	"locations": [	"locations": [
	"https://example.com/accounts"	"https://example.com/accounts"
	]	]
	},	},
	{	{

	"type": "payment_initiation",	"type": "payment_initiation",
	"actions": [	"actions": [
	"initiate",	"initiate",
	"status",	"status",
	"cancel"	"cancel"
	],	],

	"locations": [	"locations": [
	"https://example.com/payments"	"https://example.com/payments"
	],	],

	"instructedAmount": {	"instructedAmount": {
	"currency": "EUR",	"currency": "EUR",
	"amount": "123.50"	"amount": "123.50"
	},	},

	"creditorName": "Merchant A",	"creditorName": "Merchant A",
	"creditorAccount": {	"creditorAccount": {
	"iban": "DE02100100109307118603"	"iban": "DE02100100109307118603"
	},	},

	"remittanceInformationUnstructured": "Ref Number Merchant&q uot;	"remittanceInformationUnstructured": "Ref Number Merchant"
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>
	<t>The JSON objects with <tt>type</tt> fields of <tt>account_information</tt> an d <tt>payment_initiation</tt> represent the different <tt>authorization_details< /tt> to be used by the AS to ask for consent.</t>	<t>The JSON objects with <tt>type</tt> fields of <tt>account_information</tt> an d <tt>payment_initiation</tt> represent the different <tt>authorization_details< /tt> to be used by the AS to ask for consent.</t>

	<t>Note: The AS will make this data subsequently available to the respective res
	ource servers (see <xref target="resource_servers"></xref>).</t>	<aside><t>Note: The AS will make this data subsequently available to the respect
		ive RSs (see <xref target="resource_servers"></xref>).</t></aside>

	<section anchor="authorization-details-types"><name>Authorization Details Types< /name>	<section anchor="authorization-details-types"><name>Authorization Details Types< /name>

	<t>Interpretation of the value of the <tt>type</tt> parameter, and the object fi
	elds that the <tt>type</tt> parameter allows, is under the control of the AS. Ho	<t>The AS controls the interpretation of the value of the <tt>type</tt> paramete
	wever, the value of the <tt>type</tt> parameter is also generally documented and	r as well as the object fields that the <tt>type</tt> parameter allows. However,
	intended to be used by developers, it is RECOMMENDED that API designers choose	the value of the <tt>type</tt> parameter is also generally documented and inten
	<tt>type</tt> values that are easily copied without ambiguity. For example, some	ded to be used by developers. It is <bcp14>RECOMMENDED</bcp14> that API designer
	glyphs have multiple Unicode code points for the same visual character, and a d	s choose <tt>type</tt> values that are easily copied without ambiguity. For exam
	eveloper could potentially type a different character than what the AS has defin	ple, some glyphs have multiple Unicode code points for the same visual character
	ed. Possible means of reducing potential confusion are limiting the value to ASC	, and a developer could potentially type a different character than what the AS
	II <xref target="RFC0020"></xref> characters, providing a machine-readable listi	has defined. Possible means of reducing potential confusion are limiting the val
	ng of data type values, or instructing developers to copy and paste directly fro	ue to ASCII <xref target="RFC0020"></xref> characters, providing a machine-reada
	m the documentation.</t>	ble listing of data type values, or instructing developers to copy and paste dir
	<t>If an application or API is expected to be deployed across different servers,	ectly from the documentation.</t>
	such as the case in an open standard, the API designer is RECOMMENDED to use a	<t>If an application or API is expected to be deployed across different servers,
	collision-resistant namespace under their control, such as a URI that the API de	such as the case in an open standard, the API designer is <bcp14>RECOMMENDED</b
	signer controls.</t>	cp14> to use a collision-resistant namespace under their control, such as a URI
		that the API designer controls.</t>
	<t>The following example shows how an implementation could utilize the namespace <tt>https://scheme.example.org/</tt> to ensure collision-resistant type values. </t>	<t>The following example shows how an implementation could utilize the namespace <tt>https://scheme.example.org/</tt> to ensure collision-resistant type values. </t>

	<figure><name>Example for <tt>authorization_details</tt> with a URL as type iden
	tifier.	<figure><name>Example of "authorization_details" with a URL as Type Identifier
	</name>	</name>

	<sourcecode type="JSON">{	<sourcecode type="json">{
	"type": "https://scheme.example.org/files",	"type": "https://scheme.example.org/files",
	"locations": [	"locations": [
	"https://example.com/files"	"https://example.com/files"
	],	],

	"permissions": [	"permissions": [
	{	{

	"path": "/myfiles/A",	"path": "/myfiles/A",
	"access": [	"access": [
	"read"	"read"
	]	]
	},	},
	{	{

	"path": "/myfiles/A/X",	"path": "/myfiles/A/X",
	"access": [	"access": [
	"read",	"read",
	"write"	"write"
	]	]
	}	}
	]	]
	}	}
	</sourcecode>	</sourcecode>
	</figure>	</figure>
	</section>	</section>


	<section anchor="common_data_fields"><name>Common data fields</name>	<section anchor="common_data_fields"><name>Common Data Fields</name>
	<t>This specification defines a set of common data fields that are designed to b	<t>This specification defines a set of common data fields that are designed to b
	e usable across different types of APIs. This specification does not require the	e usable across different types of APIs. This specification does not require the
	use of these common fields by an API definition, but instead provides them as r	use of these common fields by an API definition but, instead, provides them as
	eusable generic components for API designers to make use of. The allowable value	reusable generic components for API designers to make use of. The allowable valu
	s of all fields are determined by the API being protected, as defined by a parti	es of all fields are determined by the API being protected, as defined by a part
	cular "type" value.</t>	icular "type" value.</t>


	<dl spacing="compact">	<dl spacing="normal">
	<dt><tt>locations</tt>:</dt>	<dt><tt>locations</tt>:</dt>

	<dd>An array of strings representing the location of the resource or resource se rver. These strings are typically URIs identifying the	<dd>An array of strings representing the location of the resource or RS. These s trings are typically URIs identifying the
	location of the RS. This field can allow a client to specify a particular RS, as discussed in <xref target="security_considerations"></xref>.</dd>	location of the RS. This field can allow a client to specify a particular RS, as discussed in <xref target="security_considerations"></xref>.</dd>
	<dt><tt>actions</tt>:</dt>	<dt><tt>actions</tt>:</dt>
	<dd>An array of strings representing the kinds of actions to be taken at the res ource.</dd>	<dd>An array of strings representing the kinds of actions to be taken at the res ource.</dd>
	<dt><tt>datatypes</tt>:</dt>	<dt><tt>datatypes</tt>:</dt>
	<dd>An array of strings representing the kinds of data being requested from the resource.</dd>	<dd>An array of strings representing the kinds of data being requested from the resource.</dd>
	<dt><tt>identifier</tt>:</dt>	<dt><tt>identifier</tt>:</dt>
	<dd>A string identifier indicating a specific resource available at the API.</dd >	<dd>A string identifier indicating a specific resource available at the API.</dd >
	<dt><tt>privileges</tt>:</dt>	<dt><tt>privileges</tt>:</dt>
	<dd>An array of strings representing the types or levels of privilege being requ ested at the resource.</dd>	<dd>An array of strings representing the types or levels of privilege being requ ested at the resource.</dd>
	</dl>	</dl>
	<t>When different common data fields are used in combination, the permissions th e client requests are the product of all the values.	<t>When different common data fields are used in combination, the permissions th e client requests are the product of all the values.

	The object represents a request for all <tt>action</tt> values listed within the	The object represents a request for all <tt>actions</tt> values listed within th
	object	e object
	to be used at all <tt>locations</tt> values listed within the object for all <tt	to be used at all <tt>locations</tt> values listed within the object for all <tt
	>datatype</tt>	>datatypes</tt>
	values listed within the object. In the following example, the client is request ing <tt>read</tt> and <tt>write</tt>	values listed within the object. In the following example, the client is request ing <tt>read</tt> and <tt>write</tt>

	access to both the <tt>contacts</tt> and <tt>photos</tt> belonging to customers	access to both the <tt>contacts</tt> and <tt>photos</tt> belonging to customers
	in a <tt>customer_information</tt> API. If	in a <tt>customer_information</tt> API.
	this request is granted, the client would assume it would be able to use any com
	bination of rights	If this request is granted, the client
	defined by the API, such as reading the photos and writing the contacts.</t>	would assume it would be able to use any combination of rights
	<figure><name>Example for <tt>authorization_details</tt> with common data fields	defined by the API, such as read access to the photos and write
	.	access to the contacts.</t>
		<figure><name>Example of "authorization_details" with Common Data Fields
	</name>	</name>

	<sourcecode type="JSON">[	<sourcecode type="json">[
	{	{

	"type": "customer_information",	"type": "customer_information",
	"locations": [	"locations": [
	"https://example.com/customers"	"https://example.com/customers"
	],	],

	"actions": [	"actions": [
	"read",	"read",
	"write"	"write"
	],	],

	"datatypes": [	"datatypes": [
	"contacts",	"contacts",
	"photos"	"photos"
	]	]
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>
	<t>If the client wishes to have finer control over its access, it can send multi ple objects. In this example,	<t>If the client wishes to have finer control over its access, it can send multi ple objects. In this example,
	the client is asking for <tt>read</tt> access to the <tt>contacts</tt> and <tt>w rite</tt> access to the <tt>photos</tt> in the same API endpoint.	the client is asking for <tt>read</tt> access to the <tt>contacts</tt> and <tt>w rite</tt> access to the <tt>photos</tt> in the same API endpoint.
	If this request is granted, the client would not be able to write to the contact s.</t>	If this request is granted, the client would not be able to write to the contact s.</t>

	<figure><name>Example for <tt>authorization_details</tt> with common data fields in multiple objects.	<figure><name>Example of "authorization_details" with Common Data Fields in Mult iple Objects
	</name>	</name>

	<sourcecode type="JSON">[	<sourcecode type="json">[
	{	{

	"type": "customer_information",	"type": "customer_information",
	"locations": [	"locations": [
	"https://example.com/customers"	"https://example.com/customers"
	],	],

	"actions": [	"actions": [
	"read"	"read"
	],	],

	"datatypes": [	"datatypes": [
	"contacts"	"contacts"
	]	]
	},	},
	{	{

	"type": "customer_information",	"type": "customer_information",
	"locations": [	"locations": [
	"https://example.com/customers"	"https://example.com/customers"
	],	],

	"actions": [	"actions": [
	"write"	"write"
	],	],

	"datatypes": [	"datatypes": [
	"photos"	"photos"
	]	]
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>

	<t>An API MAY define its own extensions, subject to the <tt>type</tt> of the res pective authorization object.	<t>An API <bcp14>MAY</bcp14> define its own extensions, subject to the <tt>type< /tt> of the respective authorization object.
	It is anticipated that API designers will use a combination	It is anticipated that API designers will use a combination
	of common data fields defined in this specification as well as	of common data fields defined in this specification as well as
	fields specific to the API itself. The following non-normative	fields specific to the API itself. The following non-normative
	example shows the use of both common and API-specific fields as	example shows the use of both common and API-specific fields as
	part of two different fictitious API <tt>type</tt> values. The first	part of two different fictitious API <tt>type</tt> values. The first
	access request includes the <tt>actions</tt>, <tt>locations</tt>, and <tt>dataty pes</tt>	access request includes the <tt>actions</tt>, <tt>locations</tt>, and <tt>dataty pes</tt>
	fields specified here as well as the API-specific <tt>geolocation</tt>	fields specified here as well as the API-specific <tt>geolocation</tt>
	field, indicating access to photos taken at the given coordinates.	field, indicating access to photos taken at the given coordinates.
	The second access request includes the <tt>actions</tt> and	The second access request includes the <tt>actions</tt> and
	<tt>identifier</tt> fields specified here as well as the API-specific	<tt>identifier</tt> fields specified here as well as the API-specific
	<tt>currency</tt> fields.</t>	<tt>currency</tt> fields.</t>

	<figure><name>Example for <tt>authorization_details</tt> using common and extens
	ion data fields.	<figure><name>Example of "authorization_details" Using Common and Extension Data
	</name>	Fields</name>
	<sourcecode type="JSON">[	<sourcecode type="json">[
	{	{

	"type":"photo-api",	"type":"photo-api",
	"actions":[	"actions":[
	"read",	"read",
	"write"	"write"
	],	],

	"locations":[	"locations":[
	"https://server.example.net/",	"https://server.example.net/",
	"https://resource.local/other"	"https://resource.local/other"
	],	],

	"datatypes":[	"datatypes":[
	"metadata",	"metadata",
	"images"	"images"
	],	],

	"geolocation":[	"geolocation":[
	{	{

	"lat":-32.364,	"lat":-32.364,
	"lng":153.207	"lng":153.207
	},	},
	{	{

	"lat":-35.364,	"lat":-35.364,
	"lng":158.207	"lng":158.207
	}	}
	]	]
	},	},
	{	{

	"type":"financial-transaction",	"type":"financial-transaction",
	"actions":[	"actions":[
	"withdraw"	"withdraw"
	],	],

	"identifier":"account-14-32-32-3",	"identifier":"account-14-32-32-3",
	"currency":"USD"	"currency":"USD"
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>
	<t>If this request is approved, the resulting access token's access rights will be	<t>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 abo ve.</t>	the union of the requested types of access for each of the two APIs, just as abo ve.</t>
	</section>	</section>
	</section>	</section>

	<section anchor="authz_request"><name>Authorization Request</name>	<section anchor="authz_request"><name>Authorization Request</name>
	<t>The <tt>authorization_details</tt> authorization request parameter can be use d to specify authorization requirements in all places where the <tt>scope</tt> p arameter is used for the same purpose, examples include:</t>	<t>The <tt>authorization_details</tt> authorization request parameter can be use d to specify authorization requirements in all places where the <tt>scope</tt> p arameter is used for the same purpose, examples include:</t>


	<ul spacing="compact">	<ul spacing="normal">
	<li>Authorization requests as specified in <xref target="RFC6749"></xref>,</li>	<li>authorization requests as specified in <xref target="RFC6749"></xref></li>
	<li>Device Authorization Request as specified in <xref target="RFC8628"></xref>,	<li>device authorization requests as specified in <xref target="RFC8628"></xref>
	</li>	</li>
	<li>Backchannel Authentication Requests as defined in <xref target="OpenID.CIBA"	<li>backchannel authentication requests as defined in <xref target="OID-CIBA"></
	></xref>.</li>	xref></li>
	</ul>	</ul>

	<t>In case of authorization requests as defined in <xref target="RFC6749"></xref
	>, implementors MAY consider using pushed authorization requests <xref target="R	<t>In case of authorization requests as defined in <xref target="RFC6749"></xref
	FC9126"></xref> to improve the security, privacy, and reliability of the flow. S	>, implementers <bcp14>MAY</bcp14> consider using pushed authorization requests
	ee <xref target="security_considerations"></xref>, <xref target="privacy_conside	<xref target="RFC9126"></xref> to improve the security, privacy, and reliability
	rations"></xref>, and <xref target="large_requests"></xref> for details.</t>	of the flow. See Sections <xref target="security_considerations" format="counte
	<t>Parameter encoding is determined by the respective context. In the context of	r"></xref>, <xref target="privacy_considerations" format="counter"></xref>, and
	an authorization request according to <xref target="RFC6749"></xref>, the param	<xref target="large_requests" format="counter"></xref> for details.</t>
	eter is encoded using the <tt>application/x-www-form-urlencoded</tt> format of t	<t>Parameter encoding is determined by the respective context. In the context of
	he serialized JSON as shown in the following using the example from <xref target	an authorization request according to <xref target="RFC6749"></xref>, the param
	="authz_details"></xref> (line breaks for display purposes only):</t>	eter is encoded using the <tt>application/x-www-form-urlencoded</tt> format of t
	<figure><name>Example authorization request with authorization_details.	he serialized JSON as shown in <xref target="fig8" format="default"/>, using the
	</name>	example from <xref target="authz_details"></xref> (line breaks for display purp
	<artwork>GET /authorize?response_type=code	oses only):</t>
	&client_id=s6BhdRkqt3	<figure anchor="fig8"><name>Example of Authorization Request with "authorization
	&state=af0ifjsldkj	_details"</name>
	&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb	<sourcecode type="http-message"><![CDATA[
	&code_challenge_method=S256	GET /authorize?response_type=code
	&code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U	&client_id=s6BhdRkqt3
	&authorization_details=%5B%7B%22type%22%3A%22account%5Finfo	&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%5Finfo
	rmation%22%2C%22actions%22%3A%5B%22list%5Faccounts%22%2C%22	rmation%22%2C%22actions%22%3A%5B%22list%5Faccounts%22%2C%22
	read%5Fbalances%22%2C%22read%5Ftransactions%22%5D%2C%22loca	read%5Fbalances%22%2C%22read%5Ftransactions%22%5D%2C%22loca
	tions%22%3A%5B%22https%3A%2F%2Fexample%2Ecom%2Faccounts%22%	tions%22%3A%5B%22https%3A%2F%2Fexample%2Ecom%2Faccounts%22%
	5D%7D%2C%7B%22type%22%3A%22payment%5Finitiation%22%2C%22act	5D%7D%2C%7B%22type%22%3A%22payment%5Finitiation%22%2C%22act
	ions%22%3A%5B%22initiate%22%2C%22status%22%2C%22cancel%22%5	ions%22%3A%5B%22initiate%22%2C%22status%22%2C%22cancel%22%5
	D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample%2Ecom%2Fp	D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample%2Ecom%2Fp
	ayments%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22%	ayments%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22%
	3A%22EUR%22%2C%22amount%22%3A%22123%2E50%22%7D%2C%22credito	3A%22EUR%22%2C%22amount%22%3A%22123%2E50%22%7D%2C%22credito

	rName%22%3A%22Merchant%20A%22%2C%22creditorAccount%22%3A%7B%	rName%22%3A%22Merchant%20A%22%2C%22creditorAccount%22%3A%7B
	22iban%22%3A%22DE02100100109307118603%22%7D%2C%22remittance	%22iban%22%3A%22DE02100100109307118603%22%7D%2C%22remittanc
	InformationUnstructured%22%3A%22RefNumberMerchant%22%7D%5D HTTP/1.1	eInformationUnstructured%22%3A%22Ref%20Number%20Merchant%22
		%7D%5D HTTP/1.1
	Host: server.example.com	Host: server.example.com

	</artwork>	]]></sourcecode>
	</figure>	</figure>

	<t>Based on the data provided in the <tt>authorization_details</tt> parameter th	<t>Based on the data provided in the <tt>authorization_details</tt> parameter, t
	e AS will ask the user for consent to the requested access permissions.</t>	he AS will ask the user for consent to the requested access permissions.</t>
	<t>Note: the user may also grant a subset of the requested authorization details	<aside><t>Note: The user may also grant a subset of the requested authorization
	.</t>	details.</t></aside>
	<t>In this example, the client wants to get access to account information and in	<t>In <xref target="fig9" format="default"/>, the client wants to get access to
	itiate a payment:</t>	account information and initiate a payment:</t>
	<figure><name>URL decoded <tt>authorization_details</tt>.
	</name>	<figure anchor="fig9"><name>URL Decoded "authorization_details"</name>
	<sourcecode type="JSON">[	<sourcecode type="json">[
	{	{

	"type": "account_information",	"type": "account_information",
	"actions": [	"actions": [
	"list_accounts",	"list_accounts",
	"read_balances",	"read_balances",
	"read_transactions"	"read_transactions"
	],	],

	"locations": [	"locations": [
	"https://example.com/accounts"	"https://example.com/accounts"
	]	]
	},	},
	{	{

	"type": "payment_initiation",	"type": "payment_initiation",
	"actions": [	"actions": [
	"initiate",	"initiate",
	"status",	"status",
	"cancel"	"cancel"
	],	],

	"locations": [	"locations": [
	"https://example.com/payments"	"https://example.com/payments"
	],	],

	"instructedAmount": {	"instructedAmount": {
	"currency": "EUR",	"currency": "EUR",
	"amount": "123.50"	"amount": "123.50"
	},	},

	"creditorName": "Merchant A",	"creditorName": "Merchant A",
	"creditorAccount": {	"creditorAccount": {
	"iban": "DE02100100109307118603"	"iban": "DE02100100109307118603"
	},	},

	"remittanceInformationUnstructured": "Ref Number Merchant&q uot;	"remittanceInformationUnstructured": "Ref Number Merchant"
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>


	<section anchor="scope"><name>Relationship to "scope" parameter</name>	<section anchor="scope"><name>Relationship to the "scope" Parameter</name>
	<t><tt>authorization_details</tt> and <tt>scope</tt> can be used in the same aut horization request for carrying independent authorization requirements.</t>	<t><tt>authorization_details</tt> and <tt>scope</tt> can be used in the same aut horization request for carrying independent authorization requirements.</t>

	<t>Combined use of <tt>authorization_details</tt> and <tt>scope</tt> is supporte	<t>Combined use of <tt>authorization_details</tt> and <tt>scope</tt> is supporte
	d by this specification in part to allow existing OAuth-based applications to in	d by this specification in part to allow existing OAuth-based applications to in
	crementally migrate towards using <tt>authorization_details</tt> exclusively. It	crementally migrate towards using <tt>authorization_details</tt> exclusively. It
	is RECOMMENDED that a given API use only one form of requirement specification.	is <bcp14>RECOMMENDED</bcp14> that a given API use only one form of requirement
	</t>	specification.</t>
	<t>The AS MUST process both sets of requirements in combination with each other	<t>The AS <bcp14>MUST</bcp14> process both sets of requirements in combination w
	for the given authorization request. The details of how the AS combines these pa	ith each other for the given authorization request. The details of how the AS co
	rameters are specific to the APIs being protected and outside the scope of this	mbines these parameters are specific to the APIs being protected and outside the
	specification.</t>	scope of this specification.</t>
	<t>When gathering user consent, the AS MUST present the merged set of requiremen	<t>When gathering user consent, the AS <bcp14>MUST</bcp14> present the merged se
	ts represented by the authorization request.</t>	t of requirements represented by the authorization request.</t>
	<t>If the resource owner grants the client the requested access, the AS will iss ue tokens to the client that are associated with the respective <tt>authorizatio n_details</tt> (and scope values, if applicable).</t>	<t>If the resource owner grants the client the requested access, the AS will iss ue tokens to the client that are associated with the respective <tt>authorizatio n_details</tt> (and scope values, if applicable).</t>
	</section>	</section>


	<section anchor="relationship-to-resource-parameter"><name>Relationship to &quot	<section anchor="relationship-to-resource-parameter"><name>Relationship to the "
	;resource" parameter</name>	resource" Parameter</name>
	<t>The <tt>resource</tt> authorization request parameter as defined in <xref tar	<t>The <tt>resource</tt> authorization request parameter, as defined in <xref ta
	get="RFC8707"></xref> can be used to further determine the resources where the r	rget="RFC8707"></xref>, can be used to further determine the resources where the
	equested scope can be applied. The <tt>resource</tt> parameter does not have an	requested scope can be applied. The <tt>resource</tt> parameter does not have a
	y impact on the way the AS processes the <tt>authorization_details</tt> authoriz	ny impact on the way the AS processes the <tt>authorization_details</tt> authori
	ation request parameter.</t>	zation request parameter.</t>
	</section>	</section>
	</section>	</section>

	<section anchor="authorization-response"><name>Authorization Response</name>	<section anchor="authorization-response"><name>Authorization Response</name>
	<t>This specification does not define extensions to the authorization response.< /t>	<t>This specification does not define extensions to the authorization response.< /t>
	</section>	</section>

	<section anchor="authz_details_error"><name>Authorization Error Response</name>	<section anchor="authz_details_error"><name>Authorization Error Response</name>

	<t>The AS MUST refuse to process any unknown authorization details type or autho rization details not conforming to the respective type definition. The AS MUST a bort processing and respond with an error <tt>invalid_authorization_details</tt> to the client if any of the following are true of the objects in <tt>authorizat ion_details</tt> structure:</t>	<t>The AS <bcp14>MUST</bcp14> refuse to process any unknown authorization detail s type or authorization details not conforming to the respective type definition . The AS <bcp14>MUST</bcp14> abort processing and respond with an error <tt>inva lid_authorization_details</tt> to the client if any of the following are true of the objects in the <tt>authorization_details</tt> structure:</t>


	<ul spacing="compact">	<ul spacing="normal">
	<li>Contains an unknown authorization details type value,</li>	<li>contains an unknown authorization details type value,</li>
	<li>An object of known type but containing unknown fields,</li>	<li>is an object of known type but containing unknown fields,</li>
	<li>Contains fields of the wrong type for the authorization details type,</li>	<li>contains fields of the wrong type for the authorization details type,</li>
	<li>Contains fields with invalid values for the authorization details type, or</	<li>contains fields with invalid values for the authorization details type, or</
	li>	li>
	<li>Missing required fields for the authorization details type.</li>	<li>is missing required fields for the authorization details type.</li>
	</ul>	</ul>
	</section>	</section>

	<section anchor="token-request"><name>Token Request</name>	<section anchor="token-request"><name>Token Request</name>

	<t>The <tt>authorization_details</tt> token request parameter can be used to spe cify the authorization details a client wants the AS to assign to an access toke n. The AS checks whether the underlying grant (in case of grant types <tt>author ization_code</tt>, <tt>refresh_token</tt>, ...) or the client's policy (in case of grant type <tt>client_credential</tt>) allows the issuance of an access token with the requested authorization details. Otherwise, the AS refuses the request with the error code <tt>invalid_authorization_details</tt> (similar to <tt>inva lid_scope</tt>).</t>	<t>The <tt>authorization_details</tt> token request parameter can be used to spe cify the authorization details that a client wants the AS to assign to an access token. The AS checks whether the underlying grant (in case of grant types <tt>a uthorization_code</tt>, <tt>refresh_token</tt>, etc.) or the client's policy (in case of grant type <tt>client_credentials</tt>) allows the issuance of an acces s token with the requested authorization details. Otherwise, the AS refuses the request with the error code <tt>invalid_authorization_details</tt> (similar to < tt>invalid_scope</tt>).</t>


	<section anchor="comparing-authorization-details"><name>Comparing authorization details</name>	<section anchor="comparing-authorization-details"><name>Comparing Authorization Details</name>
	<t>Many actions in the OAuth protocol allow the AS and RS to make security decis ions based on whether the request	<t>Many actions in the OAuth protocol allow the AS and RS to make security decis ions based on whether the request

	is asking for "more" or "less" than a previous, existing req	is asking for "more" or "less" than a previous, existing request. For example, u
	uest. For example, upon refreshing a token, the client can	pon refreshing a token, the client can
	ask for a new access token with "fewer permissions" than had been prev	ask for a new access token with "fewer permissions" than had been previously aut
	iously authorized by the resource owner.	horized by the resource owner.
	The requested access token will convey the reduced permissions but the resource	The requested access token will convey the reduced permissions, but the resource
	owner's previous authorization is unchanged by such requests.	owner's previous authorization is unchanged by such requests.
	Since the semantics of the fields in the <tt>authorization_details</tt> will be implementation specific to a given API or set of APIs, there is no	Since the semantics of the fields in the <tt>authorization_details</tt> will be implementation specific to a given API or set of APIs, there is no
	standardized mechanism to compare two arbitrary authorization detail requests.	standardized mechanism to compare two arbitrary authorization detail requests.

	Authorization servers should not rely on simple object comparison in most cases, as the intersection of some fields	An AS should not rely on simple object comparison in most cases, as the intersec tion of some fields
	within a request could have side effects on the access rights granted, depending on how the API	within a request could have side effects on the access rights granted, depending on how the API
	has been designed and deployed. This is a similar effect to the scope values use d with some APIs.</t>	has been designed and deployed. This is a similar effect to the scope values use d with some APIs.</t>

	<t>When comparing a new request to an existing request, authorization servers ca n use the same	<t>When comparing a new request to an existing request, an AS can use the same
	processing techniques as used in granting the request in the first place to dete rmine if a resource	processing techniques as used in granting the request in the first place to dete rmine if a resource
	owner needs to authorize the request. The details of this comparison are depende nt on the definition	owner needs to authorize the request. The details of this comparison are depende nt on the definition
	of the <tt>type</tt> of authorization request and outside the scope of this spec ification, but common patterns	of the <tt>type</tt> of authorization request and outside the scope of this spec ification, but common patterns
	can be applied.</t>	can be applied.</t>

	<t>This shall be illustrated using our running example. The example authorizatio n request in <xref target="authz_request"></xref>, if approved by the user, resu lted in the issuance of an authorization code associated with the privileges to< /t>	<t>This shall be illustrated using our running example. The example authorizatio n request in <xref target="authz_request"></xref>, if approved by the user, resu lted in the issuance of an authorization code associated with the privileges to: </t>


	<ul spacing="compact">	<ul spacing="normal">
	<li>list accounts</li>	<li>list accounts,</li>
	<li>access the balance of one or more accounts,</li>	<li>access the balance of one or more accounts,</li>
	<li>access the transactions of one or more accounts, and</li>	<li>access the transactions of one or more accounts, and</li>

	<li>to initiate, check the status of, and cancel a payment.</li>	<li>initiate, check the status of, and cancel a payment.</li>
	</ul>	</ul>
	<t>The client could now request the AS to issue an access token assigned with th e privilege to just access a list of accounts as follows:</t>	<t>The client could now request the AS to issue an access token assigned with th e privilege to just access a list of accounts as follows:</t>

	<figure><name>Example for <tt>authorization_details</tt> reduced privileges.
		<figure><name>Example of "authorization_details" Reduced Privileges
	</name>	</name>

	<sourcecode type="JSON">[	<sourcecode type="json">[
	{	{

	"type": "account_information",	"type": "account_information",
	"actions": [	"actions": [
	"list_accounts"	"list_accounts"
	],	],

	"locations": [	"locations": [
	"https://example.com/accounts"	"https://example.com/accounts"
	]	]
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>
	<t>The example API is designed such that each field used by the <tt>account_info rmation</tt> type contains additive rights,	<t>The example API is designed such that each field used by the <tt>account_info rmation</tt> type contains additive rights,
	with each value within the <tt>actions</tt> and <tt>locations</tt> arrays specif ying a different element of access. To make a comparison in this	with each value within the <tt>actions</tt> and <tt>locations</tt> arrays specif ying a different element of access. To make a comparison in this
	instance, the AS would perform the following steps:</t>	instance, the AS would perform the following steps:</t>


	<ul spacing="compact">	<ul spacing="normal">
	<li>compare that the authorization code issued in the previous step contains an
	authorization details object of type <tt>account_information</tt></li>	<li>verify that the authorization code issued in the previous step contains an a
	<li>compare whether the approved list of actions contains <tt>list_account</tt>,	uthorization details object of type <tt>account_information</tt>,</li>
	and</li>	<li>verify whether the approved list of actions contains <tt>list_accounts</tt>,
	<li>whether the <tt>locations</tt> value includes only previously-approved locat	and</li>
	ions.</li>	<li>verify whether the <tt>locations</tt> value includes only previously approve
		d locations.</li>
	</ul>	</ul>
	<t>If all checks succeed, the AS would issue the requested access token with the reduced set of access.</t>	<t>If all checks succeed, the AS would issue the requested access token with the reduced set of access.</t>

	<t>Note that this comparison is relevant to this specific API type definition. A	<t>Note that this comparison is relevant to this specific API type definition. A
	different API type definition could have different processing rules. For exampl	different API type definition could have different processing rules. For exampl
	e, the	e, an <tt>actions</tt> value could subsume the rights associated with another <t
	value of an <tt>action</tt> could subsume the rights associated with another <tt	t>actions</tt> value. For example, if a client initially asks for
	>action</tt> value. For example, if a client initially asks for	a token with <tt>write</tt> access, this implies both read and write access to t
	a token with <tt>write</tt> access, which implies both read and write access to	his API:</t>
	this API:</t>
	<figure><name>Example for <tt>authorization_details</tt> requesting "write&	<figure><name>Example of "authorization_details" Requesting "write" Access to an
	quot; access to an API.	API</name>
	</name>	<sourcecode type="json">[
	<sourcecode type="JSON">[
	{	{

	"type": "example_api",	"type": "example_api",
	"actions": [	"actions": [
	"write"	"write"
	]	]
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>

	<t>Later that same client makes a refresh request for <tt>read</tt> access:</t>
	<figure><name>Example for <tt>authorization_details</tt> requesting "read&q	<t>Later, that same client makes a refresh request for <tt>read</tt> access:</t>
	uot; access to an API.
		<figure><name>Example of "authorization_details" Requesting "read" Access to an
		API
	</name>	</name>

	<sourcecode type="JSON">[	<sourcecode type="json">[
	{	{

	"type": "example_api",	"type": "example_api",
	"actions": [	"actions": [
	"read"	"read"
	]	]
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>

	<t>The AS would compare the <tt>type</tt> value and the <tt>action</tt> value to determine that the <tt>read</tt> access is	<t>The AS would compare the <tt>type</tt> value and the <tt>actions</tt> value t o determine that the <tt>read</tt> access is
	already covered by the <tt>write</tt> access previously granted to the client.</ t>	already covered by the <tt>write</tt> access previously granted to the client.</ t>
	<t>This same API could be designed with a possible value for <tt>privileges</tt> of <tt>admin</tt>, used in this example to	<t>This same API could be designed with a possible value for <tt>privileges</tt> of <tt>admin</tt>, used in this example to

	denote that the resulting token is allowed to perform any functions on the resou	denote that the resulting token is allowed to perform any of the functions on th
	rces. If that	e resources.
	client is then granted such <tt>admin</tt> privileges to the API:</t>
	<figure><name>Example for <tt>authorization_details</tt> requesting "admin&	If that
	quot; access to an API.	client is then granted such <tt>admin</tt> privileges to the API, the <tt>author
		ization_details</tt> would be as follows:
		</t>
		<figure><name>Example of "authorization_details" with "admin" Access to an API
	</name>	</name>

	<sourcecode type="JSON">[	<sourcecode type="json">[
	{	{

	"type": "example_api",	"type": "example_api",
	"privileges": [	"privileges": [
	"admin"	"admin"
	]	]
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>

	<t>The AS would compare the <tt>type</tt> value and find the <tt>privileges</tt>
	value subsumes any aspects of	<t>The AS would compare the <tt>type</tt> value and find that the <tt>privileges
		</tt> value subsumes any aspects of
	<tt>read</tt> or <tt>write</tt> access that had been granted to the client previ ously. Note that other	<tt>read</tt> or <tt>write</tt> access that had been granted to the client previ ously. Note that other
	API definitions can use <tt>privileges</tt> such that values do not subsume one another.</t>	API definitions can use <tt>privileges</tt> such that values do not subsume one another.</t>

	<t>The next example shows how the client can use the common data element <tt>loc	<t>The next example shows how the client can use the common data element <tt>loc
	ations</tt> (see <xref target="common_data_fields"></xref>) to request the issua	ations</tt> (see <xref target="common_data_fields"></xref>) to request the issua
	nce of an access token restricted to a certain resource server. In our running e	nce of an access token restricted to a certain RS. In our running example, the c
	xample, the client may ask for all permissions of the approved grant of type <tt	lient may ask for all permissions of the approved grant of type <tt>payment_init
	>payment_iniation</tt> applicable to the resource server residing at <tt>https:/	iation</tt> applicable to the RS residing at <tt>https://example.com/payments</t
	/example.com/payments</tt> as follows:</t>	t> as follows:</t>
	<figure><name>Example for <tt>authorization_details</tt> requesting an audience	<figure><name>Example of "authorization_details" Requesting an Audience-Restrict
	restricted access token.	ed Access Token
	</name>	</name>

	<sourcecode type="JSON">[	<sourcecode type="json">[
	{	{

	"type": "payment_initiation",	"type": "payment_initiation",
	"locations": [	"locations": [
	"https://example.com/payments"	"https://example.com/payments"
	]	]
	}	}
	]	]

	</sourcecode>	</sourcecode>
	</figure>	</figure>
	</section>	</section>
	</section>	</section>

	<section anchor="token-response"><name>Token Response</name>	<section anchor="token-response"><name>Token Response</name>

	<t>In addition to the token response parameters as defined in <xref target="RFC6 749"></xref>, the authorization server MUST also return the <tt>authorization_de tails</tt> as granted by the resource owner and assigned to the respective acces s token.</t>	<t>In addition to the token response parameters as defined in <xref target="RFC6 749"></xref>, the AS <bcp14>MUST</bcp14> also return the <tt>authorization_detai ls</tt> as granted by the resource owner and assigned to the respective access t oken.</t>
	<t>The authorization details assigned to the access token issued in a token resp onse are determined by the <tt>authorization_details</tt> parameter of the corre sponding token request. If the client does not specify the <tt>authorization_det ails</tt> token request parameters, the AS determines the resulting <tt>authoriz ation_details</tt> at its discretion.</t>	<t>The authorization details assigned to the access token issued in a token resp onse are determined by the <tt>authorization_details</tt> parameter of the corre sponding token request. If the client does not specify the <tt>authorization_det ails</tt> token request parameters, the AS determines the resulting <tt>authoriz ation_details</tt> at its discretion.</t>

	<t>The AS MAY omit values in the <tt>authorization_details</tt> to the client.</	<t>The AS <bcp14>MAY</bcp14> omit values in the <tt>authorization_details</tt> t
	t>	o the client.</t>
	<t>For our running example, this would look like this:</t>	<t>For our running example, it would look like this:</t>
	<figure><name>Example token response.
	</name>	<figure><name>Example Token Response</name>
	<sourcecode type="JSON">HTTP/1.1 200 OK
		<sourcecode type="http-message">
		HTTP/1.1 200 OK
	Content-Type: application/json	Content-Type: application/json
	Cache-Control: no-store	Cache-Control: no-store

	{	{

	"access_token": "2YotnFZFEjr1zCsicMWpAA",	"access_token": "2YotnFZFEjr1zCsicMWpAA",
	"token_type": "example",	"token_type": "example",
	"expires_in": 3600,	"expires_in": 3600,
	"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",	"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
	"authorization_details": [	"authorization_details": [
	{	{

	"type": "payment_initiation",	"type": "payment_initiation",
	"actions": [	"actions": [
	"initiate",	"initiate",
	"status",	"status",
	"cancel"	"cancel"
	],	],

	"locations": [	"locations": [
	"https://example.com/payments"	"https://example.com/payments"
	],	],

	"instructedAmount": {	"instructedAmount": {
	"currency": "EUR",	"currency": "EUR",
	"amount": "123.50"	"amount": "123.50"
	},	},

	"creditorName": "Merchant A",	"creditorName": "Merchant A",
	"creditorAccount": {	"creditorAccount": {
	"iban": "DE02100100109307118603"	"iban": "DE02100100109307118603"
	},	},

	"remittanceInformationUnstructured": "Ref Number Merchan t"	"remittanceInformationUnstructured": "Ref Number Merchant"
	}	}
	]	]
	}	}
	</sourcecode>	</sourcecode>
	</figure>	</figure>


	<section anchor="enriched-authorization-details-in-token-response"><name>Enriche	<section anchor="enriched-authorization-details-in-token-response"><name>Enriche
	d authorization details in Token Response</name>	d Authorization Details in Token Response</name>
	<t>The authorization details attached to the access token MAY differ from what t	<t>The authorization details attached to the access token <bcp14>MAY</bcp14> dif
	he client requests. In addition to the user authorizing less than what the clien	fer from what the client requests. In addition to the user authorizing less than
	t requested, there are some use cases where the authorization server enriches th	what the client requested, there are some use cases where the AS enriches the d
	e data in an authorization details object. Whether enrichment is allowed and spe	ata in an authorization details object. Whether enrichment is allowed and specif
	cifics of how it works are necessarily part of the definition of the respective	ics of how it works are necessarily part of the definition of the respective aut
	authorization details type.</t>	horization details type.</t>
	<t>As one example, a client may ask for access to account information but leave	<t>As one example, a client may ask for access to account information but leave
	the decision about the specific accounts it will be able to access to the user.	the decision about the specific accounts it will be able to access to the user.
	The user would, during the course of the authorization process, select the subse	During the course of the authorization process, the user would select the subset
	t of their accounts that they want to allow the client to access. As one design	of their accounts that they want to allow the client to access. As one design o
	option to convey the selected accounts, the authorization server could add this	ption to convey the selected accounts, the AS could add this information to the
	information to the respective authorization details object.</t>	respective authorization details object.</t>
	<t>In that example, the requested authorization detail parameter might look like	<t>In that example, the requested <tt>authorization_details</tt> parameter might
	the following. In this example the empty arrays serve as placeholders for where	look like the following. In this example, the empty arrays serve as placeholder
	data will be added during enrichment by the AS. This example is illustrative on	s for where data will be added during enrichment by the AS. This example is illu
	ly and is not intended to suggest a preference for designing the specifics of an	strative only and is not intended to suggest a preference for designing the spec
	y authorization details type this way.</t>	ifics of any authorization details type this way.</t>
	<figure><name>Example for requested <tt>authorization_details</tt>.
	</name>	<figure><name>Example of Requested "authorization_details"</name>
	<sourcecode type="JSON">"authorization_details": [	<sourcecode type="json">"authorization_details": [
	{	{

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

	"recurringIndicator":true	"recurringIndicator":true
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>

	<t>The authorization server then would expand the authorization details object a	<t>The AS then would expand the authorization details object and add the respect
	nd add the respective account identifiers.</t>	ive account identifiers.</t>
	<figure><name>Example for enriched <tt>authorization_details</tt>.
	</name>	<figure><name>Example of Enriched "authorization_details"</name>
	<sourcecode type="JSON">HTTP/1.1 200 OK	<sourcecode type="http-message">
		HTTP/1.1 200 OK
	Content-Type: application/json	Content-Type: application/json
	Cache-Control: no-store	Cache-Control: no-store

	{	{

	"access_token":"2YotnFZFEjr1zCsicMWpAA",	"access_token":"2YotnFZFEjr1zCsicMWpAA",
	"token_type":"example",	"token_type":"example",
	"expires_in":3600,	"expires_in":3600,
	"refresh_token":"tGzv3JokF0XG5Qx2TlKWIA",	"refresh_token":"tGzv3JokF0XG5Qx2TlKWIA",
	"authorization_details":[	"authorization_details":[
	{	{

	"type":"account_information",	"type":"account_information",
	"access":{	"access":{
	"accounts":[	"accounts":[
	{	{

	"iban":"DE2310010010123456789"	"iban":"DE2310010010123456789"
	},	},
	{	{

	"maskedPan":"123456xxxxxx1234"	"maskedPan":"123456xxxxxx1234"
	}	}
	],	],

	"balances":[	"balances":[
	{	{

	"iban":"DE2310010010123456789"	"iban":"DE2310010010123456789"
	}	}
	],	],

	"transactions":[	"transactions":[
	{	{

	"iban":"DE2310010010123456789"	"iban":"DE2310010010123456789"
	},	},
	{	{

	"maskedPan":"123456xxxxxx1234"	"maskedPan":"123456xxxxxx1234"
	}	}
	]	]
	},	},

	"recurringIndicator":true	"recurringIndicator":true
	}	}
	]	]
	}	}
	</sourcecode>	</sourcecode>
	</figure>	</figure>
	<t>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 spe cifies the type of access it wants but doesn't specify the location or identifie r of that access.</t>	<t>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 spe cifies the type of access it wants but doesn't specify the location or identifie r of that access.</t>

	<figure><name>Example for requested <tt>authorization_details</tt>.
	</name>	<figure><name>Example of Requested "authorization_details"</name>
	<sourcecode type="JSON">{	<sourcecode type="json">{
	"authorization_details": [	"authorization_details": [
	{	{

	"type": "medical_record",	"type": "medical_record",
	"sens": [ "HIV", "ETH", "MART" ],	"sens": [ "HIV", "ETH", "MART" ],
	"actions": [ "read" ],	"actions": [ "read" ],
	"datatypes": [ "Patient", "Observation", &qu	"datatypes": [ "Patient", "Observation", "Appointment" ]
	ot;Appointment" ]
	}	}
	]}	]}
	</sourcecode>	</sourcecode>
	</figure>	</figure>
	<t>When the user interacts with the AS, they select which of the medical records they are responsible for giving to the client. This information gets returned w ith the access token.</t>	<t>When the user interacts with the AS, they select which of the medical records they are responsible for giving to the client. This information gets returned w ith the access token.</t>

	<figure><name>Example for enriched <tt>authorization_details</tt>.
	</name>	<figure><name>Example of Enriched "authorization_details"</name>
	<sourcecode type="JSON">{	<sourcecode type="json">{
	"access_token":"2YotnFZFEjr1zCsicMWpAA",	"access_token":"2YotnFZFEjr1zCsicMWpAA",
	"token_type":"example",	"token_type":"example",
	"expires_in":3600,	"expires_in":3600,
	"refresh_token":"tGzv3JokF0XG5Qx2TlKWIA",	"refresh_token":"tGzv3JokF0XG5Qx2TlKWIA",
	"authorization_details":[	"authorization_details":[
	{	{

	"type": "medical_record",	"type": "medical_record",
	"sens": [ "HIV", "ETH", "MART" ],	"sens": [ "HIV", "ETH", "MART" ],
	"actions": [ "read" ],	"actions": [ "read" ],
	"datatypes": [ "Patient", "Observation", &qu	"datatypes": [ "Patient", "Observation", "Appointment" ],
	ot;Appointment" ],	"identifier": "patient-541235",
	"identifier": "patient-541235",	"locations": [ "https://records.example.com/" ]
	"locations": [ "https://records.example.com/" ]
	}	}
	]	]
	}	}
	</sourcecode>	</sourcecode>
	</figure>	</figure>

	<t>Note: the client needs to be aware upfront of the possibility that a certain authorization details object can be enriched. It is assumed that this property i s part of the definition of the respective authorization details type.</t>	<aside><t>Note: The client needs to be aware upfront of the possibility that a c ertain authorization details object can be enriched. It is assumed that this pro perty is part of the definition of the respective authorization details type.</t ></aside>
	</section>	</section>
	</section>	</section>

	<section anchor="token-error-response"><name>Token Error Response</name>	<section anchor="token-error-response"><name>Token Error Response</name>

	<t>The Token Error Response MUST conform to the rules given in <xref target="aut hz_details_error"></xref>.</t>	<t>The Token Error Response <bcp14>MUST</bcp14> conform to the rules given in <x ref target="authz_details_error"></xref>.</t>
	</section>	</section>

	<section anchor="resource_servers"><name>Resource Servers</name>	<section anchor="resource_servers"><name>Resource Servers</name>

	<t>In order to enable the RS to enforce the authorization details as approved in the authorization process, the AS MUST make this data available to the RS. The AS MAY add the <tt>authorization_details</tt> field to access tokens in JWT form at or to Token Introspection responses.</t>	<t>In order to enable the RS to enforce the authorization details as approved in the authorization process, the AS <bcp14>MUST</bcp14> make this data available to the RS. The AS <bcp14>MAY</bcp14> add the <tt>authorization_details</tt> fiel d to access tokens in JSON Web Token (JWT) format or to token introspection resp onses.</t>


	<section anchor="jwt_based_access_tokens"><name>JWT-based Access Tokens</name>	<section anchor="jwt_based_access_tokens"><name>JWT-Based Access Tokens</name>
	<t>If the access token is a JWT <xref target="RFC7519"></xref>, the AS is RECOMM	<t>If the access token is a JWT <xref target="RFC7519"></xref>, the AS is <bcp14
	ENDED to add the <tt>authorization_details</tt> object, filtered to the specific	>RECOMMENDED</bcp14> to add the authorization details object, filtered to the sp
	audience, as a top-level claim.</t>	ecific audience, as a top-level claim.</t>
	<t>The AS will typically also add further claims to the JWT the RS requires for	<t>The AS will typically also add further claims to the JWT that the RS requires
	request processing, e.g., user id, roles, and transaction-specific data. What cl	request processing, e.g., user ID, roles, and transaction-specific data. What c
	aims the particular RS requires is defined by the RS-specific policy with the AS	laims the particular RS requires is defined by the RS-specific policy with the A
	.</t>	S.</t>
	<t>The following shows the contents of an example JWT for the payment initiation example above:</t>	<t>The following shows the contents of an example JWT for the payment initiation example above:</t>

	<figure><name>Example for <tt>authorization_details</tt> in JWT-based access tok
	en.	<figure><name>Example of "authorization_details" in JWT-Based Access Token</name
	</name>	>
	<sourcecode type="JSON">{	<sourcecode type="json">{
	"iss": "https://as.example.com",	"iss": "https://as.example.com",
	"sub": "24400320",	"sub": "24400320",
	"aud": "a7AfcPcsl2",	"aud": "a7AfcPcsl2",
	"exp": 1311281970,	"exp": 1311281970,
	"acr": "psd2_sca",	"acr": "psd2_sca",
	"txn": "8b4729cc-32e4-4370-8cf0-5796154d1296",	"txn": "8b4729cc-32e4-4370-8cf0-5796154d1296",
	"authorization_details": [	"authorization_details": [
	{	{

	"type": "https://scheme.example.com/payment_initiation&q	"type": "https://scheme.example.com/payment_initiation",
	uot;,	"actions": [
	"actions": [	"initiate",
	"initiate",	"status",
	"status",	"cancel"
	"cancel"
	],	],

	"locations": [	"locations": [
	"https://example.com/payments"	"https://example.com/payments"
	],	],

	"instructedAmount": {	"instructedAmount": {
	"currency": "EUR",	"currency": "EUR",
	"amount": "123.50"	"amount": "123.50"
	},	},

	"creditorName": "Merchant A",	"creditorName": "Merchant A",
	"creditorAccount": {	"creditorAccount": {
	"iban": "DE02100100109307118603"	"iban": "DE02100100109307118603"
	},	},

	"remittanceInformationUnstructured": "Ref Number Merchan t"	"remittanceInformationUnstructured": "Ref Number Merchant"
	}	}
	],	],

	"debtorAccount": {	"debtorAccount": {
	"iban": "DE40100100103307118608",	"iban": "DE40100100103307118608",
	"user_role": "owner"	"user_role": "owner"
	}	}
	}	}
	</sourcecode>	</sourcecode>
	</figure>	</figure>
	<t>In this case, the AS added the following example claims to the JWT-based acce ss token:</t>	<t>In this case, the AS added the following example claims to the JWT-based acce ss token:</t>


	<ul spacing="compact">	<dl spacing="normal" newline="false">
	<li><tt>sub</tt>: conveys the user on which behalf the client is asking for paym
	ent initiation</li>	<dt><tt>sub</tt>:</dt>
	<li><tt>txn</tt>: transaction id used to trace the transaction across the servic	<dd>indicates the user for which the client is asking for payment initiation.</d
	es of provider <tt>example.com</tt></li>	d>
	<li><tt>debtorAccount</tt>: API-specific field containing the debtor account. In	<dt><tt>txn</tt>:</dt>
	the example, this account was not passed in the <tt>authorization_details</tt>	<dd>transaction id used to trace the transaction across the services of provider
	but selected by the user during the authorization process. The field <tt>user_ro	<tt>example.com</tt></dd>
	le</tt> conveys the role the user has with respect to this particular account. I	<dt><tt>debtorAccount</tt>:</dt>
	n this case, they are the owner. This data is used for access control at the pay	<dd>API-specific field containing the debtor account. In the example, this accou
	ment API (the RS).</li>	nt was not passed in the <tt>authorization_details</tt> but was selected by the
	</ul>	user during the authorization process. The field <tt>user_role</tt> conveys the
		role the user has with respect to this particular account. In this case, they ar
		e the owner. This data is used for access control at the payment API (the RS).</
		dd>
		</dl>
	</section>	</section>

	<section anchor="token_introspection"><name>Token Introspection</name>	<section anchor="token_introspection"><name>Token Introspection</name>

	<t>Token introspection <xref target="RFC7662"></xref> provides a means for an RS to query the AS to determine information about an access token. If the AS inclu des authorization detail information for the token in its response, the informat ion MUST be conveyed with <tt>authorization_details</tt> as a top-level member o f the introspection response JSON object. The <tt>authorization_details</tt> mem ber MUST contain the same structure defined in <xref target="authz_details"></xr ef>, potentially filtered and extended for the RS making the introspection reque st.</t>	<t>Token introspection <xref target="RFC7662"></xref> provides a means for an RS to query the AS to determine information about an access token. If the AS inclu des authorization detail information for the token in its response, the informat ion <bcp14>MUST</bcp14> be conveyed with <tt>authorization_details</tt> as a top -level member of the introspection response JSON object. The <tt>authorization_d etails</tt> member <bcp14>MUST</bcp14> contain the same structure defined in <xr ef target="authz_details"></xref>, potentially filtered and extended for the RS making the introspection request.</t>
	<t>Here is an example introspection response for the payment initiation example: </t>	<t>Here is an example introspection response for the payment initiation example: </t>

	<figure><name>Example for <tt>authorization_details</tt> in introspection respon
	se.	<figure><name>Example of "authorization_details" in Introspection Response</name
	</name>	>
	<sourcecode type="json">{	<sourcecode type="json">{

	"active": true,	"active": true,
	"sub": "24400320",	"sub": "24400320",
	"aud": "s6BhdRkqt3",	"aud": "s6BhdRkqt3",
	"exp": 1311281970,	"exp": 1311281970,
	"acr": "psd2_sca",	"acr": "psd2_sca",
	"txn": "8b4729cc-32e4-4370-8cf0-5796154d1296",	"txn": "8b4729cc-32e4-4370-8cf0-5796154d1296",
	"authorization_details": [	"authorization_details": [
	{	{

	"type": "https://scheme.example.com/payment_initiation&q	"type": "https://scheme.example.com/payment_initiation",
	uot;,	"actions": [
	"actions": [	"initiate",
	"initiate",	"status",
	"status",	"cancel"
	"cancel"
	],	],

	"locations": [	"locations": [
	"https://example.com/payments"	"https://example.com/payments"
	],	],

	"instructedAmount": {	"instructedAmount": {
	"currency": "EUR",	"currency": "EUR",
	"amount": "123.50"	"amount": "123.50"
	},	},

	"creditorName": "Merchant123",	"creditorName": "Merchant123",
	"creditorAccount": {	"creditorAccount": {
	"iban": "DE02100100109307118603"	"iban": "DE02100100109307118603"
	},	},

	"remittanceInformationUnstructured": "Ref Number Merchan t"	"remittanceInformationUnstructured": "Ref Number Merchant"
	}	}
	],	],

	"debtorAccount": {	"debtorAccount": {
	"iban": "DE40100100103307118608",	"iban": "DE40100100103307118608",
	"user_role": "owner"	"user_role": "owner"
	}	}
	}	}
	</sourcecode>	</sourcecode>
	</figure>	</figure>
	</section>	</section>
	</section>	</section>

	<section anchor="metadata"><name>Metadata</name>	<section anchor="metadata"><name>Metadata</name>
	<t>To advertise its support for this feature, the supported list of authorizatio n details types is included in the AS metadata response <xref target="RFC8414">< /xref> using the metadata parameter <tt>authorization_details_types_supported</t t>, which is a JSON array.</t>	<t>To advertise its support for this feature, the supported list of authorizatio n details types is included in the AS metadata response <xref target="RFC8414">< /xref> using the metadata parameter <tt>authorization_details_types_supported</t t>, which is a JSON array.</t>
	<t>This is illustrated by the following example:</t>	<t>This is illustrated by the following example:</t>

	<figure><name>Example for server metadata about the supported authorization deta
	ils.	<figure><name>Example of Server Metadata about the Supported Authorization Detai
	</name>	ls</name>
	<sourcecode type="JSON">{	<sourcecode type="json">{
	...	...

	"authorization_details_types_supported":[	"authorization_details_types_supported":[
	"payment_initiation",	"payment_initiation",
	"account_information"	"account_information"
	]	]
	}	}
	</sourcecode>	</sourcecode>
	</figure>	</figure>

	<t>Clients MAY indicate the authorization details types they will use when reque sting authorization with the client registration metadata parameter <tt>authoriz ation_details_types</tt>, which is a JSON array.</t>	<t>Clients <bcp14>MAY</bcp14> indicate the authorization details types they will use when requesting authorization with the client registration metadata paramet er <tt>authorization_details_types</tt>, which is a JSON array.</t>
	<t>This is illustrated by the following example:</t>	<t>This is illustrated by the following example:</t>

	<figure><name>Example for server metadata about authorization details.
	</name>	<figure><name>Example of Server Metadata about Authorization Details</name>
	<sourcecode type="JSON">{	<sourcecode type="json">{
	...	...

	"authorization_details_types":[	"authorization_details_types":[
	"payment_initiation"	"payment_initiation"
	]	]
	}	}
	</sourcecode>	</sourcecode>
	</figure>	</figure>

	<t>The registration of authorization details types with the AS is out of scope o f this specification.</t>	<t>The registration of authorization details types with the AS is outside the sc ope of this specification.</t>
	</section>	</section>

	<section anchor="implementation-considerations"><name>Implementation Considerati ons</name>	<section anchor="implementation-considerations"><name>Implementation Considerati ons</name>


	<section anchor="using-authorization-details-in-a-certain-deployment"><name>Usin g authorization details in a certain deployment</name>	<section anchor="using-authorization-details-in-a-certain-deployment"><name>Usin g Authorization Details in a Certain Deployment</name>
	<t>Using authorization details in a certain deployment will require the followin g steps:</t>	<t>Using authorization details in a certain deployment will require the followin g steps:</t>


	<ul spacing="compact">	<ul spacing="normal">
	<li>Define authorization details types</li>	<li>Define authorization details types.</li>
	<li>Publish authorization details types in the OAuth server metadata</li>	<li>Publish authorization details types in the OAuth server metadata.</li>
	<li>Determine how authorization details are shown to the user in the user consen	<li>Determine how authorization details are shown to the user in the user consen
	t prompt</li>	t prompt.</li>
	<li>(if needed) Enrich authorization details in the user consent process (e.g. a	<li>If needed, enrich authorization details in the user consent process (e.g., a
	dd selected accounts or set expirations)</li>	dd selected accounts or set expirations).</li>
	<li>(if needed) Determine how authorization details are reflected in access toke	<li>If needed, determine how authorization details are reflected in access token
	n content or introspection responses</li>	content or introspection responses.</li>
	<li>Determine how the resource server(s) process(s) the authorization details or	<li>Determine how the RSs process the authorization details or token data derive
	token data derived from authorization details</li>	d from authorization details.</li>
	<li>(if needed) Entitle clients to use certain authorization details types</li>	<li>If needed, entitle clients to use certain authorization details types.</li>
	</ul>	</ul>
	</section>	</section>


	<section anchor="minimal-implementation-support"><name>Minimal implementation su	<section anchor="minimal-implementation-support"><name>Minimal Implementation Su
	pport</name>	pport</name>
	<t>General authorization server implementations supporting this specification sh	<t>General AS implementations supporting this specification should provide the f
	ould provide the following basic functions:</t>	ollowing basic functions:</t>


	<ul spacing="compact">	<ul spacing="normal">
	<li>Support advertisement of supported authorization details types in OAuth serv er metadata</li>	<li>Support advertisement of supported authorization details types in OAuth serv er metadata</li>

	<li>Accept <tt>authorization_details</tt> parameter in authorization requests in conformance with this specification</li>	<li>Accept the <tt>authorization_details</tt> parameter in authorization request s in conformance with this specification</li>
	<li>Support storage of consented authorization details as part of a grant</li>	<li>Support storage of consented authorization details as part of a grant</li>

	<li>Implement default behavior for adding authorization details to access tokens and token introspection responses in order to make them available to resource s ervers (similar to scope values). This should work with any grant type, especial ly <tt>authorization_code</tt> and <tt>refresh_token</tt>.</li>	<li>Implement default behavior for adding authorization details to access tokens and token introspection responses in order to make them available to RSs (simil ar to scope values). This should work with any grant type, especially <tt>author ization_code</tt> and <tt>refresh_token</tt>.</li>
	</ul>	</ul>

	<t>Processing and presentation of authorization details will vary significantly among different authorization details types. Implementations should therefore su pport customization of the respective behavior. In particular, implementations s hould:</t>	<t>Processing and presentation of authorization details will vary significantly among different authorization details types. Implementations should therefore su pport customization of the respective behavior. In particular, implementations s hould allow deployments to:</t>


	<ul spacing="compact">	<ul spacing="normal">
	<li>allow deployments to determine presentation of the authorization details</li	<li>determine presentation of the authorization details;</li>
	>	<li>modify requested authorization details in the user consent process, e.g., ad
	<li>allow deployments to modify requested authorization details in the user cons	ding fields; and</li>
	ent process, e.g. adding fields</li>	<li>merge requested and preexisting authorization details.</li>
	<li>allow deployments to merge requested and pre-existing authorization details<
	/li>
	</ul>	</ul>

	<t>One approach to supporting such customization would be to have a mechanism al
	lowing the registration of extension modules, each of them responsible for rende	<t>One approach to supporting such customization would be to have a mechanism al
	ring the respective user consent and any transformation needed to provide the da	lowing the registration of extension modules, each of them responsible for rende
	ta needed to the resource server by way of structured access tokens or token int	ring the respective user consent and any transformation needed to provide the da
	rospection responses.</t>	ta needed to the RS by way of structured access tokens or token introspection re
		sponses.</t>
	</section>	</section>


	<section anchor="use-of-machine-readable-type-schemas"><name>Use of Machine-read able Type Schemas</name>	<section anchor="use-of-machine-readable-type-schemas"><name>Use of Machine-Read able Type Schemas</name>
	<t>Implementations might allow deployments to use machine-readable schema langua ges for defining authorization details types to facilitate creating and validati ng authorization details objects against such schemas. For example, if an author ization details <tt>type</tt> were defined using JSON Schemas <xref target="JSON .Schema"></xref>, the JSON Schema identifier could be used as <tt>type</tt> valu e in the respective authorization details objects.</t>	<t>Implementations might allow deployments to use machine-readable schema langua ges for defining authorization details types to facilitate creating and validati ng authorization details objects against such schemas. For example, if an author ization details <tt>type</tt> were defined using JSON Schemas <xref target="JSON .Schema"></xref>, the JSON Schema identifier could be used as <tt>type</tt> valu e in the respective authorization details objects.</t>

	<t>Note however that <tt>type</tt> values are identifiers understood by the AS a	<t>Note, however, that <tt>type</tt> values are identifiers understood by the AS
	nd, to the extent necessary, the client and RS. This specification makes no assu	and, to the extent necessary, the client and RS.
	mption that a <tt>type</tt> value point to a machine-readable schema format, or	This specification makes no assumption that a <tt>type</tt> value would point to
	that any party in the system (such as the client, AS, or RS) dereference or proc	a machine-readable schema format or that any party in the system (such as the c
	ess the contents of the <tt>type</tt> field in any specific way.</t>	lient, AS, or RS) would dereference or process the contents of the <tt>type</tt>
		field in any specific way.</t>
	</section>	</section>


	<section anchor="large_requests"><name>Large requests</name>	<section anchor="large_requests"><name>Large Requests</name>
	<t>Authorization request URIs containing <tt>authorization_details</tt> in a req	<t>Authorization request URIs containing <tt>authorization_details</tt> in a req
	uest parameter or a request object can become very long. Implementers should the	uest parameter or a request object can become very long. Therefore, implementers
	refore consider using the <tt>request_uri</tt> parameter as defined in <xref tar	should consider using the <tt>request_uri</tt> parameter as defined in <xref ta
	get="RFC9101"></xref> in combination with the pushed request object mechanism as	rget="RFC9101"></xref> in combination with the pushed request object mechanism a
	defined in <xref target="RFC9126"></xref> to pass <tt>authorization_details</tt	s defined in <xref target="RFC9126"></xref> to pass <tt>authorization_details</t
	> in a reliable and secure manner. Here is an example of such a pushed authoriza	t> in a reliable and secure manner. Here is an example of such a pushed authoriz
	tion request that sends the authorization request data directly to the AS via an	ation request that sends the authorization request data directly to the AS via a
	HTTPS-protected connection:</t>	n HTTPS-protected connection:</t>
	<figure><name>Example for large request including <tt>authorization_details</tt>
	.	<figure><name>Example of Large Request including "authorization_details"</name>
	</name>	<sourcecode type="http-message"><![CDATA[
	<artwork> POST /as/par HTTP/1.1	POST /as/par HTTP/1.1
	Host: as.example.com	Host: as.example.com
	Content-Type: application/x-www-form-urlencoded	Content-Type: application/x-www-form-urlencoded
	Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3	Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3


	response_type=code&	response_type=code&
	client_id=s6BhdRkqt3	client_id=s6BhdRkqt3

	&state=af0ifjsldkj	&state=af0ifjsldkj
	&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb	&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
	&code_challenge_method=S256	&code_challenge_method=S256
	&code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U	&code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U
	&authorization_details=%5B%7B%22type%22%3A%22account_information%22	&authorization_details=%5B%7B%22type%22%3A%22account_information%22
	%2C%22actions%22%3A%5B%22list_accounts%22%2C%22read_balances%22%2C%	%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	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	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	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	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	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	%2C%22amount%22%3A%22123.50%22%7D%2C%22creditorName%22%3A%22Merchan
	t123%22%2C%22creditorAccount%22%3A%7B%22iban%22%3A%22DE021001001093	t123%22%2C%22creditorAccount%22%3A%7B%22iban%22%3A%22DE021001001093
	07118603%22%7D%2C%22remittanceInformationUnstructured%22%3A%22Ref%2	07118603%22%7D%2C%22remittanceInformationUnstructured%22%3A%22Ref%2
	0Number%20Merchant%22%7D%5D	0Number%20Merchant%22%7D%5D

	</artwork>	]]></sourcecode>
	</figure>	</figure>
	</section>	</section>
	</section>	</section>

	<section anchor="security_considerations"><name>Security Considerations</name>	<section anchor="security_considerations"><name>Security Considerations</name>

	<t>The <tt>authorization_details</tt> parameter is sent through the user agent i	<t>The <tt>authorization_details</tt> parameter is sent through the user agent i
	n case of an OAuth authorization request, which makes them vulnerable to modific	n case of an OAuth authorization request, which makes them vulnerable to modific
	ations by the user. If integrity of the	ations by the user. If the integrity of the
	<tt>authorization_details</tt> is a concern, clients MUST protect <tt>authorizat	<tt>authorization_details</tt> is a concern, clients <bcp14>MUST</bcp14> protect
	ion_details</tt> against tampering and swapping. This can be achieved by signing	<tt>authorization_details</tt> against tampering and swapping. This can be achi
	the request using signed request objects as defined in <xref target="RFC9101"><	eved by signing the request using signed request objects as defined in <xref tar
	/xref> or using the <tt>request_uri</tt> authorization request parameter as defi	get="RFC9101"></xref> or using the <tt>request_uri</tt> authorization request pa
	ned in <xref target="RFC9101"></xref> in conjunction with <xref target="RFC9126"	rameter as defined in <xref target="RFC9101"></xref> in conjunction with <xref t
	></xref> to pass the URI of the request object to the authorization server.</t>	arget="RFC9126"></xref> to pass the URI of the request object to the AS.</t>
	<t>All string comparisons in an <tt>authorization_details</tt> parameter are to be done as defined by <xref target="RFC8259"></xref>. No additional transformati on or normalization is to be done in evaluating equivalence of string values.</t >	<t>All string comparisons in an <tt>authorization_details</tt> parameter are to be done as defined by <xref target="RFC8259"></xref>. No additional transformati on or normalization is to be done in evaluating equivalence of string values.</t >

	<t>The common data field <tt>locations</tt> allows a client to specify where it	<t>The common data field <tt>locations</tt> allows a client to specify where it
	intends to use a certain authorization, i.e., it is possible to unambiguously a	intends to use a certain authorization, i.e., it is possible to unambiguously a
	ssign permissions to resource servers. In situations with multiple resource serv	ssign permissions to RSs. In situations with multiple RSs, this prevents uninten
	ers, this prevents unintended client authorizations (e.g. a <tt>read</tt> scope	ded client authorizations (e.g., a <tt>read</tt> scope value potentially applica
	value potentially applicable for an email as well as a cloud service) through au	ble for an email as well as a cloud service) through audience restriction.</t>
	dience restriction.</t>	<t>The AS <bcp14>MUST</bcp14> properly sanitize and handle the data passed in th
	<t>The AS MUST properly sanitized and handle the data passed in the <tt>authoriz	e <tt>authorization_details</tt> in order to prevent injection attacks.</t>
	ation_details</tt> in order to prevent injection attacks.</t>
	<t>The Security Considerations of <xref target="RFC6749"></xref>, <xref target=" RFC7662"></xref>, and <xref target="RFC8414"></xref> also apply.</t>	<t>The Security Considerations of <xref target="RFC6749"></xref>, <xref target=" RFC7662"></xref>, and <xref target="RFC8414"></xref> also apply.</t>
	</section>	</section>

	<section anchor="privacy_considerations"><name>Privacy Considerations</name>	<section anchor="privacy_considerations"><name>Privacy Considerations</name>
	<t>It is especially important for implementers to design and use authorization d etails in a privacy-preserving manner.</t>	<t>It is especially important for implementers to design and use authorization d etails in a privacy-preserving manner.</t>

	<t>Any sensitive personal data included in <tt>authorization_details</tt> must b	<t>Any sensitive personal data included in <tt>authorization_details</tt> must b
	e prevented from leaking, e.g., through referrer headers. Implementation options	e prevented from leaking, e.g., through referrer headers. Implementation options
	include encrypted request objects as defined in <xref target="RFC9101"></xref>	include encrypted request objects as defined in <xref target="RFC9101"></xref>
	or transmission of <tt>authorization_details</tt> via end-to-end encrypted conne	or transmission of <tt>authorization_details</tt> via end-to-end encrypted conne
	ctions between client and authorization server by utilizing <xref target="RFC912	ctions between client and AS by utilizing <xref target="RFC9126"></xref> and the
	6"></xref> and the <tt>request_uri</tt> authorization request parameter as defin	<tt>request_uri</tt> authorization request parameter as defined in <xref target
	ed in <xref target="RFC9101"></xref>. The latter does not require application le	="RFC9101"></xref>. The latter does not require application-level encryption, bu
	vel encryption but it requires another message exchange between client and AS.</	t it requires another message exchange between the client and the AS.</t>
	t>	<t>Even if the request data is encrypted, an attacker could use the AS to learn
	<t>Even if the request data is encrypted, an attacker could use the authorizatio	the user's data by injecting the encrypted request data into an authorization re
	n server to learn the user's data by injecting the encrypted request data into a	quest on a device under their control and use the AS's user consent screens to s
	n authorization request on a device under their control and use the authorizatio	how the (decrypted) user data in the clear. Implementations need to consider thi
	n server's user consent screens to show the (decrypted) user data in the clear.	s attack vector and implement appropriate countermeasures, e.g., by only showing
	Implementations need to consider this attack vector and implement appropriate co	portions of the data or, if possible, determining whether the assumed user cont
	untermeasures, e.g. by only showing portions of the data or, if possible, determ	ext is still the same (after user authentication).</t>
	ining whether the assumed user context is still the same (after user authenticat	<t>The AS needs to take into consideration the privacy implications when sharing
	ion).</t>	<tt>authorization_details</tt> with the client or RSs. The AS should share this
	<t>The AS needs to take into consideration the privacy implications when sharing	data with those parties on a "need to know" basis as determined by local policy
	<tt>authorization_details</tt> with the client or resource servers. The AS shou	.</t>
	ld share this data with those parties on a "need to know" basis as det
	ermined by local policy.</t>
	</section>

	<section anchor="Acknowledgements"><name>Acknowledgements</name>
	<t>We would like to thank Daniel Fett, Sebastian Ebling, Dave Tonge, Mike Jones,
	Nat Sakimura, and Rob Otto for their valuable feedback during the preparation o
	f this specification.</t>
	<t>We would also like to thank
	Vladimir Dzhuvinov,
	Takahiko Kawasaki,
	Daniel Fett,
	Dave Tonge,
	Travis Spencer,
	Joergen Binningsboe,
	Aamund Bremer,
	Steinar Noem,
	Francis Pouatcha,
	Jacob Ideskog,
	Hannes Tschofenig,
	and Aaron Parecki for their valuable feedback to this specification.</t>
	</section>	</section>

	<section anchor="iana_considerations"><name>IANA Considerations</name>	<section anchor="iana_considerations"><name>IANA Considerations</name>

	<section anchor="oauth-parameters-registration"><name>OAuth Parameters Registrat ion</name>	<section anchor="oauth-parameters-registration"><name>OAuth Parameters Registrat ion</name>

	<t>This specification requests registration of the following parameter	<t>The following parameter has been registered
	in the "OAuth Parameters" registry <xref target="IANA.OAuth.Parameters	in the "OAuth Parameters" registry <xref target="IANA.OAuth.Parameters"></xref>
	"></xref>
	established by <xref target="RFC6749"></xref>.</t>	established by <xref target="RFC6749"></xref>.</t>


	<dl spacing="compact">	<dl spacing="normal">
	<dt>Name:</dt>	<dt>Name:</dt>
	<dd><tt>authorization_details</tt></dd>	<dd><tt>authorization_details</tt></dd>
	<dt>Parameter Usage Location:</dt>	<dt>Parameter Usage Location:</dt>
	<dd>authorization request, token request, token response</dd>	<dd>authorization request, token request, token response</dd>
	<dt>Change Controller:</dt>	<dt>Change Controller:</dt>
	<dd>IETF</dd>	<dd>IETF</dd>

	<dt>Specification Document(s):</dt>	<dt>Reference:</dt>
	<dd>[[ this document ]]</dd>	<dd>RFC 9396</dd>
	</dl>	</dl>
	</section>	</section>

	<section anchor="json-web-token-claims-registration"><name>JSON Web Token Claims Registration</name>	<section anchor="json-web-token-claims-registration"><name>JSON Web Token Claims Registration</name>

	<t>This specification requests registration of the following value in the IANA & quot;JSON Web Token Claims" registry established by <xref target="RFC7519"> </xref>.</t>	<t>The following value has been registered in the IANA "JSON Web Token Claims" r egistry established by <xref target="RFC7519"></xref>.</t>


	<dl spacing="compact">	<dl spacing="normal">
	<dt>Claim Name:</dt>	<dt>Claim Name:</dt>
	<dd><tt>authorization_details</tt></dd>	<dd><tt>authorization_details</tt></dd>
	<dt>Claim Description:</dt>	<dt>Claim Description:</dt>
	<dd>The claim <tt>authorization_details</tt> contains a JSON array of JSON objec ts representing the rights of the access token. Each JSON object contains the da ta to specify the authorization requirements for a certain type of resource.</dd >	<dd>The claim <tt>authorization_details</tt> contains a JSON array of JSON objec ts representing the rights of the access token. Each JSON object contains the da ta to specify the authorization requirements for a certain type of resource.</dd >
	<dt>Change Controller:</dt>	<dt>Change Controller:</dt>
	<dd>IETF</dd>	<dd>IETF</dd>

	<dt>Specification Document(s):</dt>	<dt>Reference:</dt>
	<dd><xref target="jwt_based_access_tokens"></xref> of [[ this document ]]</dd>	<dd><xref target="jwt_based_access_tokens"></xref> of RFC 9396</dd>
	</dl>	</dl>
	</section>	</section>

	<section anchor="oauth-token-introspection-response-registration"><name>OAuth To ken Introspection Response Registration</name>	<section anchor="oauth-token-introspection-response-registration"><name>OAuth To ken Introspection Response Registration</name>

	<t>This specification requests registration of the following value in the IANA & quot;OAuth Token Introspection Response" registry established by <xref targ et="RFC7662"></xref>.</t>	<t>The following value has been registered in the IANA "OAuth Token Introspectio n Response" registry established by <xref target="RFC7662"></xref>.</t>


	<dl spacing="compact">	<dl spacing="normal">
	<dt>Name:</dt>	<dt>Name:</dt>
	<dd><tt>authorization_details</tt></dd>	<dd><tt>authorization_details</tt></dd>
	<dt>Description:</dt>	<dt>Description:</dt>
	<dd>The member <tt>authorization_details</tt> contains a JSON array of JSON obje cts representing the rights of the access token. Each JSON object contains the d ata to specify the authorization requirements for a certain type of resource.</d d>	<dd>The member <tt>authorization_details</tt> contains a JSON array of JSON obje cts representing the rights of the access token. Each JSON object contains the d ata to specify the authorization requirements for a certain type of resource.</d d>
	<dt>Change Controller:</dt>	<dt>Change Controller:</dt>
	<dd>IETF</dd>	<dd>IETF</dd>

	<dt>Specification Document(s):</dt>	<dt>Reference:</dt>
	<dd><xref target="token_introspection"></xref> of [[ this document ]]</dd>	<dd><xref target="token_introspection"></xref> of RFC 9396</dd>
	</dl>	</dl>
	</section>	</section>

	<section anchor="oauth-authorization-server-metadata-registration"><name>OAuth A uthorization Server Metadata Registration</name>	<section anchor="oauth-authorization-server-metadata-registration"><name>OAuth A uthorization Server Metadata Registration</name>

	<t>This specification requests registration of the following values in the IANA "OAuth Authorization Server Metadata" registry of <xref target="IANA.O Auth.Parameters"></xref> established by <xref target="RFC8414"></xref>.</t>	<t>The following values have been registered in the IANA "OAuth Authorization Se rver Metadata" registry of <xref target="IANA.OAuth.Parameters"></xref> establis hed by <xref target="RFC8414"></xref>.</t>


	<dl spacing="compact">	<dl spacing="normal">
	<dt>Metadata Name:</dt>	<dt>Metadata Name:</dt>
	<dd><tt>authorization_details_types_supported</tt></dd>	<dd><tt>authorization_details_types_supported</tt></dd>
	<dt>Metadata Description:</dt>	<dt>Metadata Description:</dt>
	<dd>JSON array containing the authorization details types the AS supports</dd>	<dd>JSON array containing the authorization details types the AS supports</dd>
	<dt>Change Controller:</dt>	<dt>Change Controller:</dt>
	<dd>IETF</dd>	<dd>IETF</dd>

	<dt>Specification Document(s):</dt>	<dt>Reference:</dt>
	<dd><xref target="metadata"></xref> of [[ this document ]]</dd>	<dd><xref target="metadata"></xref> of RFC 9396</dd>
	</dl>	</dl>
	</section>	</section>

	<section anchor="oauth-dynamic-client-registration-metadata-registration"><name> OAuth Dynamic Client Registration Metadata Registration</name>	<section anchor="oauth-dynamic-client-registration-metadata-registration"><name> OAuth Dynamic Client Registration Metadata Registration</name>

	<t>This specification requests registration of the following value in the IANA & quot;OAuth Dynamic Client Registration Metadata" registry of <xref target=" IANA.OAuth.Parameters"></xref> established by <xref target="RFC7591"></xref>.</t >	<t>The following value has been registered in the IANA "OAuth Dynamic Client Reg istration Metadata" registry of <xref target="IANA.OAuth.Parameters"></xref> est ablished by <xref target="RFC7591"></xref>.</t>


	<dl spacing="compact">	<dl spacing="normal">
	<dt>Metadata Name:</dt>	<dt>Client Metadata Name:</dt>
	<dd><tt>authorization_details_types</tt></dd>	<dd><tt>authorization_details_types</tt></dd>

	<dt>Metadata Description:</dt>	<dt>Client Metadata Description:</dt>
	<dd>Indicates what authorization details types the client uses.</dd>	<dd>Indicates what authorization details types the client uses.</dd>
	<dt>Change Controller:</dt>	<dt>Change Controller:</dt>
	<dd>IETF</dd>	<dd>IETF</dd>

	<dt>Specification Document(s):</dt>	<dt>Reference:</dt>
	<dd><xref target="metadata"></xref> of [[ this document ]]</dd>	<dd><xref target="metadata"></xref> of RFC 9396</dd>
	</dl>	</dl>
	</section>	</section>

	<section anchor="oauth-extensions-error-registration"><name>OAuth Extensions Err or Registration</name>	<section anchor="oauth-extensions-error-registration"><name>OAuth Extensions Err or Registration</name>

	<t>This specification requests registration of the following value in the IANA & quot;OAuth Extensions Error" registry of <xref target="IANA.OAuth.Parameter s"></xref> established by <xref target="RFC6749"></xref>.</t>	<t>The following value has been registered in the IANA "OAuth Extensions Error R egistry" of <xref target="IANA.OAuth.Parameters"></xref> established by <xref ta rget="RFC6749"></xref>.</t>


	<dl spacing="compact">	<dl spacing="normal">
	<dt>Error name:</dt>	<dt>Name:</dt>
	<dd><tt>invalid_authorization_details</tt></dd>	<dd><tt>invalid_authorization_details</tt></dd>

	<dt>Error usage location:</dt>	<dt>Usage Location:</dt>
	<dd>token endpoint, authorization endpoint</dd>	<dd>token endpoint, authorization endpoint</dd>

	<dt>Related protocol extension:</dt>	<dt>Protocol Extension:</dt>
	<dd>OAuth 2.0 Rich Authorization Requests</dd>	<dd>OAuth 2.0 Rich Authorization Requests</dd>
	<dt>Change Controller:</dt>	<dt>Change Controller:</dt>
	<dd>IETF</dd>	<dd>IETF</dd>
	<dt>Reference:</dt>	<dt>Reference:</dt>

	<dd><xref target="authz_details_error"></xref> of [[ this document ]]</dd>	<dd><xref target="authz_details_error"></xref> of RFC 9396</dd>
	</dl>	</dl>
	</section>	</section>
	</section>	</section>

	</middle>	</middle>

	<back>	<back>

	<references><name>Normative References</name>	<references>
		<name>References</name>

		<references>
		<name>Normative References</name>
	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119. xml"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119. xml"/>
	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7519. xml"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7519. xml"/>
	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7662. xml"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7662. xml"/>
	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174. xml"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174. xml"/>
	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8414. xml"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8414. xml"/>
	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8628. xml"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8628. xml"/>
	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8707. xml"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8707. xml"/>
	</references>	</references>

	<references><name>Informative References</name>
	<reference anchor="CSC" target="https://cloudsignatureconsortium.org/wp-content/	<references>
	uploads/2019/07/CSC_API_V1_1.0.4.0.pdf">	<name>Informative References</name>

		<reference anchor="CSC" target="https://cloudsignatureconsortium.org/wp-content/
		uploads/2020/01/CSC_API_V1_1.0.4.0.pdf">
	<front>	<front>
	<title>Architectures and protocols for remote signature applications</title>	<title>Architectures and protocols for remote signature applications</title>

	<author fullname="Cloud Signature Consortium">	<author>
	<organization abbrev="CSC">Cloud Signature Consortium</organization>	<organization>Cloud Signature Consortium</organization>
	</author>	</author>

	<date year="2019" month="Jun" day="01"></date>	<date year="2019" month="June"></date>
	</front>	</front>

		<refcontent>Version 1.0.4.0</refcontent>
	</reference>	</reference>


	<reference anchor="ETSI" target="https://www.etsi.org/deliver/etsi_ts/119400_119 499/119432/01.01.01_60/ts_119432v010101p.pdf">	<reference anchor="ETSI" target="https://www.etsi.org/deliver/etsi_ts/119400_119 499/119432/01.01.01_60/ts_119432v010101p.pdf">
	<front>	<front>

	<title>ETSI TS 119 432, Electronic Signatures and Infrastructures (ESI); Pro	<title>Electronic Signatures and Infrastructures (ESI); Protocols for
	tocols for remote digital signature creation </title>	remote digital signature creation </title>
	<author fullname="ETSI">	<author>
	<organization abbrev="ETSI">ETSI</organization>	<organization>ETSI</organization>
	</author>	</author>

	<date year="2019" month="Mar" day="20"></date>	<date year="2019" month="March"/>
	</front>	</front>

		<seriesInfo name="ETSI TS" value="119 432"/>
		<refcontent>V1.1.1</refcontent>
	</reference>	</reference>


	<reference anchor="IANA.OAuth.Parameters" target="https://www.iana.org/assignmen ts/oauth-parameters">	<reference anchor="IANA.OAuth.Parameters" target="https://www.iana.org/assignmen ts/oauth-parameters">
	<front>	<front>
	<title>OAuth Parameters</title>	<title>OAuth Parameters</title>
	<author>	<author>
	<organization>IANA</organization>	<organization>IANA</organization>
	</author>	</author>

	<date></date>
	</front>	</front>
	</reference>	</reference>


	<reference anchor="JSON.Schema" target="https://json-schema.org/">	<reference anchor="JSON.Schema" target="https://json-schema.org/">
	<front>	<front>
	<title>JSON Schema</title>	<title>JSON Schema</title>

	<author fullname="json-schema.org">	<author>
	<organization abbrev="json-schema.org">json-schema.org</organization>	<organization>OpenJS Foundation</organization>
	</author>	</author>
	</front>	</front>
	</reference>	</reference>


	<reference anchor="OIDC" target="https://openid.net/specs/openid-connect-core-1_ 0.html">	<reference anchor="OIDC" target="https://openid.net/specs/openid-connect-core-1_ 0.html">
	<front>	<front>
	<title>OpenID Connect Core 1.0 incorporating errata set 1</title>	<title>OpenID Connect Core 1.0 incorporating errata set 1</title>

	<author fullname="Nat Sakimura" initials="N." surname="Sakimura">	<author initials="N." surname="Sakimura">
	<organization>NRI</organization>	<organization>NRI</organization>
	</author>	</author>

	<author fullname="John Bradley" initials="J." surname="Bradley">	<author initials="J." surname="Bradley">
	<organization>Ping Identity</organization>	<organization>Ping Identity</organization>
	</author>	</author>

	<author fullname="Mike Jones" initials="M." surname="Jones">	<author initials="M." surname="Jones">
	<organization>Microsoft</organization>	<organization>Microsoft</organization>
	</author>	</author>

	<author fullname="Breno de Medeiros" initials="B." surname="de Medeiros">	<author initials="B." surname="de Medeiros">
	<organization>Google</organization>	<organization>Google</organization>
	</author>	</author>

	<author fullname="Chuck Mortimore" initials="C." surname="Mortimore">	<author initials="C." surname="Mortimore">
	<organization>Salesforce</organization>	<organization>Salesforce</organization>
	</author>	</author>
	<date year="2014" month="Nov" day="8"></date>	<date year="2014" month="Nov" day="8"></date>
	</front>	</front>
	</reference>	</reference>

	<reference anchor="OpenID.CIBA" target="https://openid.net/specs/openid-client-i
	nitiated-backchannel-authentication-core-1_0.html">	<reference anchor="OID-CIBA" target="https://openid.net/specs/openid-client-init
		iated-backchannel-authentication-core-1_0.html">
	<front>	<front>

	<title>OpenID Connect Client Initiated Backchannel Authentication Flow - Cor	<title>OpenID Connect Client-Initiated Backchannel Authentication Flow - Cor
	e 1.0</title>	e 1.0</title>
	<author fullname="Gonzalo Fernandez Rodriguez" initials="G." surname="Fernan	<author initials="G." surname="Fernandez">
	dez">	<organization>Telefonica</organization>
	<organization abbrev="Telefonica">Telefonica I+D</organization>
	</author>	</author>

	<author fullname="Florian Walter" initials="F." surname="Walter">	<author initials="F." surname="Walter">
	<organization>Deutsche Telekom AG</organization>	<organization>Deutsche Telekom AG</organization>
	</author>	</author>

	<author fullname="Axel Nennker" initials="A." surname="Nennker">	<author initials="A." surname="Nennker">
	<organization>Deutsche Telekom AG</organization>	<organization>Deutsche Telekom AG</organization>
	</author>	</author>

	<author fullname="Dave Tonge" initials="D." surname="Tonge">	<author initials="D." surname="Tonge">
	<organization abbrev="Moneyhub">Moneyhub</organization>	<organization>Moneyhub</organization>
	</author>	</author>

	<author fullname="Brian Campbell" initials="B." surname="Campbell">	<author initials="B." surname="Campbell">
	<organization abbrev="Ping Identity">Ping Identity</organization>	<organization abbrev="Ping Identity">Ping Identity</organization>
	</author>	</author>

	<date year="2019" month="January" day="16"></date>	<date year="2021" month="September" day="1"></date>
	</front>	</front>
	</reference>	</reference>


	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.0020. xml"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.0020. xml"/>
	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6749. xml"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6749. xml"/>
	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7591. xml"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7591. xml"/>
	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8259. xml"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8259. xml"/>
	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9101. xml"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9101. xml"/>
	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9126. xml"/>	<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9126. xml"/>

	<reference anchor="transaction-authorization" target="https://medium.com/oauth-2
	/transaction-authorization-or-why-we-need-to-re-think-oauth-scopes-2326e2038948"	<reference anchor="Transaction-Auth" target="https://medium.com/oauth-2/transact
	>	ion-authorization-or-why-we-need-to-re-think-oauth-scopes-2326e2038948">
	<front>	<front>
	<title>Transaction Authorization or why we need to re-think OAuth scopes</ti tle>	<title>Transaction Authorization or why we need to re-think OAuth scopes</ti tle>
	<author fullname="Torsten Lodderstedt" initials="T." surname="Lodderstedt">	<author fullname="Torsten Lodderstedt" initials="T." surname="Lodderstedt">
	<organization>yes.com</organization>	<organization>yes.com</organization>
	</author>	</author>

	<date year="2019" month="Apr" day="20"></date>	<date year="2019" month="April" day="20"></date>
	</front>	</front>
	</reference>	</reference>


		</references>
	</references>	</references>

	<section anchor="additional-examples"><name>Additional Examples</name>	<section anchor="additional-examples"><name>Additional Examples</name>

	<section anchor="openid"><name>OpenID Connect</name>	<section anchor="openid"><name>OpenID Connect</name>

	<t>OpenID Connect <xref target="OIDC"></xref> specifies the JSON-based <tt>claim s</tt> request parameter that can be used to specify the claims a client (acting as OpenID Connect Relying Party) wishes to receive in a fine-grained and privac y-preserving way as well as assign those claims to certain delivery mechanisms, i.e. ID Token or userinfo response.</t>	<t>OpenID Connect <xref target="OIDC"></xref> specifies the JSON-based <tt>claim s</tt> request parameter that can be used to specify the claims a client (acting as an OpenID Connect Relying Party) wishes to receive in a fine-grained and pri vacy-preserving way as well as assign those claims to certain delivery mechanism s, i.e., ID Token or userinfo response.</t>
	<t>The combination of the scope value <tt>openid</tt> and the additional paramet er <tt>claims</tt> can be used beside <tt>authorization_details</tt> in the same way as every non-OIDC scope value.</t>	<t>The combination of the scope value <tt>openid</tt> and the additional paramet er <tt>claims</tt> can be used beside <tt>authorization_details</tt> in the same way as every non-OIDC scope value.</t>
	<t>Alternatively, there could be an authorization details type for OpenID Connec t. This section gives an example of what such an authorization details type coul d look like, but defining this authorization details type is outside the scope o f this specification.</t>	<t>Alternatively, there could be an authorization details type for OpenID Connec t. This section gives an example of what such an authorization details type coul d look like, but defining this authorization details type is outside the scope o f this specification.</t>
	<t>These hypothetical examples try to encapsulate all details specific to the Op enID Connect part of an authorization process into an authorization JSON object. </t>	<t>These hypothetical examples try to encapsulate all details specific to the Op enID Connect part of an authorization process into an authorization JSON object. </t>

	<t>The top-level field are based on the definitions given in <xref target="OIDC" ></xref>:</t>	<t>The top-level fields are based on the definitions given in <xref target="OIDC "></xref>:</t>


	<ul spacing="compact">	<dl spacing="normal" newline="false">
	<li><tt>claim_sets</tt>: names of predefined claim sets, replacement for respect	<dt><tt>claim_sets</tt>:</dt>
	ive scope values, such as <tt>profile</tt></li>	<dd>the names of predefined claim sets, replacement for respective scope values,
	<li><tt>max_age</tt>: Maximum Authentication Age</li>	such as <tt>profile</tt></dd>
	<li><tt>acr_values</tt>: requested Authentication Context Class Reference (ACR)	<dt><tt>max_age</tt>:</dt>
	values.</li>	<dd>Maximum Authentication Age</dd>
	<li><tt>claims</tt>: the <tt>claims</tt> JSON structure as defined in <xref targ	<dt><tt>acr_values</tt>:</dt>
	et="OIDC"></xref></li>	<dd>requested Authentication Context Class Reference (ACR) values</dd>
	</ul>	<dt><tt>claims</tt>:</dt>
		<dd>the <tt>claims</tt> JSON structure as defined in <xref target="OIDC"></xref>
		</dd>
		</dl>
	<t>This is a simple request for some claim sets.</t>	<t>This is a simple request for some claim sets.</t>

	<figure><name>Example for OpenID Connect request utilizing <tt>authorization_det
	ails</tt>.	<figure><name>Example of OpenID Connect Request Utilizing "authorization_details
	</name>	"</name>
	<sourcecode type="json">[	<sourcecode type="json">[
	{	{

	"type": "openid",	"type": "openid",
	"locations": [	"locations": [
	"https://op.example.com/userinfo"	"https://op.example.com/userinfo"
	],	],

	"claim_sets": [	"claim_sets": [
	"email",	"email",
	"profile"	"profile"
	]	]
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>

	<t>Note: <tt>locations</tt> specifies the location of the userinfo endpoint sinc	<aside><t>Note: <tt>locations</tt> specifies the location of the userinfo endpoi
	e this is the only place where an access token is used by a client (RP) in OpenI	nt since this is the only place where an access token is used by a client (Relyi
	D Connect to obtain claims.</t>	ng Party) in OpenID Connect to obtain claims.</t></aside>
	<t>A more sophisticated example is shown in the following</t>	<t>A more sophisticated example is shown in <xref target="fig26" format="default
	<figure><name>Advanced example for OpenID Connect request utilizing <tt>authoriz	"/>.</t>
	ation_details</tt>.
	</name>	<figure anchor="fig26"><name>Advanced Example of OpenID Connect Request Utilizin
		g "authorization_details"</name>
	<sourcecode type="json">[	<sourcecode type="json">[
	{	{

	"type": "openid",	"type": "openid",
	"locations": [	"locations": [
	"https://op.example.com/userinfo"	"https://op.example.com/userinfo"
	],	],

	"max_age": 86400,	"max_age": 86400,
	"acr_values": "urn:mace:incommon:iap:silver",	"acr_values": "urn:mace:incommon:iap:silver",
	"claims": {	"claims": {
	"userinfo": {	"userinfo": {
	"given_name": {	"given_name": {
	"essential": true	"essential": true
	},	},

	"nickname": null,	"nickname": null,
	"email": {	"email": {
	"essential": true	"essential": true
	},	},

	"email_verified": {	"email_verified": {
	"essential": true	"essential": true
	},	},

	"picture": null,	"picture": null,
	"http://example.com/claims/groups": null	"http://example.com/claims/groups": null
	},	},

	"id_token": {	"id_token": {
	"auth_time": {	"auth_time": {
	"essential": true	"essential": true
	}	}
	}	}
	}	}
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>
	</section>	</section>

	<section anchor="signing"><name>Remote Electronic Signing</name>	<section anchor="signing"><name>Remote Electronic Signing</name>

	<t>The following example is based on the concept laid out for remote electronic	<t>The following example is based on the concept laid out for remote electronic
	signing in ETSI TS 119 432 <xref target="ETSI"></xref> and the CSC API for remot	signing in ETSI TS 119 432 <xref target="ETSI"></xref> and the Cloud Signature C
	e signature creation <xref target="CSC"></xref>.</t>	onsortium (CSC) API for remote signature creation <xref target="CSC"></xref>.</t
	<figure><name>Example for electronic signing.	>
	</name>
		<figure><name>Example of Electronic Signing</name>
	<sourcecode type="json">[	<sourcecode type="json">[
	{	{

	"type": "sign",	"type": "sign",
	"locations": [	"locations": [
	"https://signing.example.com/signdoc"	"https://signing.example.com/signdoc"
	],	],

	"credentialID": "60916d31-932e-4820-ba82-1fcead1c9ea3"	"credentialID": "60916d31-932e-4820-ba82-1fcead1c9ea3",
	,	"documentDigests": [
	"documentDigests": [
	{	{

	"hash": "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=	"hash": "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=",
	",	"label": "Credit Contract"
	"label": "Credit Contract"
	},	},
	{	{

	"hash": "HZQzZmMAIWekfGH0/ZKW1nsdt0xg3H6bZYztgsMTLw0=	"hash": "HZQzZmMAIWekfGH0/ZKW1nsdt0xg3H6bZYztgsMTLw0=",
	",	"label": "Contract Payment Protection Insurance"
	"label": "Contract Payment Protection Insurance"
	}	}
	],	],

	"hashAlgorithmOID": "2.16.840.1.101.3.4.2.1"	"hashAlgorithmOID": "2.16.840.1.101.3.4.2.1"
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>


	<t>The top-level fields have the following meaning:</t>	<t>The top-level fields have the following meaning:</t>


	<ul spacing="compact">	<dl spacing="normal" newline="false">
	<li><tt>credentialID</tt>: identifier of the certificate to be used for signing<	<dt><tt>credentialID</tt>:</dt>
	/li>	<dd>identifier of the certificate to be used for signing</dd>
	<li><tt>documentDigests</tt>: array containing the hash of every document to be	<dt><tt>documentDigests</tt>:</dt>
	signed (<tt>hash</tt> fields). Additionally, the corresponding <tt>label</tt> fi	<dd>array containing the hash of every document to be signed (<tt>hash</tt> fiel
	eld identifies the respective document to the user, e.g. to be used in user cons	ds). Additionally, the corresponding <tt>label</tt> field identifies the respect
	ent.</li>	ive document to the user, e.g., to be used in user consent.</dd>
	<li><tt>hashAlgorithm</tt>: algorithm that was used to calculate the hash values	<dt><tt>hashAlgorithm</tt>:</dt>
	.</li>	<dd>algorithm that was used to calculate the hash values</dd>
	</ul>	</dl>
	<t>The AS is supposed to ask the user for consent for the creation of signatures
	for the documents listed in the structure. The client uses the access token iss	<t>The AS is supposed to ask the user for consent for the creation of signatures
	ued as a result of the process to call the sign doc endpoint at the respective s	for the documents listed in the structure. The client uses the access token iss
	igning service to actually create the signature. This access token is bound to t	ued as a result of the process to call the document signature API at the respect
	he client, the user id and the hashes (and signature algorithm) as consented by	ive signing service to actually create the signature. This access token is bound
	the user.</t>	to the client, the user ID and the hashes (and signature algorithm) as consente
		d by the user.</t>
	</section>	</section>

	<section anchor="tax"><name>Access to Tax Data</name>	<section anchor="tax"><name>Access to Tax Data</name>
	<t>This example is inspired by an API allowing third parties to access citizen's tax declarations and income statements, for example, to determine their creditw orthiness.</t>	<t>This example is inspired by an API allowing third parties to access citizen's tax declarations and income statements, for example, to determine their creditw orthiness.</t>

	<figure><name>Example for tax data access.
	</name>	<figure><name>Example of Tax Data Access</name>
	<sourcecode type="json">[	<sourcecode type="json">[
	{	{

	"type": "tax_data",	"type": "tax_data",
	"locations": [	"locations": [
	"https://taxservice.govehub.no.example.com"	"https://taxservice.govehub.no.example.com"
	],	],

	"actions":"read_tax_declaration",	"actions":"read_tax_declaration",
	"periods": ["2018"],	"periods": ["2018"],
	"duration_of_access": 30,	"duration_of_access": 30,
	"tax_payer_id": "23674185438934"	"tax_payer_id": "23674185438934"
	}	}
	]	]
	</sourcecode>	</sourcecode>
	</figure>	</figure>
	<t>The top-level fields have the following meaning:</t>	<t>The top-level fields have the following meaning:</t>


	<ul spacing="compact">	<dl spacing="normal" newline="false">
	<li><tt>periods</tt>: determines the periods the client wants to access</li>	<dt><tt>periods</tt>:</dt>
	<li><tt>duration_of_access</tt>: how long does the client intend to access the d	<dd>the periods the client wants to access</dd>
	ata in days</li>	<dt><tt>duration_of_access</tt>:</dt>
	<li><tt>tax_payer_id</tt>: identifier of the taxpayer (if known to the client)</	<dd>how long the clients intend to access the data in days</dd>
	li>	<dt><tt>tax_payer_id</tt>:</dt>
	</ul>	<dd>identifier of the taxpayer (if known to the client)</dd>
		</dl>
	</section>	</section>

	<section anchor="ehealth"><name>eHealth</name>	<section anchor="ehealth"><name>eHealth</name>
	<t>These two examples are inspired by requirements for APIs used in the Norwegia n eHealth system.</t>	<t>These two examples are inspired by requirements for APIs used in the Norwegia n eHealth system.</t>

	<t>In this use case, the physical therapist sits in front of their computer usin	<t>In this use case, the physical therapist sits in front of their computer usin
	g a local Electronic Health Records (EHR) system. They want to look at the elect	g a local Electronic Health Records (EHR) system. They want to look at the elect
	ronic patient records of a certain patient and they also want to fetch the patie	ronic patient records of a certain patient, and they also want to fetch the pati
	nts journal entries in another system, perhaps at another institution or a natio	ent's journal entries in another system, perhaps at another institution or a nat
	nal service. Access to this data is provided by an API.</t>	ional service. Access to this data is provided by an API.</t>
	<t>The information necessary to authorize the request at the API is only known b	<t>The information necessary to authorize the request at the API is only known b
	y the EHR system, and must be presented to the API.</t>	y the EHR system and must be presented to the API.</t>
	<t>In the first example, the authorization details object contains the identifie r of an organization. In this case, the API needs to know if the given organizat ion has the lawful basis for processing personal health information to give acce ss to sensitive data.</t>	<t>In the first example, the authorization details object contains the identifie r of an organization. In this case, the API needs to know if the given organizat ion has the lawful basis for processing personal health information to give acce ss to sensitive data.</t>

	<figure><name>eHealth Example.
	</name>	<figure><name>eHealth Example</name>
	<sourcecode type="JSON">"authorization_details": {	<sourcecode type="json"><![CDATA["authorization_details": {
	"type": "patient_record",	"type": "patient_record",
	"requesting_entity": {	"requesting_entity": {
	"type": "Practitioner",	"type": "Practitioner",
	"identifier": [	"identifier": [
	{	{

	"system": "urn:oid:2.16.578.1.12.4.1.4.4",	"system": "urn:oid:2.16.578.1.12.4.1.4.4",
	"value": "1234567"	"value": "1234567"
	}],	}],

	"practitioner_role": {	"practitioner_role": {
	"organization": {	"organization": {
	"identifier": {	"identifier": {
	"system": "urn:oid:2.16.578.1.12.4.1.2.101&qu	"system": "urn:oid:2.16.578.1.12.4.1.2.101",
	ot;,	"type": "ENH",
	"type": "ENH",	"value": "[organizational number]"
	"value": "[organizational number]"
	}	}
	}	}
	}	}
	}	}
	}	}

	</sourcecode>	]]></sourcecode>
	</figure>	</figure>
	<t>In the second example, the API requires more information to authorize the req uest. In this case, the authorization details object contains additional informa tion 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 auth orization and data minimization.</t>	<t>In the second example, the API requires more information to authorize the req uest. In this case, the authorization details object contains additional informa tion 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 auth orization and data minimization.</t>

	<figure><name>Advanced eHealth example.
	</name>	<figure><name>Advanced eHealth Example</name>
	<sourcecode type="JSON">[	<sourcecode type="json"><![CDATA[
		[
	{	{

	"type": "patient_record",	"type": "patient_record",
	"location": "https://fhir.example.com/patient",	"location": "https://fhir.example.com/patient",
	"actions": [	"actions": [
	"read"	"read"
	],	],

	"patient_identifier": [	"patient_identifier": [
	{	{

	"system": "urn:oid:2.16.578.1.12.4.1.4.1",	"system": "urn:oid:2.16.578.1.12.4.1.4.1",
	"value": "12345678901"	"value": "12345678901"
	}	}
	],	],

	"reason_for_request": "Clinical treatment",	"reason_for_request": "Clinical treatment",
	"requesting_entity": {	"requesting_entity": {
	"type": "Practitioner",	"type": "Practitioner",
	"identifier": [	"identifier": [
	{	{

	"system": "urn:oid:2.16.578.1.12.4.1.4.4",	"system": "urn:oid:2.16.578.1.12.4.1.4.4",
	"value": "1234567"	"value": "1234567"
	}	}
	],	],

	"practitioner_role": {	"practitioner_role": {
	"organization": {	"organization": {
	"identifier": [	"identifier": [
	{	{

	"system": "urn:oid:2.16.578.1.12.4.1.2.101&q	"system": "urn:oid:2.16.578.1.12.4.1.2.101",
	uot;,	"type": "ENH",
	"type": "ENH",	"value": "<organizational number>"
	"value": "<organizational number>&quot
	;
	}	}
	],	],

	"type": {	"type": {
	"coding": [	"coding": [
	{	{

	"system":	"system":
	"http://hl7.example.org/fhir/org-type",	"http://hl7.example.org/fhir/org-type",
	"code": "dept",	"code": "dept",
	"display": "Hospital Department"	"display": "Hospital Department"
	}	}
	]	]
	},	},

	"name": "Akuttmottak"	"name": "Akuttmottak"
	},	},

	"profession": {	"profession": {
	"coding": [	"coding": [
	{	{

	"system": "http://snomed.example.org/sct&quo	"system": "http://snomed.example.org/sct",
	t;,	"code": "36682004",
	"code": "36682004",	"display": "Physical therapist"
	"display": "Physical therapist"
	}	}
	]	]
	}	}
	}	}
	}	}
	}	}
	]	]

	</sourcecode>	]]></sourcecode>
	</figure>	</figure>
	<t>Description of the fields:</t>	<t>Description of the fields:</t>


	<ul spacing="compact">	<dl spacing="normal" newline="false">
	<li><tt>patient_identifier</tt>: the identifier of the patient composed of a sys	<dt><tt>patient_identifier</tt>:</dt>
	tem identifier in OID format (namespace) and the actual value within this namesp	<dd>the identifier of the patient composed of a system identifier in OID format
	ace.</li>	(namespace) and the actual value within this namespace.</dd>
	<li><tt>reason_for_request</tt>: the reason why the user wants to access a certa	<dt><tt>reason_for_request</tt>:</dt>
	in API</li>	<dd>the reason why the user wants to access a certain API.</dd>
	<li><tt>requesting_entity</tt>: specification of the requester by means of ident	<dt><tt>requesting_entity</tt>:</dt>
	ity, role and organizational context. This data is provided to facilitate author	<dd>specification of the requester by means of identity, role and organizational
	ization and for auditing purposes.</li>	context. This data is provided to facilitate authorization and for auditing pur
	</ul>	poses.</dd>
		</dl>
	<t>In this use case, the AS authenticates the requester, who is not the patient, and approves access based on policies.</t>	<t>In this use case, the AS authenticates the requester, who is not the patient, and approves access based on policies.</t>
	</section>	</section>
	</section>	</section>


	<section anchor="document-history"><name>Document History</name>	<section anchor="Acknowledgements" numbered="false">
	<t>[[ To be removed from the final specification ]]</t>	<name>Acknowledgements</name>
	<t>-22</t>	<t>We would like to thank <contact fullname="Daniel Fett"/>, <contact fullname="
		Sebastian Ebling"/>, <contact fullname="Dave Tonge"/>, <contact fullname="Mike J
	<ul spacing="compact">	ones"/>, <contact fullname="Nat Sakimura"/>, and <contact fullname="Rob Otto"/>
	<li>Add clarifying language around the geolocation example and Section 6.1 per P	for their valuable feedback during the preparation of this specification.</t>
	aul Wouters' ballot comment</li>	<t>We would also like to thank <contact fullname="Vladimir Dzhuvinov"/>,
	</ul>	<contact fullname="Takahiko Kawasaki"/>, <contact fullname="Daniel Fett"/>,
	<t>-21</t>	<contact fullname="Dave Tonge"/>, <contact fullname="Travis Spencer"/>,
		<contact fullname="Joergen Binningsboe"/>, <contact fullname="Aamund
	<ul spacing="compact">	Bremer"/>, <contact fullname="Steinar Noem"/>, <contact fullname="Francis
	<li>incorporated feedback from Robert Wilton and <u format="char-num">É</u>ric V	Pouatcha"/>, <contact fullname="Jacob Ideskog"/>, <contact fullname="Hannes
	yncke</li>	Tschofenig"/>, and <contact fullname="Aaron Parecki"/> for their valuable
	</ul>	feedback to this specification.</t>
	<t>-20</t>

	<ul spacing="compact">
	<li>incorporated feedback from Murray Kucherawy</li>
	</ul>
	<t>-19</t>

	<ul spacing="compact">
	<li>incorporated feedback from Lars Eggert</li>
	</ul>
	<t>-18</t>

	<ul spacing="compact">
	<li>IANA Considerations cleanup</li>
	</ul>
	<t>-17</t>

	<ul spacing="compact">
	<li>incorporated feedback from Genart review</li>
	</ul>
	<t>-16</t>

	<ul spacing="compact">
	<li>incorporated feedback from Sec Dir review</li>
	</ul>
	<t>-15</t>

	<ul spacing="compact">
	<li>Editorial updates from Roman Danyliw's AD review</li>
	<li>Other editorial updates</li>
	</ul>
	<t>-14</t>

	<ul spacing="compact">
	<li>Added clarification regarding authorization details types matching</li>
	<li>Removed duplicate text on use of "scope" and "resource"
	parameters alongside "authorization_details"</li>
	<li>Replaced duplicate error response description in Section 8 with reference to
	Section 5</li>
	</ul>
	<t>-13</t>

	<ul spacing="compact">
	<li>Editorial updates from Roman Danyliw's AD review</li>
	<li>Removed normative language from field definitions.</li>
	</ul>
	<t>-12</t>

	<ul spacing="compact">
	<li>Clarify introspection response.</li>
	<li>Editorial updates</li>
	</ul>
	<t>-11</t>

	<ul spacing="compact">
	<li>Updated IANA registrations adding <tt>authorization_details</tt> parameter</
	li>
	</ul>
	<t>-10</t>

	<ul spacing="compact">
	<li>Updated IANA registrations</li>
	</ul>
	<t>-09</t>

	<ul spacing="compact">
	<li>Incorporated feedback by Hannes as document shepherd</li>
	</ul>
	<t>-08</t>

	<ul spacing="compact">
	<li>formatting in authorization details type section</li>
	<li>added example for <tt>privileges</tt> common data element</li>
	</ul>
	<t>-07</t>

	<ul spacing="compact">
	<li>incorporated review feedback from WGLC</li>
	<li>fixed wording in token introspection section</li>
	<li>added privacy considerations re authorization details in token response</li>
	</ul>
	<t>-06</t>

	<ul spacing="compact">
	<li>removed use of resource indicators to filter authorization details in token
	response</li>
	</ul>
	<t>-05</t>

	<ul spacing="compact">
	<li>added <tt>authorization_details</tt> token request parameter and discussion
	on authorization details comparison</li>
	<li>added <tt>privileges</tt> field to authorization details (to align with GNAP
	)</li>
	<li>added IANA text and changed metadata parameter names</li>
	<li>added text about use of machine-readable type schemas, e.g. JSON Schema</li>
	<li>added text on how authorization details are determined for access token issu
	ed with token response</li>
	<li>added token error response and further error conditions to authorization err
	or response</li>
	</ul>
	<t>-04</t>

	<ul spacing="compact">
	<li>restructured draft for better readability</li>
	<li>simplified normative text about use of the <tt>resource</tt> parameter with
	<tt>authorization_details</tt></li>
	<li>added implementation considerations for deployments and products</li>
	<li>added type union language from GNAP</li>
	<li>added recommendation to use PAR to cope with large requests and for request
	protection</li>
	</ul>
	<t>-03</t>

	<ul spacing="compact">
	<li>Updated references to current revisions or RFC numbers</li>
	<li>Added section about enrichment of authorization details objects by the AS</l
	i>
	<li>Clarified processing of unknown authorization details parameters</li>
	<li>clarified dependencies between <tt>resource</tt> and <tt>authorization_detai
	ls</tt> parameters</li>
	</ul>
	<t>-02</t>

	<ul spacing="compact">
	<li>Clarify "type" parameter processing</li>
	</ul>
	<t>-01</t>

	<ul spacing="compact">
	<li>Minor fix-up in a few examples</li>
	</ul>
	<t>-00 (WG draft)</t>

	<ul spacing="compact">
	<li>initial WG revision</li>
	</ul>
	<t>-03</t>

	<ul spacing="compact">
	<li>Reworked examples to illustrate privacy preserving use of <tt>authorization_
	details</tt></li>
	<li>Added text on audience restriction</li>
	<li>Added description of relationship between <tt>scope</tt> and <tt>authorizati
	on_details</tt></li>
	<li>Added text on token request & response and <tt>authorization_details</tt
	></li>
	<li>Added text on how authorization details are conveyed to RSs by JWTs or token
	introspection endpoint response</li>
	<li>Added description of relationship between <tt>claims</tt> and <tt>authorizat
	ion_details</tt></li>
	<li>Added more example from different sectors</li>
	<li>Clarified string comparison to be byte-exact without collation</li>
	</ul>
	<t>-02</t>

	<ul spacing="compact">
	<li>Added Security Considerations</li>
	<li>Added Privacy Considerations</li>
	<li>Added notes on URI size and authorization details</li>
	<li>Added requirement to return the effective authorization details granted by t
	he resource owner in the token response</li>
	<li>changed <tt>authorization_details</tt> structure from object to array</li>
	<li>added Justin Richer & Brian Campbell as Co-Authors</li>
	</ul>
	<t>-00 / -01</t>

	<ul spacing="compact">
	<li>first draft</li>
	</ul>
	</section>	</section>

	</back>	</back>


	</rfc>	</rfc>

End of changes. 276 change blocks.
	1114 lines changed or deleted	967 lines changed or added
This html diff was produced by rfcdiff 1.48.