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
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
|
<pre>Internet Engineering Task Force (IETF) J. Richer, Ed.
Request for Comments: 7662 October 2015
Category: Standards Track
ISSN: 2070-1721
<span class="h1">OAuth 2.0 Token Introspection</span>
Abstract
This specification defines a method for a protected resource to query
an OAuth 2.0 authorization server to determine the active state of an
OAuth 2.0 token and to determine meta-information about this token.
OAuth 2.0 deployments can use this method to convey information about
the authorization context of the token from the authorization server
to the protected resource.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in <a href="./rfc5741#section-2">Section 2 of RFC 5741</a>.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
<a href="http://www.rfc-editor.org/info/rfc7662">http://www.rfc-editor.org/info/rfc7662</a>.
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and the IETF Trust's Legal
Provisions Relating to IETF Documents
(<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
<span class="grey">Richer Standards Track [Page 1]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-2" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
Table of Contents
<a href="#section-1">1</a>. Introduction . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-2">2</a>
<a href="#section-1.1">1.1</a>. Notational Conventions . . . . . . . . . . . . . . . . . <a href="#page-3">3</a>
<a href="#section-1.2">1.2</a>. Terminology . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-3">3</a>
<a href="#section-2">2</a>. Introspection Endpoint . . . . . . . . . . . . . . . . . . . <a href="#page-3">3</a>
<a href="#section-2.1">2.1</a>. Introspection Request . . . . . . . . . . . . . . . . . . <a href="#page-4">4</a>
<a href="#section-2.2">2.2</a>. Introspection Response . . . . . . . . . . . . . . . . . <a href="#page-6">6</a>
<a href="#section-2.3">2.3</a>. Error Response . . . . . . . . . . . . . . . . . . . . . <a href="#page-8">8</a>
<a href="#section-3">3</a>. IANA Considerations . . . . . . . . . . . . . . . . . . . . . <a href="#page-9">9</a>
<a href="#section-3.1">3.1</a>. OAuth Token Introspection Response Registry . . . . . . . <a href="#page-9">9</a>
<a href="#section-3.1.1">3.1.1</a>. Registration Template . . . . . . . . . . . . . . . . <a href="#page-10">10</a>
<a href="#section-3.1.2">3.1.2</a>. Initial Registry Contents . . . . . . . . . . . . . . <a href="#page-10">10</a>
<a href="#section-4">4</a>. Security Considerations . . . . . . . . . . . . . . . . . . . <a href="#page-12">12</a>
<a href="#section-5">5</a>. Privacy Considerations . . . . . . . . . . . . . . . . . . . <a href="#page-14">14</a>
<a href="#section-6">6</a>. References . . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-15">15</a>
<a href="#section-6.1">6.1</a>. Normative References . . . . . . . . . . . . . . . . . . <a href="#page-15">15</a>
<a href="#section-6.2">6.2</a>. Informative References . . . . . . . . . . . . . . . . . <a href="#page-16">16</a>
<a href="#appendix-A">Appendix A</a>. Use with Proof-of-Possession Tokens . . . . . . . . <a href="#page-17">17</a>
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-17">17</a>
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . <a href="#page-17">17</a>
<span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span>
In OAuth 2.0 [<a href="./rfc6749" title=""The OAuth 2.0 Authorization Framework"">RFC6749</a>], the contents of tokens are opaque to clients.
This means that the client does not need to know anything about the
content or structure of the token itself, if there is any. However,
there is still a large amount of metadata that may be attached to a
token, such as its current validity, approved scopes, and information
about the context in which the token was issued. These pieces of
information are often vital to protected resources making
authorization decisions based on the tokens being presented. Since
OAuth 2.0 does not define a protocol for the resource server to learn
meta-information about a token that it has received from an
authorization server, several different approaches have been
developed to bridge this gap. These include using structured token
formats such as JWT [<a href="./rfc7519" title=""JSON Web Token (JWT)"">RFC7519</a>] or proprietary inter-service
communication mechanisms (such as shared databases and protected
enterprise service buses) that convey token information.
This specification defines a protocol that allows authorized
protected resources to query the authorization server to determine
the set of metadata for a given token that was presented to them by
an OAuth 2.0 client. This metadata includes whether or not the token
is currently active (or if it has expired or otherwise been revoked),
what rights of access the token carries (usually conveyed through
OAuth 2.0 scopes), and the authorization context in which the token
was granted (including who authorized the token and which client it
<span class="grey">Richer Standards Track [Page 2]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-3" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
was issued to). Token introspection allows a protected resource to
query this information regardless of whether or not it is carried in
the token itself, allowing this method to be used along with or
independently of structured token values. Additionally, a protected
resource can use the mechanism described in this specification to
introspect the token in a particular authorization decision context
and ascertain the relevant metadata about the token to make this
authorization decision appropriately.
<span class="h3"><a class="selflink" id="section-1.1" href="#section-1.1">1.1</a>. Notational Conventions</span>
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
[<a href="./rfc2119" title=""Key words for use in RFCs to Indicate Requirement Levels"">RFC2119</a>].
Unless otherwise noted, all the protocol parameter names and values
are case sensitive.
<span class="h3"><a class="selflink" id="section-1.2" href="#section-1.2">1.2</a>. Terminology</span>
This section defines the terminology used by this specification.
This section is a normative portion of this specification, imposing
requirements upon implementations.
This specification uses the terms "access token", "authorization
endpoint", "authorization grant", "authorization server", "client",
"client identifier", "protected resource", "refresh token", "resource
owner", "resource server", and "token endpoint" defined by OAuth 2.0
[<a href="./rfc6749" title=""The OAuth 2.0 Authorization Framework"">RFC6749</a>], and the terms "claim names" and "claim values" defined by
JSON Web Token (JWT) [<a href="./rfc7519" title=""JSON Web Token (JWT)"">RFC7519</a>].
This specification defines the following terms:
Token Introspection
The act of inquiring about the current state of an OAuth 2.0 token
through use of the network protocol defined in this document.
Introspection Endpoint
The OAuth 2.0 endpoint through which the token introspection
operation is accomplished.
<span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. Introspection Endpoint</span>
The introspection endpoint is an OAuth 2.0 endpoint that takes a
parameter representing an OAuth 2.0 token and returns a JSON
[<a href="./rfc7159" title=""The JavaScript Object Notation (JSON) Data Interchange Format"">RFC7159</a>] document representing the meta information surrounding the
token, including whether this token is currently active. The
<span class="grey">Richer Standards Track [Page 3]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-4" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
definition of an active token is dependent upon the authorization
server, but this is commonly a token that has been issued by this
authorization server, is not expired, has not been revoked, and is
valid for use at the protected resource making the introspection
call.
The introspection endpoint MUST be protected by a transport-layer
security mechanism as described in <a href="#section-4">Section 4</a>. The means by which the
protected resource discovers the location of the introspection
endpoint are outside the scope of this specification.
<span class="h3"><a class="selflink" id="section-2.1" href="#section-2.1">2.1</a>. Introspection Request</span>
The protected resource calls the introspection endpoint using an HTTP
POST [<a href="./rfc7231" title=""Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content"">RFC7231</a>] request with parameters sent as
"application/x-www-form-urlencoded" data as defined in
[<a href="#ref-W3C.REC-html5-20141028">W3C.REC-html5-20141028</a>]. The protected resource sends a parameter
representing the token along with optional parameters representing
additional context that is known by the protected resource to aid the
authorization server in its response.
token
REQUIRED. The string value of the token. For access tokens, this
is the "access_token" value returned from the token endpoint
defined in OAuth 2.0 <a href="./rfc6749#section-5.1">[RFC6749], Section 5.1</a>. For refresh tokens,
this is the "refresh_token" value returned from the token endpoint
as defined in OAuth 2.0 <a href="./rfc6749#section-5.1">[RFC6749], Section 5.1</a>. Other token types
are outside the scope of this specification.
token_type_hint
OPTIONAL. A hint about the type of the token submitted for
introspection. The protected resource MAY pass this parameter to
help the authorization server optimize the token lookup. If the
server is unable to locate the token using the given hint, it MUST
extend its search across all of its supported token types. An
authorization server MAY ignore this parameter, particularly if it
is able to detect the token type automatically. Values for this
field are defined in the "OAuth Token Type Hints" registry defined
in OAuth Token Revocation [<a href="./rfc7009" title=""OAuth 2.0 Token Revocation"">RFC7009</a>].
The introspection endpoint MAY accept other OPTIONAL parameters to
provide further context to the query. For instance, an authorization
server may desire to know the IP address of the client accessing the
protected resource to determine if the correct client is likely to be
presenting the token. The definition of this or any other parameters
are outside the scope of this specification, to be defined by service
documentation or extensions to this specification. If the
authorization server is unable to determine the state of the token
<span class="grey">Richer Standards Track [Page 4]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-5" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
without additional information, it SHOULD return an introspection
response indicating the token is not active as described in
<a href="#section-2.2">Section 2.2</a>.
To prevent token scanning attacks, the endpoint MUST also require
some form of authorization to access this endpoint, such as client
authentication as described in OAuth 2.0 [<a href="./rfc6749" title=""The OAuth 2.0 Authorization Framework"">RFC6749</a>] or a separate
OAuth 2.0 access token such as the bearer token described in OAuth
2.0 Bearer Token Usage [<a href="./rfc6750" title=""The OAuth 2.0 Authorization Framework: Bearer Token Usage"">RFC6750</a>]. The methods of managing and
validating these authentication credentials are out of scope of this
specification.
For example, the following shows a protected resource calling the
token introspection endpoint to query about an OAuth 2.0 bearer
token. The protected resource is using a separate OAuth 2.0 bearer
token to authorize this call.
The following is a non-normative example request:
POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 23410913-abewfq.123483
token=2YotnFZFEjr1zCsicMWpAA
In this example, the protected resource uses a client identifier and
client secret to authenticate itself to the introspection endpoint.
The protected resource also sends a token type hint indicating that
it is inquiring about an access token.
The following is a non-normative example request:
POST /introspect HTTP/1.1
Host: server.example.com
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
token=mF_9.B5f-4.1JqM&token_type_hint=access_token
<span class="grey">Richer Standards Track [Page 5]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-6" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
<span class="h3"><a class="selflink" id="section-2.2" href="#section-2.2">2.2</a>. Introspection Response</span>
The server responds with a JSON object [<a href="./rfc7159" title=""The JavaScript Object Notation (JSON) Data Interchange Format"">RFC7159</a>] in "application/
json" format with the following top-level members.
active
REQUIRED. Boolean indicator of whether or not the presented token
is currently active. The specifics of a token's "active" state
will vary depending on the implementation of the authorization
server and the information it keeps about its tokens, but a "true"
value return for the "active" property will generally indicate
that a given token has been issued by this authorization server,
has not been revoked by the resource owner, and is within its
given time window of validity (e.g., after its issuance time and
before its expiration time). See <a href="#section-4">Section 4</a> for information on
implementation of such checks.
scope
OPTIONAL. A JSON string containing a space-separated list of
scopes associated with this token, in the format described in
<a href="#section-3.3">Section 3.3</a> of OAuth 2.0 [<a href="./rfc6749" title=""The OAuth 2.0 Authorization Framework"">RFC6749</a>].
client_id
OPTIONAL. Client identifier for the OAuth 2.0 client that
requested this token.
username
OPTIONAL. Human-readable identifier for the resource owner who
authorized this token.
token_type
OPTIONAL. Type of the token as defined in <a href="#section-5.1">Section 5.1</a> of OAuth
2.0 [<a href="./rfc6749" title=""The OAuth 2.0 Authorization Framework"">RFC6749</a>].
exp
OPTIONAL. Integer timestamp, measured in the number of seconds
since January 1 1970 UTC, indicating when this token will expire,
as defined in JWT [<a href="./rfc7519" title=""JSON Web Token (JWT)"">RFC7519</a>].
iat
OPTIONAL. Integer timestamp, measured in the number of seconds
since January 1 1970 UTC, indicating when this token was
originally issued, as defined in JWT [<a href="./rfc7519" title=""JSON Web Token (JWT)"">RFC7519</a>].
nbf
OPTIONAL. Integer timestamp, measured in the number of seconds
since January 1 1970 UTC, indicating when this token is not to be
used before, as defined in JWT [<a href="./rfc7519" title=""JSON Web Token (JWT)"">RFC7519</a>].
<span class="grey">Richer Standards Track [Page 6]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-7" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
sub
OPTIONAL. Subject of the token, as defined in JWT [<a href="./rfc7519" title=""JSON Web Token (JWT)"">RFC7519</a>].
Usually a machine-readable identifier of the resource owner who
authorized this token.
aud
OPTIONAL. Service-specific string identifier or list of string
identifiers representing the intended audience for this token, as
defined in JWT [<a href="./rfc7519" title=""JSON Web Token (JWT)"">RFC7519</a>].
iss
OPTIONAL. String representing the issuer of this token, as
defined in JWT [<a href="./rfc7519" title=""JSON Web Token (JWT)"">RFC7519</a>].
jti
OPTIONAL. String identifier for the token, as defined in JWT
[<a href="./rfc7519" title=""JSON Web Token (JWT)"">RFC7519</a>].
Specific implementations MAY extend this structure with their own
service-specific response names as top-level members of this JSON
object. Response names intended to be used across domains MUST be
registered in the "OAuth Token Introspection Response" registry
defined in <a href="#section-3.1">Section 3.1</a>.
The authorization server MAY respond differently to different
protected resources making the same request. For instance, an
authorization server MAY limit which scopes from a given token are
returned for each protected resource to prevent a protected resource
from learning more about the larger network than is necessary for its
operation.
The response MAY be cached by the protected resource to improve
performance and reduce load on the introspection endpoint, but at the
cost of liveness of the information used by the protected resource to
make authorization decisions. See <a href="#section-4">Section 4</a> for more information
regarding the trade off when the response is cached.
<span class="grey">Richer Standards Track [Page 7]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-8" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
For example, the following response contains a set of information
about an active token:
The following is a non-normative example response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": true,
"client_id": "l238j323ds-23ij4",
"username": "jdoe",
"scope": "read write dolphin",
"sub": "Z5O3upPC88QrAjx00dis",
"aud": "https://protected.example.net/resource",
"iss": "https://server.example.com/",
"exp": 1419356238,
"iat": 1419350238,
"extension_field": "twenty-seven"
}
If the introspection call is properly authorized but the token is not
active, does not exist on this server, or the protected resource is
not allowed to introspect this particular token, then the
authorization server MUST return an introspection response with the
"active" field set to "false". Note that to avoid disclosing too
much of the authorization server's state to a third party, the
authorization server SHOULD NOT include any additional information
about an inactive token, including why the token is inactive.
The following is a non-normative example response for a token that
has been revoked or is otherwise invalid:
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": false
}
<span class="h3"><a class="selflink" id="section-2.3" href="#section-2.3">2.3</a>. Error Response</span>
If the protected resource uses OAuth 2.0 client credentials to
authenticate to the introspection endpoint and its credentials are
invalid, the authorization server responds with an HTTP 401
(Unauthorized) as described in <a href="#section-5.2">Section 5.2</a> of OAuth 2.0 [<a href="./rfc6749" title=""The OAuth 2.0 Authorization Framework"">RFC6749</a>].
<span class="grey">Richer Standards Track [Page 8]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-9" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
If the protected resource uses an OAuth 2.0 bearer token to authorize
its call to the introspection endpoint and the token used for
authorization does not contain sufficient privileges or is otherwise
invalid for this request, the authorization server responds with an
HTTP 401 code as described in <a href="#section-3">Section 3</a> of OAuth 2.0 Bearer Token
Usage [<a href="./rfc6750" title=""The OAuth 2.0 Authorization Framework: Bearer Token Usage"">RFC6750</a>].
Note that a properly formed and authorized query for an inactive or
otherwise invalid token (or a token the protected resource is not
allowed to know about) is not considered an error response by this
specification. In these cases, the authorization server MUST instead
respond with an introspection response with the "active" field set to
"false" as described in <a href="#section-2.2">Section 2.2</a>.
<span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. IANA Considerations</span>
<span class="h3"><a class="selflink" id="section-3.1" href="#section-3.1">3.1</a>. OAuth Token Introspection Response Registry</span>
This specification establishes the "OAuth Token Introspection
Response" registry.
OAuth registration client metadata names and descriptions are
registered by Specification Required [<a href="./rfc5226" title="">RFC5226</a>] after a two-week
review period on the oauth-ext-review@ietf.org mailing list, on the
advice of one or more Designated Experts. However, to allow for the
allocation of names prior to publication, the Designated Expert(s)
may approve registration once they are satisfied that such a
specification will be published.
Registration requests sent to the mailing list for review should use
an appropriate subject (e.g., "Request to register OAuth Token
Introspection Response name: example").
Within the review period, the Designated Expert(s) will either
approve or deny the registration request, communicating this decision
to the review list and IANA. Denials should include an explanation
and, if applicable, suggestions as to how to make the request
successful.
IANA must only accept registry updates from the Designated Expert(s)
and should direct all requests for registration to the review mailing
list.
<span class="grey">Richer Standards Track [Page 9]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-10" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
<span class="h4"><a class="selflink" id="section-3.1.1" href="#section-3.1.1">3.1.1</a>. Registration Template</span>
Name:
The name requested (e.g., "example"). This name is case
sensitive. Names that match other registered names in a case
insensitive manner SHOULD NOT be accepted. Names that match
claims registered in the "JSON Web Token Claims" registry
established by [<a href="./rfc7519" title=""JSON Web Token (JWT)"">RFC7519</a>] SHOULD have comparable definitions and
semantics.
Description:
Brief description of the metadata value (e.g., "Example
description").
Change controller:
For Standards Track RFCs, state "IESG". For other documents, give
the name of the responsible party. Other details (e.g., postal
address, email address, home page URI) may also be included.
Specification document(s):
Reference to the document(s) that specify the token endpoint
authorization method, preferably including a URI that can be used
to retrieve a copy of the document(s). An indication of the
relevant sections may also be included but is not required.
<span class="h4"><a class="selflink" id="section-3.1.2" href="#section-3.1.2">3.1.2</a>. Initial Registry Contents</span>
The initial contents of the "OAuth Token Introspection Response"
registry are as follows:
o Name: "active"
o Description: Token active status
o Change Controller: IESG
o Specification Document(s): <a href="./rfc7662#section-2.2">Section 2.2 of RFC 7662</a> (this
document).
o Name: "username"
o Description: User identifier of the resource owner
o Change Controller: IESG
o Specification Document(s): <a href="./rfc7662#section-2.2">Section 2.2 of RFC 7662</a> (this
document).
o Name: "client_id"
o Description: Client identifier of the client
o Change Controller: IESG
o Specification Document(s): <a href="./rfc7662#section-2.2">Section 2.2 of RFC 7662</a> (this
document).
<span class="grey">Richer Standards Track [Page 10]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-11" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
o Name: "scope"
o Description: Authorized scopes of the token
o Change Controller: IESG
o Specification Document(s): <a href="./rfc7662#section-2.2">Section 2.2 of RFC 7662</a> (this
document).
o Name: "token_type"
o Description: Type of the token
o Change Controller: IESG
o Specification Document(s): <a href="./rfc7662#section-2.2">Section 2.2 of RFC 7662</a> (this
document).
o Name: "exp"
o Description: Expiration timestamp of the token
o Change Controller: IESG
o Specification Document(s): <a href="./rfc7662#section-2.2">Section 2.2 of RFC 7662</a> (this
document).
o Name: "iat"
o Description: Issuance timestamp of the token
o Change Controller: IESG
o Specification Document(s): <a href="./rfc7662#section-2.2">Section 2.2 of RFC 7662</a> (this
document).
o Name: "nbf"
o Description: Timestamp before which the token is not valid
o Change Controller: IESG
o Specification Document(s): <a href="./rfc7662#section-2.2">Section 2.2 of RFC 7662</a> (this
document).
o Name: "sub"
o Description: Subject of the token
o Change Controller: IESG
o Specification Document(s): <a href="./rfc7662#section-2.2">Section 2.2 of RFC 7662</a> (this
document).
o Name: "aud"
o Description: Audience of the token
o Change Controller: IESG
o Specification Document(s): <a href="./rfc7662#section-2.2">Section 2.2 of RFC 7662</a> (this
document).
o Name: "iss"
o Description: Issuer of the token
o Change Controller: IESG
o Specification Document(s): <a href="./rfc7662#section-2.2">Section 2.2 of RFC 7662</a> (this
document).
<span class="grey">Richer Standards Track [Page 11]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-12" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
o Name: "jti"
o Description: Unique identifier of the token
o Change Controller: IESG
o Specification Document(s): <a href="./rfc7662#section-2.2">Section 2.2 of RFC 7662</a> (this
document).
<span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. Security Considerations</span>
Since there are many different and valid ways to implement an OAuth
2.0 system, there are consequently many ways for an authorization
server to determine whether or not a token is currently "active".
However, since resource servers using token introspection rely on the
authorization server to determine the state of a token, the
authorization server MUST perform all applicable checks against a
token's state. For instance, these tests include the following:
o If the token can expire, the authorization server MUST determine
whether or not the token has expired.
o If the token can be issued before it is able to be used, the
authorization server MUST determine whether or not a token's valid
period has started yet.
o If the token can be revoked after it was issued, the authorization
server MUST determine whether or not such a revocation has taken
place.
o If the token has been signed, the authorization server MUST
validate the signature.
o If the token can be used only at certain resource servers, the
authorization server MUST determine whether or not the token can
be used at the resource server making the introspection call.
If an authorization server fails to perform any applicable check, the
resource server could make an erroneous security decision based on
that response. Note that not all of these checks will be applicable
to all OAuth 2.0 deployments and it is up to the authorization server
to determine which of these checks (and any other checks) apply.
If left unprotected and un-throttled, the introspection endpoint
could present a means for an attacker to poll a series of possible
token values, fishing for a valid token. To prevent this, the
authorization server MUST require authentication of protected
resources that need to access the introspection endpoint and SHOULD
require protected resources to be specifically authorized to call the
introspection endpoint. The specifics of such authentication
credentials are out of scope of this specification, but commonly
these credentials could take the form of any valid client
authentication mechanism used with the token endpoint, an OAuth 2.0
access token, or other HTTP authorization or authentication
mechanism. A single piece of software acting as both a client and a
<span class="grey">Richer Standards Track [Page 12]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-13" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
protected resource MAY reuse the same credentials between the token
endpoint and the introspection endpoint, though doing so potentially
conflates the activities of the client and protected resource
portions of the software and the authorization server MAY require
separate credentials for each mode.
Since the introspection endpoint takes in OAuth 2.0 tokens as
parameters and responds with information used to make authorization
decisions, the server MUST support Transport Layer Security (TLS) 1.2
[<a href="./rfc5246" title=""The Transport Layer Security (TLS) Protocol Version 1.2"">RFC5246</a>] and MAY support additional transport-layer mechanisms
meeting its security requirements. When using TLS, the client or
protected resource MUST perform a TLS/SSL server certificate check,
as specified in [<a href="./rfc6125" title=""Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)"">RFC6125</a>]. Implementation security considerations
can be found in Recommendations for Secure Use of TLS and DTLS
[<a href="#ref-BCP195" title=""Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)"">BCP195</a>].
To prevent the values of access tokens from leaking into server-side
logs via query parameters, an authorization server offering token
introspection MAY disallow the use of HTTP GET on the introspection
endpoint and instead require the HTTP POST method to be used at the
introspection endpoint.
To avoid disclosing the internal state of the authorization server,
an introspection response for an inactive token SHOULD NOT contain
any additional claims beyond the required "active" claim (with its
value set to "false").
Since a protected resource MAY cache the response of the
introspection endpoint, designers of an OAuth 2.0 system using this
protocol MUST consider the performance and security trade-offs
inherent in caching security information such as this. A less
aggressive cache with a short timeout will provide the protected
resource with more up-to-date information (due to it needing to query
the introspection endpoint more often) at the cost of increased
network traffic and load on the introspection endpoint. A more
aggressive cache with a longer duration will minimize network traffic
and load on the introspection endpoint, but at the risk of stale
information about the token. For example, the token may be revoked
while the protected resource is relying on the value of the cached
response to make authorization decisions. This creates a window
during which a revoked token could be used at the protected resource.
Consequently, an acceptable cache validity duration needs to be
carefully considered given the concerns and sensitivities of the
protected resource being accessed and the likelihood of a token being
revoked or invalidated in the interim period. Highly sensitive
environments can opt to disable caching entirely on the protected
resource to eliminate the risk of stale cached information entirely,
again at the cost of increased network traffic and server load. If
<span class="grey">Richer Standards Track [Page 13]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-14" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
the response contains the "exp" parameter (expiration), the response
MUST NOT be cached beyond the time indicated therein.
An authorization server offering token introspection must be able to
understand the token values being presented to it during this call.
The exact means by which this happens is an implementation detail and
is outside the scope of this specification. For unstructured tokens,
this could take the form of a simple server-side database query
against a data store containing the context information for the
token. For structured tokens, this could take the form of the server
parsing the token, validating its signature or other protection
mechanisms, and returning the information contained in the token back
to the protected resource (allowing the protected resource to be
unaware of the token's contents, much like the client). Note that
for tokens carrying encrypted information that is needed during the
introspection process, the authorization server must be able to
decrypt and validate the token to access this information. Also note
that in cases where the authorization server stores no information
about the token and has no means of accessing information about the
token by parsing the token itself, it cannot likely offer an
introspection service.
<span class="h2"><a class="selflink" id="section-5" href="#section-5">5</a>. Privacy Considerations</span>
The introspection response may contain privacy-sensitive information
such as user identifiers for resource owners. When this is the case,
measures MUST be taken to prevent disclosure of this information to
unintended parties. One method is to transmit user identifiers as
opaque service-specific strings, potentially returning different
identifiers to each protected resource.
If the protected resource sends additional information about the
client's request to the authorization server (such as the client's IP
address) using an extension of this specification, such information
could have additional privacy considerations that the extension
should detail. However, the nature and implications of such
extensions are outside the scope of this specification.
Omitting privacy-sensitive information from an introspection response
is the simplest way of minimizing privacy issues.
<span class="grey">Richer Standards Track [Page 14]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-15" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
<span class="h2"><a class="selflink" id="section-6" href="#section-6">6</a>. References</span>
<span class="h3"><a class="selflink" id="section-6.1" href="#section-6.1">6.1</a>. Normative References</span>
[<a id="ref-RFC2119">RFC2119</a>] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", <a href="https://www.rfc-editor.org/bcp/bcp14">BCP 14</a>, <a href="./rfc2119">RFC 2119</a>,
DOI 10.17487/RFC2119, March 1997,
<<a href="http://www.rfc-editor.org/info/rfc2119">http://www.rfc-editor.org/info/rfc2119</a>>.
[<a id="ref-RFC5226">RFC5226</a>] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", <a href="https://www.rfc-editor.org/bcp/bcp26">BCP 26</a>, <a href="./rfc5226">RFC 5226</a>,
DOI 10.17487/RFC5226, May 2008,
<<a href="http://www.rfc-editor.org/info/rfc5226">http://www.rfc-editor.org/info/rfc5226</a>>.
[<a id="ref-RFC5246">RFC5246</a>] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", <a href="./rfc5246">RFC 5246</a>,
DOI 10.17487/RFC5246, August 2008,
<<a href="http://www.rfc-editor.org/info/rfc5246">http://www.rfc-editor.org/info/rfc5246</a>>.
[<a id="ref-RFC6125">RFC6125</a>] Saint-Andre, P. and J. Hodges, "Representation and
Verification of Domain-Based Application Service Identity
within Internet Public Key Infrastructure Using X.509
(PKIX) Certificates in the Context of Transport Layer
Security (TLS)", <a href="./rfc6125">RFC 6125</a>, DOI 10.17487/RFC6125, March
2011, <<a href="http://www.rfc-editor.org/info/rfc6125">http://www.rfc-editor.org/info/rfc6125</a>>.
[<a id="ref-RFC6749">RFC6749</a>] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework",
<a href="./rfc6749">RFC 6749</a>, DOI 10.17487/RFC6749, October 2012,
<<a href="http://www.rfc-editor.org/info/rfc6749">http://www.rfc-editor.org/info/rfc6749</a>>.
[<a id="ref-RFC6750">RFC6750</a>] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", <a href="./rfc6750">RFC 6750</a>,
DOI 10.17487/RFC6750, October 2012,
<<a href="http://www.rfc-editor.org/info/rfc6750">http://www.rfc-editor.org/info/rfc6750</a>>.
[<a id="ref-RFC7009">RFC7009</a>] Lodderstedt, T., Ed., Dronia, S., and M. Scurtescu, "OAuth
2.0 Token Revocation", <a href="./rfc7009">RFC 7009</a>, DOI 10.17487/RFC7009,
August 2013, <<a href="http://www.rfc-editor.org/info/rfc7009">http://www.rfc-editor.org/info/rfc7009</a>>.
[<a id="ref-RFC7159">RFC7159</a>] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", <a href="./rfc7159">RFC 7159</a>, DOI 10.17487/RFC7159, March
2014, <<a href="http://www.rfc-editor.org/info/rfc7159">http://www.rfc-editor.org/info/rfc7159</a>>.
[<a id="ref-RFC7231">RFC7231</a>] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
Protocol (HTTP/1.1): Semantics and Content", <a href="./rfc7231">RFC 7231</a>,
DOI 10.17487/RFC7231, June 2014,
<<a href="http://www.rfc-editor.org/info/rfc7231">http://www.rfc-editor.org/info/rfc7231</a>>.
<span class="grey">Richer Standards Track [Page 15]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-16" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
[<a id="ref-RFC7519">RFC7519</a>] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", <a href="./rfc7519">RFC 7519</a>, DOI 10.17487/RFC7519, May 2015,
<<a href="http://www.rfc-editor.org/info/rfc7519">http://www.rfc-editor.org/info/rfc7519</a>>.
[<a id="ref-W3C.REC-html5-20141028">W3C.REC-html5-20141028</a>]
Hickson, I., Berjon, R., Faulkner, S., Leithead, T.,
Navara, E., 0'Connor, E., and S. Pfeiffer, "HTML5", World
Wide Web Consortium Recommendation
REC-html5-20141028, October 2014,
<<a href="http://www.w3.org/TR/2014/REC-html5-20141028">http://www.w3.org/TR/2014/REC-html5-20141028</a>>.
<span class="h3"><a class="selflink" id="section-6.2" href="#section-6.2">6.2</a>. Informative References</span>
[<a id="ref-BCP195">BCP195</a>] Sheffer, Y., Holz, R., and P. Saint-Andre,
"Recommendations for Secure Use of Transport Layer
Security (TLS) and Datagram Transport Layer Security
(DTLS)", <a href="https://www.rfc-editor.org/bcp/bcp195">BCP 195</a>, <a href="./rfc7525">RFC 7525</a>, May 2015,
<<a href="http://www.rfc-editor.org/info/bcp195">http://www.rfc-editor.org/info/bcp195</a>>.
<span class="grey">Richer Standards Track [Page 16]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-17" ></span>
<span class="grey"><a href="./rfc7662">RFC 7662</a> OAuth Introspection October 2015</span>
<span class="h2"><a class="selflink" id="appendix-A" href="#appendix-A">Appendix A</a>. Use with Proof-of-Possession Tokens</span>
With bearer tokens such as those defined by OAuth 2.0 Bearer Token
Usage [<a href="./rfc6750" title=""The OAuth 2.0 Authorization Framework: Bearer Token Usage"">RFC6750</a>], the protected resource will have in its possession
the entire secret portion of the token for submission to the
introspection service. However, for proof-of-possession style
tokens, the protected resource will have only a token identifier used
during the request, along with the cryptographic signature on the
request. To validate the signature on the request, the protected
resource could be able to submit the token identifier to the
authorization server's introspection endpoint to obtain the necessary
key information needed for that token. The details of this usage are
outside the scope of this specification and will be defined in an
extension to this specification in concert with the definition of
proof-of-possession tokens.
Acknowledgements
Thanks to the OAuth Working Group and the User Managed Access Working
Group for feedback and review of this document, and to the various
implementors of both the client and server components of this
specification. In particular, the author would like to thank Amanda
Anganes, John Bradley, Thomas Broyer, Brian Campbell, George
Fletcher, Paul Freemantle, Thomas Hardjono, Eve Maler, Josh Mandel,
Steve Moore, Mike Schwartz, Prabath Siriwardena, Sarah Squire, and
Hannes Tschofennig.
Author's Address
Justin Richer (editor)
Email: ietf@justin.richer.org
Richer Standards Track [Page 17]
</pre>
|
