-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathdraft-dphhyland-authzen-prior-art.html
548 lines (509 loc) · 43.9 KB
/
draft-dphhyland-authzen-prior-art.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Prior Art: OIDC - OAuth 2.x - draft</title>
<style>
/* From extension vscode.github */
/*---------------------------------------------------------------------------------------------
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT License. See License.txt in the project root for license information.
*--------------------------------------------------------------------------------------------*/
.vscode-dark img[src$=\#gh-light-mode-only],
.vscode-light img[src$=\#gh-dark-mode-only] {
display: none;
}
</style>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/Microsoft/vscode/extensions/markdown-language-features/media/markdown.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/Microsoft/vscode/extensions/markdown-language-features/media/highlight.css">
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe WPC', 'Segoe UI', system-ui, 'Ubuntu', 'Droid Sans', sans-serif;
font-size: 14px;
line-height: 1.6;
}
</style>
<style>
.task-list-item {
list-style-type: none;
}
.task-list-item-checkbox {
margin-left: -20px;
vertical-align: middle;
pointer-events: none;
}
</style>
<style>
:root {
--color-note: #0969da;
--color-tip: #1a7f37;
--color-warning: #9a6700;
--color-severe: #bc4c00;
--color-caution: #d1242f;
--color-important: #8250df;
}
</style>
<style>
@media (prefers-color-scheme: dark) {
:root {
--color-note: #2f81f7;
--color-tip: #3fb950;
--color-warning: #d29922;
--color-severe: #db6d28;
--color-caution: #f85149;
--color-important: #a371f7;
}
}
</style>
<style>
.markdown-alert {
padding: 0.5rem 1rem;
margin-bottom: 16px;
color: inherit;
border-left: .25em solid #888;
}
.markdown-alert>:first-child {
margin-top: 0
}
.markdown-alert>:last-child {
margin-bottom: 0
}
.markdown-alert .markdown-alert-title {
display: flex;
font-weight: 500;
align-items: center;
line-height: 1
}
.markdown-alert .markdown-alert-title .octicon {
margin-right: 0.5rem;
display: inline-block;
overflow: visible !important;
vertical-align: text-bottom;
fill: currentColor;
}
.markdown-alert.markdown-alert-note {
border-left-color: var(--color-note);
}
.markdown-alert.markdown-alert-note .markdown-alert-title {
color: var(--color-note);
}
.markdown-alert.markdown-alert-important {
border-left-color: var(--color-important);
}
.markdown-alert.markdown-alert-important .markdown-alert-title {
color: var(--color-important);
}
.markdown-alert.markdown-alert-warning {
border-left-color: var(--color-warning);
}
.markdown-alert.markdown-alert-warning .markdown-alert-title {
color: var(--color-warning);
}
.markdown-alert.markdown-alert-tip {
border-left-color: var(--color-tip);
}
.markdown-alert.markdown-alert-tip .markdown-alert-title {
color: var(--color-tip);
}
.markdown-alert.markdown-alert-caution {
border-left-color: var(--color-caution);
}
.markdown-alert.markdown-alert-caution .markdown-alert-title {
color: var(--color-caution);
}
</style>
</head>
<body class="vscode-body vscode-light">
<p>This document provides a review of the various OAuth and OpenID specifications and how each supports the concept of authorization.</p>
<p>The purpose of this document is to provide context for the development of new standards within the AuthZen working group.</p>
<h1 id="prior-art-oidc---oauth-2x---draft">Prior Art: OIDC - OAuth 2.x - draft</h1>
<h2 id="introduction">Introduction</h2>
<p>OAuth describes a set of standards that define the protocols for the authorization of a client to access APIs. OIDC extends the authorization capability of this protocol, by providing a user context to the authorization process, enabling access control to resources based on the identity of the user. Until recently OAuth has provided few mechanisms to describe the access rights of the client; however, recent developments in open ecosystems, such as Open Banking, and evolution of standards to support strong identity using verifiable credentials have driven the development of new standards which provide a more expressive authorization process. This document provides a review of the various OAuth and OpenID standards, with a particular focus on the available mechanisms used by the client to enquire and request authorization for an end-user.</p>
<p>Conceptually and in practice there are four key activities in OAuth that perform an authorization function:</p>
<ul>
<li><strong>Client Authorization Request ( /authorize | /par | /bc-authorize )</strong>: Invoked by the user agent/client on the Authorization Server (AS) for the purposes of obtaining an access token. This performs an authorization of attributes provided in the request: if successful returns an authorization code (code flow) or access token (other); if unsuccessful returns an error.</li>
<li><strong>Token Request (/token)</strong>: The issuance of a token to the client validates the state of the grant, and any specific authorization parameters provided with the authorization request.</li>
<li><strong>Resource Server Authorization (incl /userInfo)</strong>: This is the verification the token presented to the resource server is valid and that the token has the required authorization to access the resource.</li>
<li><strong>Grant Management Enquiry (/grants)</strong>: While this api does not act as an authorization control, it does return the authorization state of the client grant.</li>
</ul>
<p><strong>User Agent/Client Authorization</strong>: Today there are a number of mechanisms in OAuth and OIDC that enable the client to communicate its Authorization requirement, which may be performed in a number of different ways beyond standard OAuth flows providing support for many different use cases (e.g. <a href="https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html">CIBA</a>, <a href="https://www.rfc-editor.org/rfc/rfc8628">Device Authorization Grant</a> etc.). Despite this diversity the mechanism to communicate the authorization requirement is standardized through the use of Scopes (including finer grained claims defined within OIDC) <a href="https://openid.net/specs/openid-connect-core-1_0.html#Claims">OIDC Section 5</a> the <code>authorization_details</code> request parameter defined within the RAR standard <a href="https://datatracker.ietf.org/doc/html/rfc9396#name-request-parameter-authoriza">RFC 9396 Section 2</a>, and on the token request through the <code>authorization_details</code> <a href="https://datatracker.ietf.org/doc/html/rfc9396#name-token-request">RFC 9396 Section 6</a> parameter. Each of these authorization request attributes enable a user agent/client to describe the authorization it requires, which may automatically authorize the request or trigger end-user Consent based interaction from one or many users that hold ownership over the resources the authorization is being requested for.</p>
<p><strong>Consent</strong>: Consent is increasingly used within digital activities to capture end user authorization to act on user data. Consent is captured in many ways and for many different reasons, and has become a key component of privacy regulations such as GDPR. Schemes such as Open Banking have also adopted the concept of consent for use of apis by third parties, which has driven the development of the FAPI standard and Rich Authorization Requests to accommodate a more secure expressive way of communicating the authorization requirement of the API client. Open Banking has also opened a degree of ambiguity in the concept of consent due to the authorization requirement over joint accounts, with the capture "consent" of multiple parties for jointly owned Bank Accounts. From an OAuth/OIDC point of view, the Consent interaction is outside of the standard and transparent to the client - this presents challenges to the client in understanding the state authorization it has been granted if multiple parties are required to perform separate consent activities. While recent standards such as the <a href="https://openid.net/specs/oauth-v2-grant-management-ID1.html">Grant Management API</a> attempt to provide the client with insight into the authorization granted, for reasons of privacy, it is not possible to provide the authorization requirement of jointly held resources.</p>
<p><strong>User Agent/Client Visibility</strong>: Conceptually OAuth and OIDC standards related to authorization are specific to the requirement of the user agent/client request for access to user data. This stems from the origins of OAuth which did not include the concept of identity of the end-user and thus the inferred access that user may have over a resource OAuth left user authorization up to implementer to address outside of the API client connection. The introduction of end-user identity through OIDC addressed authorization of end-user attributes (Claims) but did not extend to the authorization of other resources the end-user may own, or have access to. The development of the <a href="https://openid.net/specs/oauth-v2-grant-management-ID1.html">Grant Management API</a> standard provides visibility of the authorization state of a client request, and although its intent was not to provide a conduit through to the end-user resource ownership, revealing resource ownership through this API does provide opportunities for the client to enquire on authorization potential held by the end-user.</p>
<p><strong>Authorization Signalling</strong>:communicating to the client authorization state is poorly defined in OAuth/OIDC standards. Recent standards relating to (Authentication Stepup)[] (note this is an authentication stepup not AuthN) have been defined, and the <a href="https://openid.net/specs/oauth-v2-grant-management-ID1.html">Grant Management API</a> now potentially provides insight into resource ownership of the client, but otherwise generic HTTP codes are used to signal authorization outcomes to a client.</p>
<p><strong>Resource Authorization</strong>: <a href="https://www.rfc-editor.org/rfc/rfc8707.html">RFC 8707: Resource Indicators for OAuth 2.0</a> provides a mechanism for the client to signal to the authorization server the protected resources it requires access to. While the standard does not allow the inclusion of a <a href="https://www.rfc-editor.org/rfc/rfc8707#name-resource-parameter">fragment component</a> it does provide opportunity for a query component (although discouraged). The resource parameter may also be used on the <code>./token</code> endpoint. The <a href="https://datatracker.ietf.org/doc/html/rfc9396#name-common-data-fields">RFC 9396: OAuth 2.0 Rich Authorization Request</a> standard also provides opportunity communicate resource endpoint authorization requirements through the <code>locations</code> attribute.</p>
<p><strong>Authorization Metadata</strong>: There are a couple of OAuth standards which describe mechanisms for the communication of authorization metadata to the client. These include:</p>
<ul>
<li><a href="https://www.rfc-editor.org/rfc/rfc8414.html">RFC 8414: OAuth 2.0 Authorization Server Metadata</a>: Providing the client with information regarding scopes - claims - <code>authorization_details</code> type supported by the Authorization Server.</li>
<li><a href="https://www.ietf.org/archive/id/draft-ietf-oauth-resource-metadata-01.html">Oauth 2.0 Protected Resource Metadata</a> (DRAFT:Published 20 Oct 2023): Offers a mechanism for the Resource Server to advertise its capabilities to the client through a a <code>.well_known</code> endpoint. This can signal to the client the authorization servers, scopes that the resource server supports, documentation and other values required by the client to invoke.</li>
</ul>
<p><strong>OpenID for Verifiable Credentials</strong>: OID4VC builds on existing OpenID Connect standards to enable a client to perform activities related to the issuance, verification and presentation of Verifiable Credentials. These standards leverage authorization and token flows to request authorize and return credential data, of which there are authorization activities performed. These flows have not been covered in this document but will be addressed in a subsequent version.</p>
<p><strong>Other Standards</strong>: This document covers the main standards that describe the authorization process within OAuth and OIDC, and provide sufficient context for framing new Authorization Standards of the AuthZen working group; however, there are a number of standards that are worth mentioning and review by the reader - including <a href="https://www.ietf.org/archive/id/draft-vattaparambil-oauth-poa-grant-type-01.html">OAuth-PoA Grant Type</a>, <a href="https://www.rfc-editor.org/rfc/rfc8693#name-token-exchange-request-and-">RFC 8693 Token Exchange</a></p>
<h2 id="requests">Requests</h2>
<p>This section describes the various methods for requesting authorization defined by OAuth and OIDC standards.</p>
<p>NOTE: AS policy determines the behavior of an authorization request relating to unknown or scopes - authorization types that a client has not been registered for.</p>
<h3 id="standard-oauth-rfc-6749">Standard OAuth RFC 6749</h3>
<p>Request for the return of an Access Token (and optionally a Refresh Token) from the Authorization Server, which will grant a client access to a resource on behalf of a End-User.</p>
<p>The scope parameter is used to describe the access that the client is requesting.</p>
<pre><code class="language-http">
GET /authorize?
response_type=code&
client_id=s6BhdRkqt3&state=xyz&
redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&
**scope=openid%20profile&**
HTTP/1.1
</code></pre>
<p>There are a number of extension standards that provide alternative methods for requesting authorization:</p>
<ul>
<li><strong>Pushed Authorization Requests (PAR)</strong>: Requests provided via a Pushed Authorization Request (PAR) endpoint.</li>
<li><strong>JWT-Secured Authorization Request (JAR)</strong>: Requests encoded in a JWT and provided either within the request or via uri.</li>
<li><strong>Rich Authorization Requests (RAR)</strong>: Authorization Details provided as json via the <code>authorization_details</code> parameter in the authorization request. (Note: <code>authorization_details</code> may also be used on token refresh, however, this only narrows the scope of the returned token, and does not change the authorization of the client grant.)</li>
</ul>
<p>Extensions to authorization request:</p>
<ul>
<li><code>resource</code> parameter: <a href="https://www.rfc-editor.org/rfc/rfc8707">Section 2 RFC 8707 Resource Indicators for OAuth 2.0</a></li>
<li><code>authorization_details</code> parameter: <a href="https://datatracker.ietf.org/doc/html/rfc9396#name-request-parameter-authoriza">Section 2 RFC 9396 RAR</a></li>
<li><a href="https://www.rfc-editor.org/rfc/rfc9126">Pushed Authorization Requests</a>: for back channel lodgment of authorization request.</li>
</ul>
<h3 id="oidc-claims-request">OIDC Claims Request</h3>
<p><a href="https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter">https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter</a></p>
<pre><code class="language-http">GET /authorize?
response_type=code&
client_id=s6BhdRkqt3&
scope=openid%20profile%20email&
redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb&
state=xyz&
nonce=n-0S6_WzA2Mj&
claims=
{
"userinfo":
{
"given_name": {"essential": true},
"nickname": null,
"email": {"essential": true},
"email_verified": {"essential": true},
"picture": null
},
"id_token":
{
"auth_time": {"essential": true},
"acr": {"values": ["urn:mace:incommon:iap:silver"]}
}
}
HTTP/1.1
<span class="hljs-attribute">Host</span><span class="hljs-punctuation">: </span>server.example.com
</code></pre>
<h3 id="rich-authorization-requests">Rich Authorization Requests</h3>
<p>As defined in <a href="https://datatracker.ietf.org/doc/html/rfc9396#name-authorization-request">Section 3</a> for request on <code>/authorize</code> endpoint, and for a token request in <a href="https://datatracker.ietf.org/doc/html/rfc9396#name-token-response">Section 7</a>.</p>
<pre><code class="language-http">GET /authorize?response_type=code
&client_id=s6BhdRkqt3
&state=af0ifjsldkj
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&code_challenge_method=S256
&code_challenge=K2-ltc83acc4h0c9w6ESC_rEMTJ3bwc-uCHaoeK1t8U
&authorization_details=%5B%7B%22type%22%3A%22account%5Finfo
rmation%22%2C%22actions%22%3A%5B%22list%5Faccounts%22%2C%22
read%5Fbalances%22%2C%22read%5Ftransactions%22%5D%2C%22loca
tions%22%3A%5B%22https%3A%2F%2Fexample%2Ecom%2Faccounts%22%
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
D%2C%22locations%22%3A%5B%22https%3A%2F%2Fexample%2Ecom%2Fp
ayments%22%5D%2C%22instructedAmount%22%3A%7B%22currency%22%
3A%22EUR%22%2C%22amount%22%3A%22123%2E50%22%7D%2C%22credito
rName%22%3A%22Merchant%20A%22%2C%22creditorAccount%22%3A%7B
%22iban%22%3A%22DE02100100109307118603%22%7D%2C%22remittanc
eInformationUnstructured%22%3A%22Ref%20Number%20Merchant%22
%7D%5D HTTP/1.1
<span class="hljs-attribute">Host</span><span class="hljs-punctuation">: </span>server.example.com
</code></pre>
<pre><code class="language-json"><span class="hljs-punctuation">[</span>
<span class="hljs-punctuation">{</span>
<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"account_information"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"actions"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
<span class="hljs-string">"list_accounts"</span><span class="hljs-punctuation">,</span>
<span class="hljs-string">"read_balances"</span><span class="hljs-punctuation">,</span>
<span class="hljs-string">"read_transactions"</span>
<span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"locations"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
<span class="hljs-string">"https://example.com/accounts"</span>
<span class="hljs-punctuation">]</span>
<span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
<span class="hljs-punctuation">{</span>
<span class="hljs-attr">"type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"payment_initiation"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"actions"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
<span class="hljs-string">"initiate"</span><span class="hljs-punctuation">,</span>
<span class="hljs-string">"status"</span><span class="hljs-punctuation">,</span>
<span class="hljs-string">"cancel"</span>
<span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"locations"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">[</span>
<span class="hljs-string">"https://example.com/payments"</span>
<span class="hljs-punctuation">]</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"instructedAmount"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
<span class="hljs-attr">"currency"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"EUR"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"amount"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"123.50"</span>
<span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"creditorName"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Merchant A"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"creditorAccount"</span><span class="hljs-punctuation">:</span> <span class="hljs-punctuation">{</span>
<span class="hljs-attr">"iban"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"DE02100100109307118603"</span>
<span class="hljs-punctuation">}</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"remittanceInformationUnstructured"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Ref Number Merchant"</span>
<span class="hljs-punctuation">}</span>
<span class="hljs-punctuation">]</span>
</code></pre>
<p>URL Decoded <code>authorization_details</code></p>
<p><strong>NOTES</strong>:</p>
<ul>
<li>The only mandatory parameter is the type parameter. The type parameter is a string that identifies the type of the authorization details. All other parameters are optional and up to the implementer to define.</li>
<li>An Authorization Request may also be placed on the token endpoint; however, this only narrows the scope of the returned token and does not change the authorization of the client grant. When this token is presented to the resource server the narrowed token scope is enforced.</li>
</ul>
<h4 id="metadata">Metadata</h4>
<p><a href="https://datatracker.ietf.org/doc/html/rfc9396#name-metadata">https://datatracker.ietf.org/doc/html/rfc9396#name-metadata</a></p>
<p>the RAR spec provides for the advertisement of the RAR capability through the metadata endpoint.</p>
<pre><code class="language-http"> ...
"authorization_details_types_supported":[
"payment_initiation",
"account_information"
]
}
</code></pre>
<h3 id="grant-management-api">Grant Management API</h3>
<p>The Grant Management API allows the client to manage the grants that it has been issued. This includes the ability to revoke or extend a clients grant.
As part of the Authorization request <a href="https://openid.net/specs/fapi-grant-management-01.html#name-authorization-request">Section 5.2</a></p>
<p>To enquire on the status of a grant <a href="https://openid.net/specs/fapi-grant-management-01.html#name-query-status-of-a-grant">Section 6.4</a></p>
<p>To call the GM API the client requires authorization of the following scopes <a href="https://openid.net/specs/fapi-grant-management-01.html#name-api-authorization">Section 6.1</a>:</p>
<ul>
<li><code>grant_management_query</code></li>
<li><code>grant_management_revoke</code></li>
</ul>
<h4 id="update-a-grant">Update a Grant</h4>
<pre><code class="language-http">
GET /authorize?response_type=code&
client_id=s6BhdRkqt3
&grant_management_action=update
&grant_id=TSdqirmAxDa0_-DB_1bASQ
&scope=write
&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
&code_challenge_method=S256
&code_challenge=K2-ltc83acc4h... HTTP/1.1
<span class="hljs-attribute">Host</span><span class="hljs-punctuation">: </span>as.example.com
</code></pre>
<h4 id="grant-enquiry">Grant Enquiry</h4>
<pre><code class="language-http">GET /grants/TSdqirmAxDa0_-DB_1bASQ
<span class="hljs-attribute">Host</span><span class="hljs-punctuation">: </span>as.example.com
<span class="hljs-attribute">Authorization</span><span class="hljs-punctuation">: </span>Bearer 2YotnFZFEjr1zCsicMWpAA
</code></pre>
<h2 id="responses">Responses</h2>
<p>This section of the document describes the various responses that may be returned from an authorization request.</p>
<p>OAuth 2.1 requires the more secure decoupled authorization flow where the client is issued an authorization code that is then exchanged for an access token. The responses listed in this section assume this flow. (shown in flow (4) below).</p>
<pre><code class="language-http">
+--------+ +---------------+
| |--(1)- Authorization Request ->| Resource |
| | | Owner |
| |<-(2)-- Authorization Grant ---| |
| | +---------------+
| |
| | +---------------+
| |--(3)-- Authorization Grant -->| Authorization |
| Client | | Server |
| |<-(4)----- Access Token -------| |
| | +---------------+
| |
| | +---------------+
| |--(5)----- Access Token ------>| Resource |
| | | Server |
| |<-(6)--- Protected Resource ---| |
+--------+ +---------------+
</code></pre>
<h3 id="oidc---oauth2x-response">OIDC - OAuth2.x Response</h3>
<p>A standard OAuth 2.x response will return the access token and optionally the refresh token. These tokens may be opaque or as JWTs. <a href="https://datatracker.ietf.org/doc/rfc9068/">RFC9068</a></p>
<p>The authorization server MAY fully or partially ignore the scope requested by the client, based on the authorization server policy or the resource owner's instructions. If the issued access token scope is different from the one requested by the client, the authorization server MUST include the "scope" response parameter to inform the client of the actual scope granted.</p>
<pre><code class="language-http">
<span class="hljs-meta">HTTP/1.1</span> <span class="hljs-number">200</span> OK
<span class="hljs-attribute">Content-Type</span><span class="hljs-punctuation">: </span>application/json
<span class="language-json"><span class="hljs-punctuation">{</span>
<span class="hljs-attr">"access_token"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"SlAV32hkKG"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"token_type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Bearer"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"expires_in"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">3600</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"refresh_token"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"8xLOxBtZp8"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"scope"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"cheese"</span>
<span class="hljs-punctuation">}</span>
</span></code></pre>
<p><strong>OAuth 2.0 response with JWT access token</strong></p>
<pre><code class="language-http"><span class="hljs-meta">HTTP/1.1</span> <span class="hljs-number">200</span> OK
<span class="hljs-attribute">Content-Type</span><span class="hljs-punctuation">: </span>application/json
<span class="hljs-attribute">Cache-Control</span><span class="hljs-punctuation">: </span>no-store
<span class="hljs-attribute">Pragma</span><span class="hljs-punctuation">: </span>no-cache
<span class="language-json"><span class="hljs-punctuation">{</span>
<span class="hljs-attr">"access_token"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGhvcml6YXRpb24tc2VydmVyLmV4YW1wbGUuY29tLyIsInN1YiI6IjViYTU1MmQ2NyIsImF1ZCI6Imh0dHBzOi8vcnMuZXhhbXBsZS5jb20vIiwiZXhwIjoxNjM5NTI4OTEyLCJpYXQiOjE2MTgzNTQwOTAsImp0aSI6ImRiZTM5YmYzYTNiYTQyMzhhNTEzZjUxZDZlMTY5MWM0IiwiY2xpZW50X2lkIjoiczZCaGRSa3F0MyIsInNjb3BlIjoib3BlbmlkIHByb2ZpbGUgcmVhZGVtYWlsIn0.XXXXX"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"token_type"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"Bearer"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"expires_in"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">3600</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"refresh_token"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"XXXXX"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"scope"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"openid profile reademail"</span>
<span class="hljs-punctuation">}</span>
</span></code></pre>
<pre><code class="language-json"> <span class="hljs-punctuation">{</span>
<span class="hljs-attr">"iss"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"https://authorization-server.example.com/"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"sub"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"5ba552d67"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"aud"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"https://rs.example.com/"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"exp"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1639528912</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"iat"</span><span class="hljs-punctuation">:</span> <span class="hljs-number">1618354090</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"jti"</span> <span class="hljs-punctuation">:</span> <span class="hljs-string">"dbe39bf3a3ba4238a513f51d6e1691c4"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"client_id"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"s6BhdRkqt3"</span><span class="hljs-punctuation">,</span>
<span class="hljs-attr">"scope"</span><span class="hljs-punctuation">:</span> <span class="hljs-string">"openid profile reademail"</span>
<span class="hljs-punctuation">}</span>
</code></pre>
<p><strong>Note</strong>: Authorization Server Policy may be configured to ignore or reject unknown scopes and claims.</p>
<h4 id="errors">Errors</h4>
<p>Depending upon the Authorization flow used by the client, there are a range of errors that may be returned. With particular regard to the authorization request, responses such as invalid_request, invalid_grant, invalid_Scope are defined which provide some signal to the reason for the error.</p>
<p>Note: Authentication Stepup as defined in RFC 9470 provides a mechanism for the Resource Server to signal that the client requires an Authentication Stepup by the End User. This is an Authentication and not an Authorization Stepup protocol responding to exceptions relating to the <code>max_age</code> and <code>acr_values</code>.</p>
<p>OAuth <a href="https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-09.html#name-access-token">2.1</a>provides the following standard for errors relating to failed authorization request on a protected resource:</p>
<p><code>If the protected resource request included an access token and failed authentication, the resource server SHOULD include the error attribute to provide the client with the reason why the access request was declined. The parameter value is described in Section 5.2.4. In addition, the resource server MAY include the error_description attribute to provide developers a human-readable explanation that is not meant to be displayed to end-users. It also MAY include the error_uri attribute with an absolute URI identifying a human-readable web page explaining the error. The error, error_description, and error_uri attributes MUST NOT appear more than once.</code></p>
<p>OAuth 2.0: <a href="https://datatracker.ietf.org/doc/html/rfc6749#autoid-56">https://datatracker.ietf.org/doc/html/rfc6749#autoid-56</a>
OAuth 2.1: <a href="https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-09.html#name-error-codes">https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-09.html#name-error-codes</a>
RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage: <a href="https://datatracker.ietf.org/doc/html/rfc6750#autoid-10">https://datatracker.ietf.org/doc/html/rfc6750#autoid-10</a></p>
<h3 id="rich-authorization-response">Rich Authorization Response</h3>
<p><a href="https://datatracker.ietf.org/doc/html/rfc9396#name-token-response">https://datatracker.ietf.org/doc/html/rfc9396#name-token-response</a></p>
<p>This returns a token which may be enriched by the Authorization Server.</p>
<p>Policies may be configured to ignore or reject unknown <code>authorization_details</code> types.</p>
<p>If the access token is a JWT then it may contain the authorization details.</p>
<pre><code class="language-http">
<span class="hljs-meta">HTTP/1.1</span> <span class="hljs-number">200</span> OK
<span class="hljs-attribute">Content-Type</span><span class="hljs-punctuation">: </span>application/json
<span class="hljs-attribute">Cache-Control</span><span class="hljs-punctuation">: </span>no-store
<span class="language-prolog">{
<span class="hljs-string">"access_token"</span>: <span class="hljs-string">"2YotnFZFEjr1zCsicMWpAA"</span>,
<span class="hljs-string">"token_type"</span>: <span class="hljs-string">"example"</span>,
<span class="hljs-string">"expires_in"</span>: <span class="hljs-number">3600</span>,
<span class="hljs-string">"refresh_token"</span>: <span class="hljs-string">"tGzv3JOkF0XG5Qx2TlKWIA"</span>,
<span class="hljs-string">"authorization_details"</span>: [
{
<span class="hljs-string">"type"</span>: <span class="hljs-string">"payment_initiation"</span>,
<span class="hljs-string">"actions"</span>: [
<span class="hljs-string">"initiate"</span>,
<span class="hljs-string">"status"</span>,
<span class="hljs-string">"cancel"</span>
],
<span class="hljs-string">"locations"</span>: [
<span class="hljs-string">"https://example.com/payments"</span>
],
<span class="hljs-string">"instructedAmount"</span>: {
<span class="hljs-string">"currency"</span>: <span class="hljs-string">"EUR"</span>,
<span class="hljs-string">"amount"</span>: <span class="hljs-string">"123.50"</span>
},
<span class="hljs-string">"creditorName"</span>: <span class="hljs-string">"Merchant A"</span>,
<span class="hljs-string">"creditorAccount"</span>: {
<span class="hljs-string">"iban"</span>: <span class="hljs-string">"DE02100100109307118603"</span>
},
<span class="hljs-string">"remittanceInformationUnstructured"</span>: <span class="hljs-string">"Ref Number Merchant"</span>
}
]
}
</span></code></pre>
<p>RAR also allows an AS to add further claims to the JWT presented to the RS to assist in the RS processing (e.g. "debtorAccount" below)</p>
<p>Taken from : <a href="https://datatracker.ietf.org/doc/html/rfc9396#name-jwt-based-access-tokens">https://datatracker.ietf.org/doc/html/rfc9396#name-jwt-based-access-tokens</a></p>
<pre><code class="language-http">
{
"iss": "https://as.example.com",
"sub": "24400320",
"aud": "a7AfcPcsl2",
"exp": 1311281970,
"acr": "psd2_sca",
"txn": "8b4729cc-32e4-4370-8cf0-5796154d1296",
"authorization_details": [
{
"type": "https://scheme.example.com/payment_initiation",
"actions": [
"initiate",
"status",
"cancel"
],
"locations": [
"https://example.com/payments"
],
"instructedAmount": {
"currency": "EUR",
"amount": "123.50"
},
"creditorName": "Merchant A",
"creditorAccount": {
"iban": "DE02100100109307118603"
},
"remittanceInformationUnstructured": "Ref Number Merchant"
}
],
"debtorAccount": {
"iban": "DE40100100103307118608",
"user_role": "owner"
}
}
</code></pre>
<p>In this case, the AS added the following example claims to the JWT-based access token:</p>
<p><strong>sub</strong>: indicates the user for which the client is asking for payment initiation.
<strong>txn</strong>: transaction id used to trace the transaction across the services of provider <a href="http://example.com">example.com</a>
<strong>debtorAccount</strong>: API-specific field containing the debtor account. In the example, this account was not passed in the <code>authorization_details</code> but was selected by the user during the authorization process. The field user_role conveys the role the user has with respect to this particular account. In this case, they are the owner. This data is used for access control at the payment API (the RS).</p>
<h4 id="errors-1">Errors</h4>
<p>The AuthZ response is the same as an OAuth 2.x response - however the authorization code may be a JWT that contains the authorization details.</p>
<p>The standard is thin on how to deal with errors in the authorization request - it is mostly focused on errors related to the data type (i.e. does not suggest range values) and does not provide any opportunity to communicate the reason for the error. (i.e. is it an authorization issue or a data issue).</p>
<p>Authorization Errors defined by the RAR spec are focused on type excepts - no standards are defined for Authorization based exceptions</p>
<p><a href="https://datatracker.ietf.org/doc/html/rfc9396#name-authorization-error-response">https://datatracker.ietf.org/doc/html/rfc9396#name-authorization-error-response</a></p>
<h3 id="grant-management-api-response">Grant Management API Response</h3>
<p>The token response of an AS supporting the Grant Management API will include the grant_id that enables the client to manage and enquire on the grant.</p>
<p>The /grants API returns a JSON-formatted response that contains the grant_id and the grant status. The provides the client insight into grant is holds, enabling monitoring-discovery of any latent grants that may be provided to the client through the consent process - e.g. multi-party consent flows.</p>
<p>Note this response is not an access token.</p>
<pre><code class="language-http"><span class="hljs-meta">HTTP/1.1</span> <span class="hljs-number">200</span> OK
<span class="hljs-attribute">Cache-Control</span><span class="hljs-punctuation">: </span>no-cache, no-store
<span class="hljs-attribute">Content-Type</span><span class="hljs-punctuation">: </span>application/json
<span class="language-prolog">{
<span class="hljs-string">"scopes"</span>:[
{
<span class="hljs-string">"scope"</span>:<span class="hljs-string">"contacts read write"</span>,
<span class="hljs-string">"resources"</span>:[
<span class="hljs-string">"https://rs.example.com/api"</span>
]
},
{
<span class="hljs-string">"scope"</span>:<span class="hljs-string">"openid"</span>
}
],
<span class="hljs-string">"claims"</span>:[
<span class="hljs-string">"given_name"</span>,
<span class="hljs-string">"nickname"</span>,
<span class="hljs-string">"email"</span>,
<span class="hljs-string">"email_verified"</span>
],
<span class="hljs-string">"authorization_details"</span>:[
{
<span class="hljs-string">"type"</span>:<span class="hljs-string">"account_information"</span>,
<span class="hljs-string">"actions"</span>:[
<span class="hljs-string">"list_accounts"</span>,
<span class="hljs-string">"read_balances"</span>,
<span class="hljs-string">"read_transactions"</span>
],
<span class="hljs-string">"locations"</span>:[
<span class="hljs-string">"https://example.com/accounts"</span>
]
}
]
}
</span></code></pre>
<h2 id="specifications">Specifications</h2>
<h3 id="general-method-for-requesting-authorization-over-http">General Method for Requesting Authorization over http</h3>
<p>OAuth 2.0: <a href="https://datatracker.ietf.org/doc/html/rfc6749">https://datatracker.ietf.org/doc/html/rfc6749</a>
The OAuth 2.0 Authorization Framework: Bearer Token Usage: <a href="https://www.rfc-editor.org/rfc/rfc6750">https://www.rfc-editor.org/rfc/rfc6750</a>
Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants: <a href="https://www.rfc-editor.org/rfc/rfc7521.html">https://www.rfc-editor.org/rfc/rfc7521.html</a></p>
<h3 id="methods-for-requesting-authorization-to-specialized-data-types">Methods for Requesting Authorization to specialized Data Types</h3>
<p>OpenID Connect Core: <a href="https://openid.net/specs/openid-connect-core-1_0.html">https://openid.net/specs/openid-connect-core-1_0.html</a> - for Authorization to identity data in via id_token and /userInfo API
Self Issued OIDC <a href="https://openid.net/specs/openid-connect-self-issued-v2-1_0.html">https://openid.net/specs/openid-connect-self-issued-v2-1_0.html</a> -
OpenID for Verifiable Presentations: <a href="https://openid.net/specs/openid-4-verifiable-presentations-1_0.html">https://openid.net/specs/openid-4-verifiable-presentations-1_0.html</a> - for Authorization to vp_token
OpenID for Verifiable Credential Issuance: <a href="https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html">https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html</a> - for Authorization at a Credential Endpoint.</p>
<h3 id="alternate-methods-for-requesting-authorization">Alternate Methods for Requesting Authorization</h3>
<p>Rich Authorization Requests: <a href="https://datatracker.ietf.org/doc/html/rfc9396">https://datatracker.ietf.org/doc/html/rfc9396</a>
JWT-Secured Authorization Request (JAR): <a href="https://datatracker.ietf.org/doc/html/rfc9101">https://datatracker.ietf.org/doc/html/rfc9101</a>
Pushed Authorization Requests (PAR): <a href="https://datatracker.ietf.org/doc/html/rfc9126">https://datatracker.ietf.org/doc/html/rfc9126</a></p>
<h3 id="methods-for-inspecting-and-managing-authorization-grants">Methods for Inspecting and Managing Authorization Grants</h3>
<p>Grant Management API: <a href="https://openid.net/specs/fapi-grant-management-01.html">https://openid.net/specs/fapi-grant-management-01.html</a></p>
<h3 id="authorization-semantics">Authorization Semantics</h3>
<p>Resource Indictors for OAuth: <a href="https://www.rfc-editor.org/rfc/rfc8707.html">https://www.rfc-editor.org/rfc/rfc8707.html</a>
JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens: <a href="https://datatracker.ietf.org/doc/html/rfc9068">https://datatracker.ietf.org/doc/html/rfc9068</a>
OAuth 2.0 Step Up Authentication Challenge Protocol <a href="https://datatracker.ietf.org/doc/rfc9470/">https://datatracker.ietf.org/doc/rfc9470/</a></p>
</body>
</html>