-
Notifications
You must be signed in to change notification settings - Fork 0
/
draft-ietf-oauth-jwt-introspection-response.xml
869 lines (780 loc) · 40.4 KB
/
draft-ietf-oauth-jwt-introspection-response.xml
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
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
<?xml version="1.0" encoding="UTF-8"?>
<!--
This template is for creating an Internet Draft using xml2rfc, which
is available here: http://xml.resource.org.
-->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- One method to get references from the online citation libraries.
There has to be one entity for each item to be referenced.
An alternate method (rfc include) is described in the references. -->
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
<!ENTITY RFC3552 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
<!ENTITY I-D.narten-iana-considerations-rfc2434bis SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.narten-iana-considerations-rfc2434bis.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!--
For a complete list and description of processing instructions (PIs),
please see http://xml.resource.org/authoring/README.html.
-->
<!--
Below are generally applicable Processing Instructions (PIs) that most
I-Ds might want to use. (Here they are set differently than their
defaults in xml2rfc v1.32)
-->
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="4"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!--
control vertical white space (using these PIs as follows is
recommended by the RFC Editor)
-->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<!-- keep one blank line between list items -->
<!-- end of list of popular I-D processing instructions -->
<rfc category="std" docName="draft-ietf-oauth-jwt-introspection-response-11"
ipr="trust200902">
<!--
category values: std, bcp, info, exp, and historic ipr values:
full3667, noModification3667, noDerivatives3667 you can add the
attributes updates="NNNN" and obsoletes="NNNN" they will automatically
be output with "(if approved)"
-->
<!-- ***** FRONT MATTER ***** -->
<front>
<!--
The abbreviated title is used in the page header - it is only
necessary if the full title is longer than 39 characters
-->
<title abbrev="JWT Response">JWT Response for OAuth Token Introspection</title>
<author fullname="Torsten Lodderstedt" initials="T." role="editor"
surname="Lodderstedt">
<organization>yes.com AG</organization>
<address>
<email>torsten@lodderstedt.net</email>
<!-- uri and facsimile elements may also be added -->
</address>
</author>
<author fullname="Vladimir Dzhuvinov" initials="V."
surname="Dzhuvinov">
<organization>Connect2id Ltd.</organization>
<address>
<email>vladimir@connect2id.com</email>
<!-- uri and facsimile elements may also be added -->
</address>
</author>
<date day="20" month="June" year="2021" />
<!-- Meta-data Declarations -->
<area>Security Area</area>
<workgroup>Open Authentication Protocol</workgroup>
<!--
WG name at the upperleft corner of the doc, IETF is fine for
individual submissions. If this element is not present, the default
is "Network Working Group", which is used by the RFC Editor as a nod
to the history of the IETF.
-->
<keyword>token introspection</keyword>
<keyword>JWT</keyword>
<keyword>oauth2</keyword>
<!--
Keywords will be incorporated into HTML output files in a meta tag
but they have no effect on text or nroff output. If you submit your
draft to the RFC Editor, the keywords will be used for the search
engine.
-->
<abstract>
<t>This specification proposes an additional JSON Web Token (JWT) secured response
for OAuth 2.0 Token Introspection.</t>
</abstract>
</front>
<middle>
<section anchor="Introduction" title="Introduction">
<t><xref target="RFC7662">OAuth 2.0 Token Introspection</xref> specifies a
method for a protected resource to query an OAuth 2.0 authorization server
to determine the state of an access token and obtain data associated with
the access token. This enables deployments to implement opaque access
tokens in an interoperable way.</t>
<t>The introspection response, as specified in <xref target="RFC7662">OAuth
2.0 Token Introspection</xref>, is a plain JSON object.
However, there are use cases where the resource server requires stronger
assurance that the authorization server issued the token introspection
response for an access token, including cases where the authorization server
assumes liability for the content of the token introspection response.
An example is a resource server using verified person data to create certificates,
which in turn are used to create qualified electronic signatures.</t>
<t>In such use cases it may be useful or even required to return a
signed <xref target="RFC7519">JWT</xref> as the introspection response.
This specification extends the token introspection endpoint with the capability
to return responses as JWTs.</t>
</section>
<section anchor="RNC" title="Requirements Notation and Conventions">
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL"
in this document are to be interpreted as described in
BCP 14 <xref target="RFC2119"/> <xref target="RFC8174"/>
when, and only when, they appear in all capitals, as shown here.
</t>
</section>
<section anchor="as-rs-relationship" title="Resource Server Management">
<t>The authorization server (AS) and the resource server (RS) maintain a strong two-way trust relationship.
The resource server relies on the authorization server to obtain authorization,
user and other data as input to its access control decisions and service delivery.
The authorization server relies on the resource server to handle the provided data
appropriately.</t>
<t>In the context of this specification, the token introspection endpoint is used to convey
such security data and potentially also privacy sensitive data related to an access
token.</t>
<t>In order to process the introspection requests in a secure and
privacy-preserving manner, the authorization server MUST be able to identify,
authenticate and authorize resource servers.</t>
<t>The authorization server MAY additionally encrypt the token introspection response JWTs.
If encryption is used the authorization server is provisioned with encryption keys and
algorithms for the RS.</t>
<t>The authorization server MUST be able to determine whether an RS is the
audience for a particular access token and what data it is entitled to receive,
otherwise the RS is not authorized to obtain data for the access token.
The AS has the discretion how to fulfil this requirement. The AS could, for example,
maintain a mapping between scope values and resource servers.</t>
<t>The requirements given above imply that the authorization server
maintains credentials and other configuration data for each RS.</t>
<t>One way is by utilizing dynamic client registration <xref target="RFC7591"/>
and treating every RS as an OAuth client. In this case, the authorization server
is assumed to at least maintain a "client_id" and a "token_endpoint_auth_method"
with complementary authentication method metadata, such as "jwks" or "client_secret".
In cases where the AS needs to acquire consent to transmit data to a RS, the following
client metadata fields are recommended: "client_name", "client_uri", "contacts",
"tos_uri", "policy_uri".</t>
<t>The AS MUST restrict the use of client credentials by a RS to the calls
it requires, e.g. the AS MAY restrict such a client to call
the token introspection endpoint only. How the AS implements this restriction
is beyond the scope of this specification.</t>
<t>This specification further introduces client metadata to manage the
configuration options required to sign and encrypt token introspection
response JWTs.</t>
</section>
<section anchor="jwt_request" title="Requesting a JWT Response">
<t>A resource server requests a JWT introspection response by sending an introspection request
with an <spanx style="verb">Accept</spanx> HTTP header field set to
"application/token-introspection+jwt".</t>
<t>The AS MUST authenticate the caller at the token introspection endpoint. Authentication can
utilize client authentication methods or a separate access token issued to the resource server
and identifying it as subject.</t>
<t>The following is a non-normative example request, with the resource
server authenticating with a private key JWT:</t>
<t>
<figure>
<artwork><![CDATA[POST /introspect HTTP/1.1
Host: as.example.com
Accept: application/token-introspection+jwt
Content-Type: application/x-www-form-urlencoded
token=2YotnFZFEjr1zCsicMWpAA&
client_assertion_type=
urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
client_assertion=PHNhbWxwOl[...omitted for brevity...]ZT]]></artwork>
</figure>
</t>
</section>
<section anchor="jwt_response" title="JWT Response">
<t>The introspection endpoint responds with a JWT, setting the
<spanx style="verb">Content-Type</spanx> HTTP header field to
"application/token-introspection+jwt" and the JWT <spanx style="verb">typ</spanx>
("type") header parameter to "token-introspection+jwt".</t>
<t>The JWT MUST include the following top-level claims:
<list hangIndent="8" style="hanging">
<t hangText="iss">MUST be set to the issuer URL of the authorization
server.</t>
<t hangText="aud">MUST identify the resource server receiving the token
introspection response.</t>
<t hangText="iat">MUST be set to the time when the introspection response
was created by the authorization server.</t>
<t hangText="token_introspection">A JSON object containing the members
of the token introspection response as specified in <xref target="RFC7662"/>, section 2.2.
The separation of the introspection response members into
a dedicated containing JWT claim is intended to prevent conflict and confusion
with top-level JWT claims that may bear the same name.
<vspace blankLines="1" />
If the access token is invalid, expired, revoked, or not intended for the
calling resource server (audience), the authorization server MUST set the value of the
<spanx style="verb">active</spanx> member in the <spanx style="verb">token_introspection</spanx>
claim to <spanx style="verb">false</spanx> and MUST NOT include other members.
Otherwise, the <spanx style="verb">active</spanx> member is set to <spanx style="verb">true</spanx>.
<vspace blankLines="1" />
The AS SHOULD narrow down the <spanx style="verb">scope</spanx> value to the scopes
relevant to the particular RS.
<vspace blankLines="1" />
As specified in section 2.2 of <xref target="RFC7662"/>, implementations MAY extend the
token introspection response with service-specific claims. In the context of this
specification, such claims will be added as top-level members of the
<spanx style="verb">token_introspection</spanx> claim.
<vspace blankLines="1" />
Token introspection response parameter names intended to be used across domains MUST be
registered in the <xref target="IANA.OAuth.Token.Introspection">OAuth Token Introspection
Response registry</xref> defined by <xref target="RFC7662"/>.
<vspace blankLines="1" />
When the AS acts as a provider of resource owner
identity claims to the RS, the AS determines based on its RS-specific policy what
identity claims to return in the token introspection response.
The AS MUST ensure the release of any privacy-sensitive data is legally based (see
<xref target="privacy"/>).
<vspace blankLines="1" />
Further content of the introspection response is determined by the RS-specific
policy at the AS.</t>
</list>
</t>
<t>The JWT MAY include other claims, including those from the "JSON Web Token Claims"
registry established by <xref target="RFC7519"/>. The JWT SHOULD NOT include the
<spanx style="verb">sub</spanx> and <spanx style="verb">exp</spanx> claims,
as an additional prevention against misuse of the JWT as an access token (see
<xref target="Cross-JWT_Confusion"/>).</t>
<t>Note: Although the JWT format is widely used as an access token format, the JWT
returned in the introspection response is not an alternative representation of
the introspected access token and is not intended to be used as an access token.</t>
<t>This specification registers the "application/token-introspection+jwt" media type,
which is used as value of the <spanx style="verb">typ</spanx> ("type") header
parameter of the JWT to indicate that the payload is a token introspection response.</t>
<t>The JWT is cryptographically secured as specified in <xref target="RFC7519"/>.</t>
<t>Depending on the specific resource server policy the JWT is either
signed, or signed and encrypted. If the JWT is signed and encrypted it
MUST be a Nested JWT, as defined in <xref target="RFC7519">JWT</xref>.</t>
<t>Note: An AS compliant with this specification MUST refuse to serve introspection
requests that don't authenticate the caller, and return an HTTP status code 400. This is
done to ensure token data is released to legitimate recipients only and prevent
downgrading to <xref target="RFC7662"/> behavior (see
<xref target="token_data_leakage"/>).</t>
<t>The following is a non-normative example response
(with line breaks for display purposes only):</t>
<t>
<figure>
<artwork><![CDATA[HTTP/1.1 200 OK
Content-Type: application/token-introspection+jwt
eyJraWQiOiJ3RzZEIiwidHlwIjoidG9rZW4taW50cm9zcGVjdGlvbitqd3QiLCJhbGc
iOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL2FzLmV4YW1wbGUuY29tLyIsImF1ZCI6I
mh0dHBzOi8vcnMuZXhhbXBsZS5jb20vcmVzb3VyY2UiLCJpYXQiOjE1MTQ3OTc4OTIs
InRva2VuX2ludHJvc3BlY3Rpb24iOnsiYWN0aXZlIjp0cnVlLCJpc3MiOiJodHRwczo
vL2FzLmV4YW1wbGUuY29tLyIsImF1ZCI6Imh0dHBzOi8vcnMuZXhhbXBsZS5jb20vcm
Vzb3VyY2UiLCJpYXQiOjE1MTQ3OTc4MjIsImV4cCI6MTUxNDc5Nzk0MiwiY2xpZW50X
2lkIjoicGFpQjJnb28wYSIsInNjb3BlIjoicmVhZCB3cml0ZSBkb2xwaGluIiwic3Vi
IjoiWjVPM3VwUEM4OFFyQWp4MDBkaXMiLCJiaXJ0aGRhdGUiOiIxOTgyLTAyLTAxIiw
iZ2l2ZW5fbmFtZSI6IkpvaG4iLCJmYW1pbHlfbmFtZSI6IkRvZSIsImp0aSI6InQxRm
9DQ2FaZDRYdjRPUkpVV1ZVZVRaZnNLaFczMENRQ3JXRERqd1h5NncifX0.przJMU5Gh
mNzvwtt1Sr-xa9xTkpiAg5IshbQsRiRVP_7eGR1GHYrNwQh84kxOkHCyje2g5WSRcYo
sGEVIiC-eoPJJ-qBwqwSlgx9JEeCDw2W5DjrblOI_N0Jvsq_dUeOyoWVMqlOydOBhKN
Y0smBrI4NZvEExucOm9WUJXMuJtvq1gBes-0go5j4TEv9sOP9uu81gqWTr_LOo6pgT0
tFFyZfWC4kbXPXiQ2YT6mxCiQRRNM-l9cBdF6Jx6IOrsfFhBuYdYQ_mlL19HgDDOFal
eyqmru6lKlASOsaE8dmLSeKcX91FbG79FKN8un24iwIDCbKT9xlUFl54xWVShNDFA]]></artwork>
</figure>
</t>
<t>
The example response JWT header contains the following JSON document:
</t>
<t>
<figure>
<artwork><![CDATA[{
"typ": "token-introspection+jwt",
"alg": "RS256",
"kid": "wG6D"
}]]></artwork>
</figure>
</t>
<t>
The example response JWT payload contains the following JSON document:
</t>
<t>
<figure>
<artwork><![CDATA[{
"iss":"https://as.example.com/",
"aud":"https://rs.example.com/resource",
"iat":1514797892,
"token_introspection":
{
"active":true,
"iss":"https://as.example.com/",
"aud":"https://rs.example.com/resource",
"iat":1514797822,
"exp":1514797942,
"client_id":"paiB2goo0a",
"scope":"read write dolphin",
"sub":"Z5O3upPC88QrAjx00dis",
"birthdate":"1982-02-01",
"given_name":"John",
"family_name":"Doe",
"jti":"t1FoCCaZd4Xv4ORJUWVUeTZfsKhW30CQCrWDDjwXy6w"
}
}]]></artwork>
</figure>
</t>
</section>
<section anchor="client_metadata" title="Client Metadata">
<t>The authorization server determines the algorithm to
secure the JWT for a particular introspection response. This decision can
be based on registered metadata parameters for the resource server,
supplied via dynamic client registration <xref target="RFC7591"/> with the
resource server acting as a client, as specified below.</t>
<t>The parameter names follow the pattern established by
<xref target="OpenID.Registration">OpenID Connect
Dynamic Client Registration</xref> for configuring signing and encryption
algorithms for JWT responses at the UserInfo endpoint.</t>
<t>The following client metadata parameters are introduced by this
specification:
<list hangIndent="8" style="hanging">
<t hangText="introspection_signed_response_alg">OPTIONAL.
<xref target="RFC7515">JWS</xref>
algorithm (<spanx style="verb">alg</spanx> value) as defined in
<xref target="RFC7518">JWA</xref> for signing introspection responses. If
this is specified, the response will be signed using JWS and the
configured algorithm. The default, if omitted, is <spanx style="verb">RS256</spanx>.</t>
<t hangText="introspection_encrypted_response_alg">OPTIONAL.
<xref target="RFC7516">JWE</xref> algorithm (<spanx style="verb">alg</spanx> value)
as defined in <xref target="RFC7518">JWA</xref> for content key encryption.
If this is specified, the response will be encrypted using JWE and the
configured content encryption algorithm
(<spanx style="verb">introspection_encrypted_response_enc</spanx>). The default,
if omitted, is that no encryption is performed.
If both signing and
encryption are requested, the response will be
signed then encrypted, with the result being a Nested JWT, as defined in
<xref target="RFC7519">JWT</xref>.</t>
<t hangText="introspection_encrypted_response_enc">OPTIONAL.
<xref target="RFC7516">JWE</xref> algorithm (<spanx style="verb">enc</spanx> value)
as defined in <xref target="RFC7518">JWA</xref> for content encryption of
introspection responses. The default, if omitted, is <spanx style="verb">A128CBC-HS256</spanx>.
Note: This parameter MUST NOT be specified without setting
<spanx style="verb">introspection_encrypted_response_alg</spanx>.</t>
</list>
</t>
<t>Resource servers may register their public encryption keys
using the <spanx style="verb">jwks_uri</spanx> or <spanx style="verb">jwks</spanx>
metadata parameters.</t>
</section>
<section anchor="server_metadata" title="Authorization Server Metadata">
<t>Authorization servers SHOULD publish the supported algorithms for
signing and encrypting the JWT of an introspection response by utilizing
<xref target="RFC8414">OAuth 2.0 Authorization Server Metadata</xref>
parameters. Resource servers use this data to parametrize their client
registration requests.</t>
<t>The following parameters are introduced by this specification:
<list hangIndent="8" style="hanging">
<t hangText="introspection_signing_alg_values_supported">
OPTIONAL. JSON array containing a list of the <xref target="RFC7515">JWS</xref> signing
algorithms (<spanx style="verb">alg</spanx> values) as defined in
<xref target="RFC7518">JWA</xref> supported by the introspection
endpoint to sign the response.</t>
<t hangText="introspection_encryption_alg_values_supported">
OPTIONAL. JSON array containing a list of the <xref target="RFC7516">JWE</xref>
encryption algorithms (<spanx style="verb">alg</spanx> values) as defined in
<xref target="RFC7518">JWA</xref> supported by the
introspection endpoint to encrypt the content encryption key for
introspection responses (content key encryption).</t>
<t hangText="introspection_encryption_enc_values_supported">
OPTIONAL. JSON array containing a list of the <xref target="RFC7516">JWE</xref>
encryption algorithms (<spanx style="verb">enc</spanx> values) as defined in
<xref target="RFC7518">JWA</xref> supported by the introspection
endpoint to encrypt the response (content encryption).</t>
</list>
</t>
</section>
<section anchor="Security" title="Security Considerations">
<section anchor="Cross-JWT_Confusion" title="Cross-JWT Confusion">
<t>The <spanx style="verb">iss</spanx> and potentially the <spanx style="verb">aud</spanx>
claim of a token introspection JWT can resemble those of a JWT-encoded access token.
An attacker could try to exploit this and pass a JWT token introspection response as
an access token to the resource server. The <spanx style="verb">typ</spanx> ("type")
JWT header "token-introspection+jwt" and the encapsulation of the token introspection members
such as <spanx style="verb">sub</spanx> and <spanx style="verb">scope</spanx> in
the <spanx style="verb">token_introspection</spanx> claim is intended to prevent such
substitution attacks. Resource servers MUST therefore check the <spanx style="verb">typ</spanx>
JWT header value of received JWT-encoded access tokens and ensure all minimally
required claims for a valid access token are present.</t>
<t>Resource servers MUST additionally apply the countermeasures against replay
as described in <xref target="I-D.ietf-oauth-security-topics"/>, section 3.2.</t>
<t>JWT Confusion and other attacks involving JWTs are discussed in
<xref target="I-D.ietf-oauth-jwt-bcp"/>.</t>
</section>
<section anchor="token_data_leakage" title="Token Data Leakage">
<t>The authorization server MUST use Transport Layer Security (TLS) 1.2
(or higher) per BCP 195 <xref target="RFC7525"/> in order to prevent
token data leakage.</t>
<t>Section 2.1 of <xref target="RFC7662"/> permits requests to the introspection endpoint to
be authorized with an access token which doesn't identify the caller. To prevent
introspection of tokens by parties that are not the intended consumer the
authorization server MUST require all requests to the token introspection endpoint to be
authenticated.</t>
</section>
</section>
<section anchor="privacy" title="Privacy Considerations">
<t>The token introspection response can be used to transfer personal identifiable
information (PII) from the AS to the RS. The AS MUST conform to legal and jurisdictional constraints
for the data transfer before any data is released to a particular RS. The details and determining
of these constraints varies by jurisdiction and is outside the scope of this document.</t>
<t>A commonly found way to establish the legal basis for releasing PII is by explicit user
consent gathered from the resource owner by the AS during the authorization flow.</t>
<t>It is also possible that the legal basis is established out of band, for example in
an explicit contract or by the client gathering the resource owner's consent.</t>
<t>If the AS and the RS belong to the same legal entity (1st party scenario), there is
potentially no need for an explicit user consent but the terms of service and policy
of the respective service provider MUST be enforced at all times.</t>
<t>In any case, the AS MUST ensure that the scope of the legal basis is enforced
throughout the whole process. The AS MUST retain the scope of the legal basis with
the access token, e.g. in the scope value, it MUST authenticate the RS, and the AS MUST
determine the data a resource server is allowed to receive based on the resource server’s identity and
suitable token data, e.g. the scope value. </t>
<t>Implementers should be aware that a token introspection request lets the AS know when the client
(and potentially the user) is accessing the RS, which is also an indication of when the user is using
the client. If this implication is not acceptable, implementers MUST use other means to relay
access token data, for example by directly transferring the data needed by the RS within the access
token.</t>
</section>
<section anchor="Acknowledgements" title="Acknowledgements">
<t>We would like to thank Petteri Stenius, Neil Madden, Filip Skokan, Tony
Nadalin, Remco Schaar, Justin Richer, Takahiko Kawasaki, Benjamin Kaduk,
Robert Wilton and Roman Danyliw for their valuable feedback.</t>
</section>
<!-- Possibly a 'Contributors' section ... -->
<section anchor="IANA" title="IANA Considerations">
<section anchor="DynRegReg" title="OAuth Dynamic Client Registration Metadata Registration">
<t>
This specification requests registration of the following client metadata definitions
in the IANA "OAuth Dynamic Client Registration Metadata" registry
<xref target="IANA.OAuth.Parameters"/>
established by <xref target="RFC7591"/>:
</t>
<section anchor="DynRegContents" title="Registry Contents">
<t>
<list style="symbols">
<t>
Client Metadata Name: <spanx style="verb">introspection_signed_response_alg</spanx>
</t>
<t>
Client Metadata Description:
String value indicating the client's desired introspection response
signing algorithm.
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): <xref target="client_metadata"/> of [[ this specification ]]
</t>
</list>
</t>
<t>
<list style="symbols">
<t>
Client Metadata Name: <spanx style="verb">introspection_encrypted_response_alg</spanx>
</t>
<t>
Client Metadata Description:
String value specifying the desired introspection response
content key encryption algorithm (alg value).
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): <xref target="client_metadata"/> of [[ this specification ]]
</t>
</list>
</t>
<t>
<list style="symbols">
<t>
Client Metadata Name: <spanx style="verb">introspection_encrypted_response_enc</spanx>
</t>
<t>
Client Metadata Description:
String value specifying the desired introspection response
content encryption algorithm (enc value).
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): <xref target="client_metadata"/> of [[ this specification ]]
</t>
</list>
</t>
</section>
</section>
<section anchor="ietf-oauth-discoveryIANA" title="OAuth Authorization Server Metadata Registration">
<t>
This specification requests registration of the following values
in the IANA "OAuth Authorization Server Metadata" registry
<xref target="IANA.OAuth.Parameters"/> established by <xref target="RFC8414"/>.
</t>
<section title="Registry Contents">
<t>
<list style='symbols'>
<t>Metadata Name: <spanx style="verb">introspection_signing_alg_values_supported</spanx></t>
<t>Metadata Description: JSON array containing a list of algorithms supported
by the authorization server for introspection response signing.</t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="server_metadata"/> of [[ this specification ]]</t>
</list>
</t>
<t>
<list style='symbols'>
<t>Metadata Name: <spanx style="verb">introspection_encryption_alg_values_supported</spanx></t>
<t>Metadata Description: JSON array containing a list of algorithms supported
by the authorization server for introspection response content key encryption (alg value).</t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="server_metadata"/> of [[ this specification ]]</t>
</list>
</t>
<t>
<list style='symbols'>
<t>Metadata Name: <spanx style="verb">introspection_encryption_enc_values_supported</spanx></t>
<t>Metadata Description: JSON array containing a list of algorithms supported
by the authorization server for introspection response content encryption (enc value).</t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="server_metadata"/> of [[ this specification ]]</t>
</list>
</t>
</section>
</section>
<section anchor="ietf-media-typeIANA" title="Media Type Registration">
<t>This section registers the "application/token-introspection+jwt" media type
in the "Media Types" registry <xref target="IANA.MediaTypes"/> in the
manner described in <xref target="RFC6838"/>, which can be used to indicate that the
content is a token introspection response in JWT format.</t>
<section title="Registry Contents">
<t>
<list style='symbols'>
<t>Type name: application</t>
<t>Subtype name: token-introspection+jwt</t>
<t>Required parameters: N/A</t>
<t>Optional parameters: N/A</t>
<t>Encoding considerations: binary; A token introspection response is a JWT; JWT values are
encoded as a series of base64url-encoded values (with trailing '='
characters removed), some of which may be the empty string,
separated by period ('.') characters.</t>
<t>Security considerations: See Section 7 of this specification</t>
<t>Interoperability considerations: N/A</t>
<t>Published specification: Section 4 of this specification</t>
<t>Applications that use this media type: Applications that produce and consume
OAuth Token Introspection Responses in JWT format</t>
<t>Fragment identifier considerations: N/A</t>
<t>Additional information:
<list style='symbols'>
<t>Magic number(s): N/A</t>
<t>File extension(s): N/A</t>
<t>Macintosh file type code(s): N/A</t>
</list>
</t>
<t>Person & email address to contact for further information: Torsten Lodderstedt,
torsten@lodderstedt.net</t>
<t>Intended usage: COMMON</t>
<t>Restrictions on usage: none</t>
<t>Author: Torsten Lodderstedt, torsten@lodderstedt.net</t>
<t>Change controller: IESG</t>
<t>Provisional registration? No</t>
</list>
</t>
</section>
</section>
<section anchor="ietf-jwt-IANA" title="JWT Claim Registration">
<t>This section registers the "token_introspection" claim in the JSON Web
Token (JWT) IANA registry <xref target="IANA.JWT"/> in the manner described in
<xref target="RFC7519"/>.</t>
<section title="Registry Contents">
<t>
<list style='symbols'>
<t>Claim name: token_introspection</t>
<t>Claim description: Token introspection response</t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="jwt_response"/> of [[this specification]]</t>
</list>
</t>
</section>
</section>
</section>
</middle>
<!-- *****BACK MATTER ***** -->
<back>
<references title="Normative References">
<?rfc include="reference.RFC.2119"?>
<?rfc include="reference.RFC.6838"?>
<?rfc include="reference.RFC.7519"?>
<?rfc include="reference.RFC.7525"?>
<?rfc include="reference.RFC.7591"?>
<?rfc include="reference.RFC.7662"?>
<?rfc include="reference.RFC.7518"?>
<?rfc include="reference.RFC.7515"?>
<?rfc include="reference.RFC.7516"?>
<?rfc include="reference.RFC.8174"?>
<?rfc include="reference.RFC.8414"?>
<?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-jwt-bcp-06.xml'?>
<?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-security-topics-13.xml'?>
<reference anchor="OpenID.Registration" target="https://openid.net/specs/openid-connect-registration-1_0.html">
<front>
<title>OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 1</title>
<author fullname="Nat Sakimura">
<organization>NRI</organization>
</author>
<author fullname="John Bradley">
<organization>Ping Identity</organization>
</author>
<author fullname="Mike Jones">
<organization>Microsoft</organization>
</author>
<date day="8" month="Nov" year="2014"/>
</front>
</reference>
<reference anchor="IANA.MediaTypes" target="http://www.iana.org/assignments/media-types">
<front>
<title>Media Types</title>
<author fullname="IANA">
<organization abbrev="ISO">IANA</organization>
</author>
<date/>
</front>
</reference>
<reference anchor="IANA.JWT" target="https://www.iana.org/assignments/jwt/jwt.xhtml#claims">
<front>
<title>JSON Web Token (JWT) claims registry</title>
<author fullname="IANA">
<organization abbrev="ISO">IANA</organization>
</author>
<date/>
</front>
</reference>
<reference anchor="IANA.OAuth.Token.Introspection" target="https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#token-introspection-response">
<front>
<title>OAuth Token Introspection Response registry</title>
<author>
<organization>IANA</organization>
</author>
<date/>
</front>
</reference>
</references>
<references title="Informative References">
<reference anchor="IANA.OAuth.Parameters" target="http://www.iana.org/assignments/oauth-parameters">
<front>
<title>OAuth Parameters</title>
<author>
<organization>IANA</organization>
</author>
<date/>
</front>
</reference>
</references>
<section anchor="History" title="Document History">
<t>[[ To be removed from the final specification ]]</t>
<t>-11<list style="symbols">
<t>consistent normative language that the AS must authenticate all callers
to the token introspection endpoint when complying with this specification</t>
<t>removes text that claims from the JSON Web Token Claims registry may be included
in the token_introspection claim</t>
<t>updates the privacy considerations section</t>
<t>fixes the example BASE64URL encoded JWT payload</t>
</list>
</t>
<t>-10<list style="symbols">
<t>added requirement to authenticate RS if privacy sensitive data is released</t>
<t>reworked text on claims from different registries</t>
<t>added forward reference to privacy considerations to section 5</t>
<t>added text in privacy considerations regarding client/user tracking</t>
</list>
</t>
<t>-09<list style="symbols">
<t>changes the Accept and Content-Type HTTP headers from
"application/json" to "application/token-introspection+jwt" so they
match the registered media type</t>
<t>moves the token introspection response members into a JSON object
claim named "token_introspection" to provide isolation from the top-level
JWT-specific claims</t>
<t>"iss", "aud" and "iat" MUST be present as top-level JWT claims</t>
<t>the "sub" and "exp" claims SHOULD NOT be used as top-level JWT
claims as additional prevention against JWT access token substitution
attacks</t>
</list>
</t>
<t>-08<list style="symbols">
<t>made difference between introspected access token and
introspection response clearer</t>
<t>defined semantics of JWT claims overlapping between
introspected access token and introspection response as JWT</t>
<t>added section about RS management</t>
<t>added text about user claims including a privacy considerations section</t>
<t>removed registration of OpenID Connect claims to "Token
Introspection Response" registry and refer to "JWT Claims" registry instead</t>
<t>added registration of "application/token-introspection+jwt" media type as
type identifier of token introspection responses in JWT format</t>
<t>more changed to incorporate IESG review feedback</t>
</list>
</t>
<t>-07<list style="symbols">
<t>fixed wrong description of "locale"</t>
<t>added references for ISO and ITU specifications</t>
</list>
</t>
<t>-06<list style="symbols">
<t>replaced reference to RFC 7159 with reference to RFC 8259</t>
</list>
</t>
<t>-05<list style="symbols">
<t>improved wording for TLS requirement</t>
<t>added RFC 2119 boilerplate</t>
<t>fixed and updated some references</t>
</list>
</t>
<t>-04<list style="symbols">
<t>reworked definition of parameters in section 4</t>
<t>added text on data minimization to security considerations section</t>
<t>added statement regarding TLS to security considerations section</t>
</list>
</t>
<t>-03<list style="symbols">
<t>added registration for OpenID Connect Standard Claims to
OAuth Token Introspection Response registry</t>
</list>
</t>
<t>-02<list style="symbols">
<t>updated references</t>
</list>
</t>
<t>-01<list style="symbols">
<t>adapted wording to preclude any accept header except "application/jwt" if
encrypted responses are required</t>
<t>use registered alg value RS256 for default signing algorithm</t>
<t>added text on claims in the token introspection response</t>
</list>
</t>
<t>-00<list style="symbols">
<t>initial version of the WG draft</t>
<t>defined default signing algorithm</t>
<t>changed behavior in case resource server is set up for encryption</t>
<t>Added text on token data leakage prevention to the security considerations</t>
<t>moved Security Considerations section forward</t>
</list>
</t>
<t>WG draft</t>
<t>-01<list style="symbols">
<t>fixed typos in client meta data field names</t>
<t>added OAuth Server Metadata parameters to publish algorithms supported
for signing and encrypting the introspection response</t>
<t>added registration of new parameters for OAuth Server Metadata
and Client Registration</t>
<t>added explicit request for JWT introspection response</t>
<t>made iss and aud claims mandatory in introspection response</t>
<t>Stylistic and clarifying edits, updates references</t>
</list></t>
<t>-00<list style="symbols">
<t>initial version</t>
</list></t>
</section>
</back>
</rfc>