forked from ietf-oauth-mtls/i-d
-
Notifications
You must be signed in to change notification settings - Fork 0
/
draft-ietf-oauth-mtls.xml
1220 lines (1137 loc) · 58.2 KB
/
draft-ietf-oauth-mtls.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
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
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="us-ascii"?>
<?xml-stylesheet type='text/xsl' href='http://xml2rfc.tools.ietf.org/authoring/rfc2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc="yes"?>
<?rfc tocompact="yes"?>
<?rfc tocdepth="4"?>
<?rfc tocindent="yes"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc comments="yes"?>
<?rfc inline="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-ietf-oauth-mtls-13" ipr="trust200902">
<front>
<title abbrev="OAuth Mutual TLS">OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens</title>
<author fullname="Brian Campbell" initials="B." surname="Campbell">
<organization>Ping Identity</organization>
<address><email>[email protected]</email></address>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization>Yubico</organization>
<address>
<email>[email protected]</email>
<uri>http://www.thread-safe.com/</uri>
</address>
</author>
<author fullname="Nat Sakimura" initials="N." surname="Sakimura">
<organization>Nomura Research Institute</organization>
<address>
<email>[email protected]</email>
<uri>https://nat.sakimura.org/</uri>
</address>
</author>
<author fullname="Torsten Lodderstedt" initials="T." surname="Lodderstedt">
<organization>YES.com AG</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<date />
<area>Security</area>
<workgroup>OAuth Working Group</workgroup>
<keyword>JSON Web Token</keyword>
<keyword>JWT</keyword>
<keyword>MTLS</keyword>
<keyword>Mutual TLS</keyword>
<keyword>proof-of-possession</keyword>
<keyword>proof-of-possession access token</keyword>
<keyword>key confirmed access token</keyword>
<keyword>certificate bound access token</keyword>
<keyword>client certificate</keyword>
<keyword>X.509 Client Certificate Authentication</keyword>
<keyword>key confirmation</keyword>
<keyword>confirmation method</keyword>
<keyword>holder-of-key</keyword>
<keyword>OAuth</keyword>
<abstract>
<t>
This document describes OAuth client authentication and certificate bound access tokens using
mutual Transport Layer Security (TLS) authentication with X.509 certificates.
OAuth clients are provided a mechanism for authentication to the authorization
server using mutual TLS, based on either self-signed certificates or public key infrastructure (PKI).
OAuth authorization servers are provided a mechanism for binding access tokens to a client's
mutual TLS certificate, and OAuth protected resources are provided a method for ensuring
that such an access token presented to it was issued to the client presenting the token.
</t>
</abstract>
</front>
<middle>
<section anchor="Introduction" title="Introduction">
<t>
This document describes OAuth client authentication and certificate bound access tokens using
mutual <xref target="RFC5246">TLS</xref> authentication with X.509 certificates.
OAuth clients are provided mechanisms for authentication to the authorization
server using mutual TLS.
OAuth authorization servers are provided a mechanism for binding access tokens to a client's
mutual TLS certificate, and OAuth protected resources are provided a method for ensuring
that such an access token presented to it was issued to the client presenting the token.
</t>
<t>
The OAuth 2.0 Authorization Framework <xref target="RFC6749"/>
defines a shared secret method of client authentication but also
allows for definition and use of additional client authentication mechanisms
when interacting directly with the authorization server.
This document describes an additional mechanism of client authentication utilizing
mutual TLS certificate-based authentication, which provides
better security characteristics than shared secrets.
While <xref target="RFC6749"/> documents client authentication for requests to the token endpoint,
extensions to OAuth 2.0 (such as <xref target="RFC7662">Introspection</xref> and
<xref target="RFC7009">Revocation</xref>) define endpoints that also utilize client authentication
and the mutual TLS methods defined herein are applicable to those endpoints as well.
</t>
<t>
Mutual TLS certificate bound access tokens ensure that
only the party in possession of the
private key corresponding to the certificate can utilize the token to
access the associated resources. Such a constraint is
sometimes referred to as key confirmation, proof-of-possession, or holder-of-key
and is unlike the case of the
bearer token described in <xref target="RFC6750"/>, where any party in
possession of the access token can use it to access the associated resources.
Binding an access token to the client's certificate
prevents the use of stolen access tokens or replay of access tokens
by unauthorized parties.
</t>
<t>
Mutual TLS certificate bound access tokens and mutual TLS client authentication
are distinct mechanisms, which are complementary but don't necessarily need to be deployed or used together.
</t>
<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="Terminology" title="Terminology">
<t>
Mutual TLS refers to the process whereby a client presents its X.509 certificate
and proves possession of the corresponding private key to a server when negotiating a TLS session.
In <xref target="RFC5246">TLS 1.2</xref> this requires the client to send
Client Certificate and Certificate Verify messages during the TLS handshake and
for the server to verify these messages.
</t>
</section>
</section>
<section anchor="mtlsca" title="Mutual TLS for OAuth Client Authentication">
<t>
This section defines, as an extension of
<xref target="RFC6749">OAuth 2.0, Section 2.3</xref>, two distinct methods of using
mutual TLS X.509 client certificates as client credentials.
The requirement of mutual TLS for client authentication is determined by the authorization server
based on policy or configuration for the given client (regardless of whether the client was dynamically
registered, statically configured, or otherwise established).
</t>
<t>
In order to utilize TLS for OAuth client authentication, the TLS
connection between the client and the authorization server MUST have been established or reestablished
with mutual TLS X.509 certificate authentication
(i.e. the Client Certificate and Certificate Verify messages are sent during the TLS Handshake
<xref target="RFC5246"/>).
</t>
<t>
For all requests to the authorization server utilizing mutual TLS client authentication,
the client MUST include the <spanx style='verb'>client_id</spanx> parameter,
described in <xref target="RFC6749">OAuth 2.0, Section 2.2</xref>.
The presence of the <spanx style='verb'>client_id</spanx>
parameter enables the authorization server to easily identify the
client independently from the content of the certificate. The authorization server
can locate the client configuration using the client identifier and check the certificate
presented in the TLS Handshake against the expected credentials for that client.
The authorization server MUST enforce the
binding of a certificate to a specific client as described in either <xref target="pki_method"/> or
<xref target="self_signed_method"/> below.
</t>
<section anchor="pki_method" title="PKI Mutual TLS OAuth Client Authentication Method">
<t>
The PKI (public key infrastructure) method of mutual TLS OAuth client authentication uses
a subject distinguished name (DN) and validated certificate chain to identify
the client. The TLS handshake is utilized to validate the client's possession
of the private key corresponding to the public key in the certificate and to
validate the corresponding certificate chain. The client is successfully authenticated
if the subject information in the certificate matches the expected DN configured or
registered for that particular client
(note that a predictable treatment of DN values, such as the distinguishedNameMatch
rule from <xref target="RFC4517"/>, is needed in comparing the
certificate's subject DN to the client's registered DN).
If and how to check a certificate's revocation status is a deployment decision at the discretion of the authorization server.
The PKI method facilitates the way X.509 certificates are traditionally being used
for authentication. It also allows the client to rotate its X.509 certificates
without the need to modify its respective authentication data at the authorization
server by obtaining a new certificate with the same subject DN from a trusted certificate authority (CA).
</t>
<section anchor="metadata_auth_value_pki" title="PKI Authentication Method Metadata Value">
<t>
For the PKI method of mutual TLS client authentication, this specification
defines and registers the following authentication method metadata
value into the "OAuth Token Endpoint Authentication Methods" registry
<xref target="IANA.OAuth.Parameters"/>.
</t>
<t>
<list style="hanging">
<t hangText="tls_client_auth">
<vspace/>
Indicates that client authentication to the authorization server will occur with
mutual TLS utilizing the PKI method of associating a certificate to a client.
</t>
</list>
</t>
</section>
<section anchor="client_metadata_pki" title="Client Registration Metadata">
<t>
The following metadata
parameter is introduced for the
<xref target="RFC7591">OAuth 2.0 Dynamic Client Registration Protocol</xref> in support of
the PKI method of binding a certificate to a client:
<list style="hanging">
<t hangText="tls_client_auth_subject_dn"><vspace/>
An <xref target="RFC4514"/> string representation of the expected subject distinguished
name of the certificate, which the OAuth client will use in mutual TLS authentication.
</t>
</list>
</t>
</section>
</section>
<section anchor="self_signed_method" title="Self-Signed Certificate Mutual TLS OAuth Client Authentication Method">
<t>
This method of mutual TLS OAuth client authentication
is intended to support client authentication using self-signed certificates.
As pre-requisite, the client registers an X.509 certificate or a trusted source
for its X.509 certificates (such as the <spanx style="verb">jwks_uri</spanx> defined in <xref target="RFC7591"/>
that references a <xref target="RFC7517">JSON Web Key</xref> Set
containing the client's certificates and public keys) with
the authorization server. During authentication,
TLS is utilized to validate the client's possession of the private key
corresponding to the public key presented within the certificate in the respective TLS handshake. In
contrast to the PKI method, the client's certificate chain is not validated by the server in this case.
The client is successfully authenticated if the subject public key info of the
certificate matches the subject public key info of one of the certificates
configured or registered for that particular client.
The Self-Signed Certificate method allows to use mutual TLS to authenticate clients without
the need to maintain a PKI. When used in conjunction with a <spanx style="verb">jwks_uri</spanx> for the
client, it also allows the client to rotate its X.509 certificates without the
need to change its respective authentication data directly with the authorization server.
</t>
<section anchor="metadata_auth_value_self_signed" title="Self-Signed Certificate Authentication Method Metadata Value">
<t>
For the Self-Signed Certificate method of mutual TLS client authentication, this specification
defines and registers the following authentication method metadata
value into the "OAuth Token Endpoint Authentication Methods" registry
<xref target="IANA.OAuth.Parameters"/>.
</t>
<t>
<list style="hanging">
<t hangText="self_signed_tls_client_auth">
<vspace/>
Indicates that client authentication to the authorization server will occur using
mutual TLS with the client utilizing a self-signed certificate.
</t>
</list>
</t>
</section>
<section anchor="client_metadata_self_signed" title="Client Registration Metadata">
<t>
For the Self-Signed Certificate method of binding a certificate to a client using mutual
TLS client authentication, the existing
<spanx style="verb">jwks_uri</spanx> or <spanx style="verb">jwks</spanx>
metadata parameters from <xref target="RFC7591"/> are used to convey the client's
certificates and public keys, where the X.509
certificates are represented using the <xref target="RFC7517">JSON Web Key (JWK)</xref>
<spanx style="verb">x5c</spanx> parameter.
Note that Sec 4.7 of <xref target="RFC7517"/> requires that the key
in the first certificate of the <spanx style="verb">x5c</spanx> parameter must match the public
key represented by other members of the JWK (e.g. "n" and "e" for RSA,
"x" and "y" for EC).
</t>
</section>
</section>
</section>
<section anchor="CertificateBoundAccessTokens" title="Mutual TLS Client Certificate Bound Access Tokens">
<t>
When mutual TLS is used by the client on the connection to the token endpoint,
the authorization server is able to bind the issued access token to the client certificate.
Such a binding is accomplished by associating the certificate with the token in
a way that can be accessed by the protected resource, such as embedding the certificate
hash in the issued access token directly, using the syntax described in <xref target="x5t"/>,
or through token introspection as described in <xref target="introspect"/>.
Binding the access token to the client certificate in that fashion has the benefit of
decoupling that binding from the client's authentication with the
authorization server, which enables mutual TLS during protected resource access to
serve purely as a proof-of-possession mechanism.
Other methods of associating a certificate with an access token are possible,
per agreement by the authorization server and the protected resource, but are
beyond the scope of this specification.
</t>
<t>
The client makes protected resource requests as described in <xref target="RFC6750"/>,
however, those requests MUST be made over a mutually authenticated TLS connection
using the same certificate that was used for mutual TLS at the token endpoint.
</t>
<t>
The protected resource MUST obtain the client certificate
used for mutual TLS authentication
and MUST verify that the certificate matches the
certificate associated with the access token. If they do not match,
the resource access attempt MUST be rejected with an error per <xref target="RFC6750"/>
using an HTTP 401 status code and the <spanx style="verb">invalid_token</spanx> error code.
</t>
<t>
Metadata to convey server and client capabilities for mutual TLS client certificate bound access tokens
is defined in <xref target="server_metadata_at"/> and <xref target="client_metadata_at"/> respectively.
</t>
<section anchor="x5t" title="X.509 Certificate Thumbprint Confirmation Method for JWT">
<t>
When access tokens are represented as JSON Web Tokens (JWT)<xref target="RFC7519"/>,
the certificate hash information SHOULD be represented using
the <spanx style="verb">x5t#S256</spanx> confirmation method member defined herein.
</t>
<t>
To represent the hash of a certificate in a JWT,
this specification defines the new <xref target="RFC7800">JWT Confirmation Method</xref>
member <spanx style="verb">x5t#S256</spanx> for the X.509 Certificate SHA-256 Thumbprint.
The value of the <spanx style="verb">x5t#S256</spanx> member is a base64url-encoded <xref target="RFC4648"/>
SHA-256 <xref target="SHS"/> hash (a.k.a. thumbprint, fingerprint or digest) of the DER encoding of the X.509 certificate
<xref target="RFC5280"/>. The base64url-encoded value MUST omit all trailing pad '=' characters
and MUST NOT include any line breaks, whitespace, or other additional characters.
</t>
<t>
The following is an example of a JWT payload containing an <spanx style="verb">x5t#S256</spanx> certificate thumbprint
confirmation method.
</t>
<figure anchor="eg_x5ts256jwt" title="Example JWT Claims Set with an X.509 Certificate Thumbprint Confirmation Method">
<artwork><![CDATA[
{
"iss": "https://server.example.com",
"sub": "[email protected]",
"exp": 1493726400,
"nbf": 1493722800,
"cnf":{
"x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
}
}]]>
</artwork>
</figure>
<t>
If, in the future, certificate thumbprints need to be computed using
hash functions other than SHA-256, it is suggested that additional
related JWT confirmation methods members be defined for that purpose.
For example, a new <spanx style="verb">x5t#S512</spanx> (X.509 Certificate Thumbprint
using SHA-512) confirmation method member could be defined by registering it in
the the IANA "JWT Confirmation Methods" registry
<xref target="IANA.JWT.Claims"/>
for JWT <spanx style="verb">cnf</spanx> member values
established by <xref target="RFC7800"/>.
</t>
</section>
<section anchor="introspect" title="Confirmation Method for Token Introspection">
<t>
<xref target="RFC7662">OAuth 2.0 Token Introspection</xref> defines a
method for a protected resource to query
an authorization server about the active state of an
access token as well as to determine meta-information about the token.
</t>
<t>
For a mutual TLS client certificate bound access token, the hash of the
certificate to which the token is bound
is conveyed to the protected resource as meta-information
in a token introspection response. The hash is conveyed using the same structure as the
certificate SHA-256 thumbprint confirmation method, described in
<xref target="x5t"/>, as a top-level member of the introspection response JSON.
The protected resource compares
that certificate hash to a hash of the client certificate used for
mutual TLS authentication
and rejects the request, if they do not match.
</t>
<t>
<xref target="RFC7800">Proof-of-Possession Key Semantics for JSON Web Tokens</xref> defined the
<spanx style="verb">cnf</spanx> (confirmation) claim, which enables
confirmation key information to be carried in a JWT.
However, the same proof-of-possession semantics are also useful for introspected access tokens
whereby the protected resource obtains the confirmation key data as meta-information
of a token introspection response and uses that information in verifying proof-of-possession.
Therefore this specification defines and registers proof-of-possession semantics for
<xref target="RFC7662">OAuth 2.0 Token Introspection</xref> using the <spanx style="verb">cnf</spanx>
structure.
When included as a top-level member of an OAuth token introspection response, <spanx style="verb">cnf</spanx>
has the same semantics and format as the claim of the same name defined in <xref target="RFC7800"/>.
While this specification only explicitly uses the <spanx style="verb">x5t#S256</spanx>
confirmation method member, it needed to define and register the higher level <spanx style="verb">cnf</spanx>
structure as an introspection response member in order to define and use the more specific
certificate thumbprint confirmation method.
</t>
<t>
The following is an example of an introspection response for an active token with
an <spanx style="verb">x5t#S256</spanx> certificate thumbprint
confirmation method.
</t>
<figure anchor="eg_x5ts256intro" title="Example Introspection Response for a Certificate Bound Access Token">
<artwork><![CDATA[
HTTP/1.1 200 OK
Content-Type: application/json
{
"active": true,
"iss": "https://server.example.com",
"sub": "[email protected]",
"exp": 1493726400,
"nbf": 1493722800,
"cnf":{
"x5t#S256": "bwcK0esc3ACC3DB2Y5_lESsXE8o9ltc05O89jdN-dg2"
}
}]]>
</artwork>
</figure>
</section>
<section anchor="server_metadata_at" title="Authorization Server Metadata">
<t>This document introduces the following new authorization server
metadata parameter to signal the server's capability to issue certificate
bound access tokens:
<list style="hanging">
<t hangText="tls_client_certificate_bound_access_tokens"><vspace/>
OPTIONAL. Boolean value indicating server support for
mutual TLS client certificate bound access tokens. If omitted, the
default value is <spanx style="verb">false</spanx>.
</t>
</list>
</t>
</section>
<section anchor="client_metadata_at" title="Client Registration Metadata">
<t>The following new client
metadata parameter is introduced to convey the client's intention to use certificate
bound access tokens:
<list style="hanging">
<t hangText="tls_client_certificate_bound_access_tokens"><vspace/>
OPTIONAL. Boolean value used to indicate the client's intention
to use mutual TLS client certificate bound access tokens.
If omitted, the default value is <spanx style="verb">false</spanx>.
</t>
</list>
</t>
</section>
</section>
<section title="Mutual TLS Client Certificate Bound Refresh Tokens">
<t>When mutual TLS is used by the client on the connection to the token endpoint and
the authorization server issues refresh tokens, it MAY also bind this refresh token
to the respective certificate. This is especially useful for public clients
since it allows for refresh token replay detection without the need
to rotate the refresh tokens.</t>
<t>The implementation details of the binding are at the discretion of the authorization
server. This specification defines metadata parameters allowing the server to
announce support for refresh token binding and the client to request this feature.</t>
<section anchor="server_metadata_rt" title="Authorization Server Metadata">
<t>This document introduces the following new authorization server
metadata parameter to signal the server's capability to issue certificate
bound refresh tokens:
<list style="hanging">
<t hangText="tls_client_certificate_bound_refresh_tokens"><vspace/>
OPTIONAL. Boolean value indicating server support for
mutual TLS client certificate bound refresh tokens. If omitted, the
default value is <spanx style="verb">false</spanx>.
</t>
</list>
</t>
</section>
<section anchor="client_metadata_rt" title="Client Registration Metadata">
<t>The following new client
metadata parameter is introduced to convey the client's intention to use certificate
bound refresh tokens:
<list style="hanging">
<t hangText="tls_client_certificate_bound_refresh_tokens"><vspace/>
OPTIONAL. Boolean value used to indicate the client's intention
to use mutual TLS client certificate bound refresh tokens.
If omitted, the default value is <spanx style="verb">false</spanx>.
</t>
</list>
</t>
</section>
</section>
<section anchor="Impl" title="Implementation Considerations">
<section anchor="ImplAS" title="Authorization Server">
<t>The authorization server needs to set up its TLS configuration appropriately
for the binding methods it supports.</t>
<t>If the authorization server wants to support mutual TLS client authentication
and other client authentication methods in parallel, it should make mutual TLS
optional.</t>
<t>If the authorization server supports the Self-Signed Certificate method, it
should configure the TLS stack in a way that it does not verify whether the
certificate presented by the client during the handshake is signed by a trusted CA
certificate.</t>
<t>The authorization server may also consider hosting the token endpoint,
and other endpoints requiring client authentication, on
a separate host name or port in order to prevent unintended impact on the TLS behavior of
its other endpoints, e.g. the authorization endpoint.</t>
</section>
<section anchor="ImplRS" title="Resource Server">
<t>
Since the resource server relies on the authorization server to
perform client authentication, there is no need for the resource server to validate
the trust chain of the client's certificate in any of the methods
defined in this document.
Mutual TLS is used only as a proof-of-possession mechanism during protected
resource access.
The resource server should therefore configure the TLS stack
in a way that it does not verify whether the certificate presented by the client
during the handshake is signed by a trusted CA certificate.
</t>
</section>
<section anchor="ImplPubClient" title="Certificate Bound Access Tokens Without Client Authentication">
<t>
Mutual TLS OAuth client authentication and mutual TLS client certificate bound access tokens
can be used independently of each other.
Use of certificate bound access tokens without mutual TLS OAuth client authentication, for example,
is possible in support of binding access tokens to a TLS client certificate for public clients or clients
utilizing other methods of authentication to the authorization server.
The authorization server would configure the TLS stack in the same manner as for the Self-Signed Certificate method
such that it does not verify that the certificate presented by the client during the handshake is
signed by a trusted CA. Individual instances of a client would create a self-signed
certificate for mutual TLS with both the authorization server and resource server. The authorization
server would not use the mutual TLS certificate to authenticate the client at the OAuth layer
but would bind the issued access token
to that certificate, which the client has proven possession of the corresponding private key.
The access token is then bound to the certificate and can only be used by the client
possessing the certificate and corresponding private key and utilizing them to negotiate mutual TLS on
connections to the resource server.
</t>
</section>
<section anchor="ImplExp" title="Certificate Bound Access Tokens">
<t>
As described in <xref target="CertificateBoundAccessTokens"/>,
an access token is bound to a specific client certificate, which means that
the same certificate must be used for mutual TLS on protected resource access.
It also implies that access tokens are invalidated when a client updates the certificate,
which can be handled similar to expired access tokens where the client
requests a new access token (typically with a refresh token) and retries the protected resource
request.
</t>
</section>
<section anchor="ImplImplicit" title="Implicit Grant Unsupported">
<t>
This document describes binding an access token to the
client certificate presented on the TLS connection from the client to the
authorization server's token endpoint,
however, such binding of access tokens issued directly from the authorization
endpoint via the implicit grant flow is explicitly out of scope.
End users interact directly with the authorization endpoint using a web browser
and the use of client certificates in user's browsers bring operational and
usability issues, which make it undesirable to support certificate bound access
tokens issued in the implicit grant flow. Implementations wanting to employ
certificate bound access tokens should utilize grant types
that involve the client making an access token request directly to the token endpoint
(e.g. the authorization code and refresh token grant types).
</t>
</section>
<section anchor="TTRP" title="TLS Termination">
<t>
An authorization server or resource server MAY choose to terminate TLS connections at a load balancer,
reverse proxy, or other network intermediary. How the client certificate metadata is securely
communicated between the intermediary and the application server in this case is out of scope of this specification.
</t>
</section>
</section>
<section anchor="Security" title="Security Considerations">
<section anchor="TLSV" title="TLS Versions and Best Practices">
<t>
<xref target="RFC5246">TLS 1.2</xref> is cited in this document because,
at the time of writing, it is the latest version that is widely deployed.
However, this document is applicable with other TLS versions supporting
certificate-based client authentication, including the relatively recently published <xref target="RFC8446">TLS 1.3</xref>.
Implementation security considerations for TLS, including version recommendations,
can be found in
<xref target="BCP195">Recommendations for Secure Use of Transport Layer Security (TLS)
and Datagram Transport Layer Security (DTLS)</xref>.
</t>
</section>
<section anchor="certspoofing" title="X.509 Certificate Spoofing">
<t>
If the PKI method of client authentication is used, an attacker could try to impersonate a client using
a certificate with the same subject DN but issued by a different CA, which the authorization server trusts.
To cope with that threat, the authorization server should only accept as trust anchors
a limited number of CAs whose certificate issuance policy meets its security requirements.
There is an assumption then that the client and server agree on the set
of trust anchors that the server uses to create and validate the
certificate chain. Without this assumption the use of a Subject DN
to identify the client certificate would open the server up to
certificate spoofing attacks.
</t>
</section>
<section title="X.509 Certificate Parsing and Validation Complexity">
<t>
Parsing and validation of X.509 certificates and certificate chains is complex and implementation
mistakes have previously exposed security vulnerabilities.
Complexities of validation include (but are not limited to)
<xref target="X509Pitfalls"/> <xref target="DangerousCode"/> <xref target="RFC5280"/>:
</t>
<t>
<list style="symbols">
<t>checking of Basic Constraints, basic and extended Key Usage constraints, validity periods, and critical extensions;</t>
<t>handling of null-terminator bytes and non-canonical string representations in subject names;</t>
<t>handling of wildcard patterns in subject names;</t>
<t>recursive verification of certificate chains and checking certificate revocation.</t>
</list>
</t><t>
For these reasons, implementors SHOULD use an established and well-tested X.509 library
(such as one used by an established TLS library) for validation of X.509 certificate chains
and SHOULD NOT attempt to write their own X.509 certificate validation procedures.
</t>
</section>
</section>
<section anchor="IANA" title="IANA Considerations">
<section anchor="cnfIANA" title="JWT Confirmation Methods Registration">
<t>
This specification requests registration of the following value
in the IANA "JWT Confirmation Methods" registry
<xref target="IANA.JWT.Claims"/>
for JWT <spanx style="verb">cnf</spanx> member values
established by <xref target="RFC7800"/>.
</t>
<t>
<?rfc subcompact="yes"?>
<list style='symbols'>
<t>Confirmation Method Value: <spanx style="verb">x5t#S256</spanx></t>
<t>Confirmation Method Description: X.509 Certificate SHA-256 Thumbprint</t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="x5t"/> of [[ this specification ]]</t>
</list>
<?rfc subcompact="no"?>
</t>
</section>
<section anchor="ietf-oauth-discoveryIANA" title="OAuth Authorization Server Metadata Registration">
<t>
This specification requests registration of the following value
in the IANA "OAuth Authorization Server Metadata" registry
<xref target="IANA.OAuth.Parameters"/> established by <xref target="RFC8414"/>.
</t>
<t>
<?rfc subcompact="yes"?>
<list style='symbols'>
<t>Metadata Name: <spanx style="verb">tls_client_certificate_bound_access_tokens</spanx></t>
<t>Metadata Description: Indicates authorization server support for mutual TLS client certificate bound
access tokens.</t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="server_metadata_at"/> of [[ this specification ]]</t>
</list>
<?rfc subcompact="no"?>
</t>
<t>
<?rfc subcompact="yes"?>
<list style='symbols'>
<t>Metadata Name: <spanx style="verb">tls_client_certificate_bound_refresh_tokens</spanx></t>
<t>Metadata Description: Indicates authorization server support for mutual TLS client certificate bound refresh tokens.</t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="server_metadata_rt"/> of [[ this specification ]]</t>
</list>
<?rfc subcompact="no"?>
</t>
</section>
<section anchor="tls_client_authIANA" title="Token Endpoint Authentication Method Registration">
<t>
This specification requests registration of the following value
in the IANA "OAuth Token Endpoint Authentication Methods" registry
<xref target="IANA.OAuth.Parameters"/> established by <xref target="RFC7591"/>.
</t>
<t>
<?rfc subcompact="yes"?>
<list style='symbols'>
<t>Token Endpoint Authentication Method Name: <spanx style="verb">tls_client_auth</spanx></t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="metadata_auth_value_pki"/> of [[ this specification ]]</t>
</list>
<?rfc subcompact="no"?>
</t>
<t>
<?rfc subcompact="yes"?>
<list style='symbols'>
<t>Token Endpoint Authentication Method Name: <spanx style="verb">self_signed_tls_client_auth</spanx></t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="metadata_auth_value_self_signed"/> of [[ this specification ]]</t>
</list>
<?rfc subcompact="no"?>
</t>
</section>
<section anchor="intorspectIANA" title="OAuth Token Introspection Response Registration">
<t>
This specification requests registration of the following value
in the IANA "OAuth Token Introspection Response" registry
<xref target="IANA.OAuth.Parameters"/>
established by <xref target="RFC7662"/>.
</t>
<t>
<?rfc subcompact="yes"?>
<list style='symbols'>
<t>Claim Name: <spanx style="verb">cnf</spanx></t>
<t>Claim Description: Confirmation</t>
<t>Change Controller: IESG</t>
<t>Specification Document(s): <xref target="introspect"/> of [[ this specification ]]</t>
</list>
<?rfc subcompact="no"?>
</t>
</section>
<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>
<t>
<?rfc subcompact="yes"?>
<list style="symbols">
<t>
Client Metadata Name: <spanx style="verb">tls_client_certificate_bound_access_tokens</spanx>
</t>
<t>
Client Metadata Description:
Indicates the client's intention to use mutual TLS client certificate bound
access tokens.
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): <xref target="client_metadata_at"/> of [[ this specification ]]
</t>
</list>
</t>
<t>
<?rfc subcompact="yes"?>
<list style="symbols">
<t>
Client Metadata Name: <spanx style="verb">tls_client_certificate_bound_refresh_tokens</spanx>
</t>
<t>
Client Metadata Description:
Indicates the client's intention to use mutual TLS client certificate bound
refresh tokens.
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): <xref target="client_metadata_rt"/> of [[ this specification ]]
</t>
</list>
</t>
<t>
<list style="symbols">
<t>
Client Metadata Name: <spanx style="verb">tls_client_auth_subject_dn</spanx>
</t>
<t>
Client Metadata Description:
String value specifying the expected subject distinguished name of the
client certificate.
</t>
<t>
Change Controller: IESG
</t>
<t>
Specification Document(s): <xref target="client_metadata_pki"/> of [[ this specification ]]
</t>
</list>
<?rfc subcompact="no"?>
</t>
</section>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include='reference.RFC.2119'?>
<?rfc include='reference.RFC.4514'?> <!-- LDAP: String Representation of Distinguished Names -->
<?rfc include='reference.RFC.4648'?> <!-- base64 -->
<?rfc include='reference.RFC.5246'?> <!-- TLS 1.2 -->
<?rfc include='reference.RFC.5280'?> <!-- X.509 Public Key Infrastructure Certificate ... -->
<?rfc include='reference.RFC.6749'?> <!-- OAuth 2.0 Authorization Framework -->
<?rfc include='reference.RFC.6750'?> <!-- OAuth 2.0 Authorization Framework: Bearer Token Usage -->
<?rfc include='reference.RFC.7800'?>
<reference anchor="BCP195" target="http://www.rfc-editor.org/info/bcp195">
<front>
<title>Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)</title>
<author initials="Y." surname="Sheffer" fullname="Y. Sheffer">
<organization/>
</author>
<author initials="R." surname="Holz" fullname="R. Holz">
<organization/>
</author>
<author initials="P." surname="Saint-Andre" fullname="P. Saint-Andre">
<organization/>
</author>
<date year="2015" month="May"/>
<abstract>
<t>Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) are widely used to protect data exchanged over application protocols such as HTTP, SMTP, IMAP, POP, SIP, and XMPP. Over the last
few years, several serious attacks on TLS have emerged, including attacks on its most commonly used cipher suites and their modes of operation. This document provides recommendations for improving the
security of deployed services that use TLS and DTLS. The recommendations are applicable to the majority of use cases.
</t>
</abstract>
</front>
<seriesInfo name="BCP" value="195"/>
<seriesInfo name="RFC" value="7525"/>
<seriesInfo name="DOI" value="10.17487/RFC7525"/>
</reference>
<reference anchor="SHS" target="http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf">
<front>
<title>Secure Hash Standard (SHS)</title>
<author>
<organization>National Institute of Standards and
Technology</organization>
</author>
<date month="March" year="2012" />
</front>
<seriesInfo name="FIPS" value="PUB 180-4" />
<format target="http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf" type="PDF" />
</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>
<reference anchor="IANA.JWT.Claims" target="http://www.iana.org/assignments/jwt">
<front>
<title>JSON Web Token Claims</title>
<author>
<organization>IANA</organization>
</author>
<date/>
</front>
</reference>
<?rfc include='reference.RFC.4517'?>
<?rfc include='reference.RFC.7009'?> <!-- revocation -->
<?rfc include='reference.RFC.7517'?> <!-- JWK -->
<?rfc include='reference.RFC.7519'?> <!-- JWT -->
<?rfc include='reference.RFC.7591'?> <!-- Dynamic Client Registration -->
<?rfc include='reference.RFC.7662'?> <!-- introspection -->
<?rfc include='reference.RFC.8174'?>
<?rfc include='reference.RFC.8414'?> <!-- OAuth AS metadata -->
<?rfc include='reference.RFC.8446'?> <!-- TLS 1.3 -->
<?rfc include='http://xml2rfc.tools.ietf.org/public/rfc/bibxml3/reference.I-D.draft-ietf-oauth-token-binding-06.xml'?>
<reference anchor="X509Pitfalls" target="https://www.cryptologie.net/article/374/common-x509-certificate-validationcreation-pitfalls">
<front>
<title>Common x509 certificate validation/creation pitfalls</title>
<author fullname="David Wong" initials="D." surname="Wong"><organization/></author>
<date month="September" year="2016"/>
</front>
</reference>
<reference anchor="DangerousCode" target="http://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf">
<front>
<title>The Most Dangerous Code in the World: Validating SSL Certificates in Non-Browser Software</title>
<author fullname="Martin Georgiev" initials="M." surname="Georgiev"><organization/></author>
<author fullname="Subodh Iyengar" initials="S." surname="Iyengar"><organization/></author>
<author fullname="Suman Jana" initials="S." surname="Jana"><organization/></author>
<author fullname="Rishita Anubhai" initials="R." surname="Anubhai"><organization/></author>
<author fullname="Dan Boneh" initials="D." surname="Boneh"><organization/></author>
<author fullname="Vitaly Shmatikov" initials="V." surname="Shmatikov"><organization/></author>
<date/>
</front>
</reference>
</references>
<section title="Example Certificate, JSON Web Key, and Confirmation Method" anchor="example">
<t>
For reference, an <spanx style="verb">x5t#S256</spanx> value and the X.509 Certificate from which it was
calculated are provided in the following example figures. A JWK representation of the certificate's public
key along with the <spanx style="verb">x5c</spanx> member is also provided.
<figure title="x5t#S256 Confirmation Claim" anchor="cnf">
<artwork><![CDATA["cnf":{"x5t#S256":"A4DtL2JmUMhAsvJj5tKyn64SqzmuXbMrJa0n761y5v0"}
]]></artwork>
</figure>
<figure title="PEM Encoded Self-Signed Certificate" anchor="pem">
<artwork><![CDATA[-----BEGIN CERTIFICATE-----
MIIBBjCBrAIBAjAKBggqhkjOPQQDAjAPMQ0wCwYDVQQDDARtdGxzMB4XDTE4MTAx
ODEyMzcwOVoXDTIyMDUwMjEyMzcwOVowDzENMAsGA1UEAwwEbXRsczBZMBMGByqG
SM49AgEGCCqGSM49AwEHA0IABNcnyxwqV6hY8QnhxxzFQ03C7HKW9OylMbnQZjjJ
/Au08/coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8wCgYIKoZIzj0EAwID
SQAwRgIhAP0RC1E+vwJD/D1AGHGzuri+hlV/PpQEKTWUVeORWz83AiEA5x2eXZOV
bUlJSGQgjwD5vaUaKlLR50Q2DmFfQj1L+SY=
-----END CERTIFICATE-----]]></artwork>
</figure>
<figure title="JSON Web Key" anchor="jwk">
<artwork><![CDATA[
{
"kty":"EC",
"x":"1yfLHCpXqFjxCeHHHMVDTcLscpb07KUxudBmOMn8C7Q",
"y":"8_coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8",
"crv":"P-256",
"x5c":[
"MIIBBjCBrAIBAjAKBggqhkjOPQQDAjAPMQ0wCwYDVQQDDARtdGxzMB4XDTE4MTA
xODEyMzcwOVoXDTIyMDUwMjEyMzcwOVowDzENMAsGA1UEAwwEbXRsczBZMBMGBy
qGSM49AgEGCCqGSM49AwEHA0IABNcnyxwqV6hY8QnhxxzFQ03C7HKW9OylMbnQZ
jjJ/Au08/coZwxS7LfA4vOLS9WuneIXhbGGWvsDSb0tH6IxLm8wCgYIKoZIzj0E
AwIDSQAwRgIhAP0RC1E+vwJD/D1AGHGzuri+hlV/PpQEKTWUVeORWz83AiEA5x2
eXZOVbUlJSGQgjwD5vaUaKlLR50Q2DmFfQj1L+SY="
]
}]]></artwork>
</figure>
</t>
</section>
<section anchor="relation" title="Relationship to Token Binding">
<t>
<xref target="I-D.ietf-oauth-token-binding">OAuth 2.0 Token Binding</xref>
enables the application of Token Binding to the various artifacts and tokens employed throughout OAuth.
That includes binding of an access token to a Token Binding key, which bears some similarities in motivation
and design to the mutual TLS client certificate bound access tokens defined in this document.
Both documents define what is often called a proof-of-possession security mechanism
for access tokens, whereby a client must demonstrate possession of cryptographic keying
material when accessing a protected resource. The details differ somewhat between the two documents but both
have the authorization server bind the access token that it issues to an asymmetric key pair
held by the client. The client then proves possession of the private key from that pair
with respect to the TLS connection over which the protected resource is accessed.
</t>
<t>
Token Binding uses bare keys that are generated on the client,
which avoids many of the difficulties of creating, distributing, and managing certificates
used in this specification. However, at the time of
writing, Token Binding is fairly new and there is relatively little support for it in available
application development platforms and tooling. Until better support for the underlying
core Token Binding specifications exists, practical implementations of OAuth 2.0 Token Binding
are infeasible.
Mutual TLS, on the other hand, has been around for some time and enjoys
widespread support in web servers and development platforms. As a consequence, OAuth 2.0 Mutual TLS
Client Authentication and Certificate Bound Access Tokens can be
built and deployed now using existing platforms and tools.
In the future, the two specifications are likely to be
deployed in parallel for solving similar problems in different environments.
Authorization servers may even support both specifications simultaneously using different
proof-of-possession mechanisms for tokens issued to different clients.
</t>
</section>
<section anchor="Acknowledgements" title="Acknowledgements">
<t>
Scott "not Tomlinson" Tomilson and Matt Peterson were involved in
design and development work on a mutual TLS OAuth client authentication
implementation, which predates this document. Experience and learning from that work
informed some of the content of this document.
</t>