forked from jricher/oauth-spec
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathrfc7591.xml
2052 lines (1660 loc) · 97.6 KB
/
rfc7591.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"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<rfc submissionType="IETF" category="std" consensus="yes" number="7591" ipr="trust200902">
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc='yes' ?>
<?rfc tocdepth='3' ?>
<?rfc symrefs='yes' ?>
<?rfc sortrefs='yes' ?>
<?rfc compact='yes' ?>
<?rfc subcompact='no' ?>
<?rfc rfcedstyle="yes"?>
<front>
<title abbrev="OAuth 2.0 Dynamic Registration">OAuth 2.0 Dynamic Client
Registration Protocol</title>
<author fullname="Justin Richer" initials="J." role="editor"
surname="Richer">
<organization/>
<address>
<email>[email protected]</email>
</address>
</author>
<author fullname="Michael B. Jones" initials="M.B." surname="Jones">
<organization abbrev="Microsoft">Microsoft</organization>
<address>
<email>[email protected]</email>
<uri>http://self-issued.info/</uri>
</address>
</author>
<author fullname="John Bradley" initials="J." surname="Bradley">
<organization abbrev="Ping Identity">Ping Identity</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author fullname="Maciej Machulak" initials="M." surname="Machulak">
<organization>Newcastle University</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author fullname="Phil Hunt" initials="P." surname="Hunt">
<organization>Oracle Corporation</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<date month="July" year="2015"/>
<area>Security</area>
<workgroup>OAuth Working Group</workgroup>
<keyword>OpenID Connect</keyword>
<keyword>OpenID Connect Dynamic Client Registration</keyword>
<abstract>
<t>This specification defines mechanisms for dynamically registering
OAuth 2.0 clients with authorization servers. Registration requests send
a set of desired client metadata values to the authorization server. The
resulting registration responses return a client identifier to use at
the authorization server and the client metadata values registered for
the client. The client can then use this registration information to
communicate with the authorization server using the OAuth 2.0 protocol.
This specification also defines a set of common client metadata fields
and values for clients to use during registration.</t>
</abstract>
</front>
<middle>
<section anchor="Introduction" title="Introduction">
<t>In order for an <xref target="RFC6749">OAuth 2.0</xref> client to
utilize an OAuth 2.0 authorization server, the client needs specific
information to interact with the server, including an OAuth 2.0 client
identifier to use at that server. This specification describes how an
OAuth 2.0 client can be dynamically registered with an authorization
server to obtain this information.</t>
<t>As part of the registration process, this specification also defines
a mechanism for the client to present the authorization server with a
set of metadata, such as a set of valid redirection URIs.
This metadata can either be communicated in a self-asserted fashion or as
a set of metadata called a software statement, which is digitally
signed or protected with a Message Authentication Code (MAC); in the case of a software statement, the issuer is vouching for
the validity of the data about the client.</t>
<t>Traditionally, registration of a client with an authorization server
is performed manually. The mechanisms defined in this specification can
be used either for a client to dynamically register itself with
authorization servers or for a client developer to programmatically
register the client with authorization servers. Multiple applications
using OAuth 2.0 have previously developed mechanisms for accomplishing
such registrations. This specification generalizes the registration
mechanisms defined by <xref target="OpenID.Registration">"OpenID
Connect Dynamic Client Registration 1.0"</xref> and used by
<xref target="UMA-Core">"User Managed Access (UMA)
Profile of OAuth 2.0"</xref> in a way that is compatible
with both, while being applicable to a wider set of OAuth 2.0 use
cases.</t>
<section anchor="Notation" title="Notational Conventions">
<t>The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
document are to be interpreted as described in <xref
target="RFC2119"/>.</t>
<t>Unless otherwise noted, all the protocol parameter names and values
are case sensitive.</t>
</section>
<section anchor="Terminology" title="Terminology">
<t>This specification uses the terms "access token", "authorization
code", "authorization endpoint", "authorization grant", "authorization
server", "client", "client identifier", "client secret", "grant type",
"protected resource", "redirection URI", "refresh token", "resource
owner", "resource server", "response type", and "token endpoint"
defined by <xref target="RFC6749">OAuth 2.0</xref> and uses the term
"Claim" defined by <xref target="RFC7519">JSON Web Token
(JWT)</xref>.</t>
<t>This specification defines the following terms:</t>
<t><list style="hanging">
<t hangText="Client Software"><vspace/>Software implementing an
OAuth 2.0 client.</t>
<t hangText="Client Instance"><vspace/>A deployed instance of a
piece of client software.</t>
<t hangText="Client Developer"><vspace/>The person or organization
that builds a client software package and prepares it for
distribution. At the time the client is built, the developer is
often not aware of who the deploying service provider
organizations will be. Client developers will need to use dynamic
registration when they are unable to predict aspects of the
software, such as the deployment URLs, at compile time. For
instance, this can occur when the software API publisher and the
deploying organization are not the same.</t>
<t hangText="Client Registration Endpoint"><vspace/>OAuth 2.0
endpoint through which a client can be registered at an
authorization server. The means by which the URL for this endpoint
is obtained are out of scope for this specification.</t>
<t hangText="Initial Access Token"><vspace/>OAuth 2.0 access token
optionally issued by an authorization server to a developer or
client and used to authorize calls to the client registration
endpoint. The type and format of this token are likely
service specific and are out of scope for this specification. The
means by which the authorization server issues this token as well
as the means by which the registration endpoint validates this
token are out of scope for this specification. Use of an initial
access token is required when the authorization server limits the
parties that can register a client.</t>
<t hangText="Deployment Organization"><vspace/>An administrative
security domain under which a software API (service) is deployed
and protected by an OAuth 2.0 framework. In some OAuth scenarios,
the deployment organization and the software API publisher are the
same. In these cases, the deploying organization will often have a
close relationship with client software developers. In many other
cases, the definer of the service may be an independent
third-party publisher or a standards organization. When working to
a published specification for an API, the client software
developer is unable to have a prior relationship with the
potentially many deployment organizations deploying the software
API (service).</t>
<t hangText="Software API Deployment"><vspace/>A deployed instance
of a software API that is protected by OAuth 2.0 (a protected
resource) in a particular deployment organization domain. For any
particular software API, there may be one or more deployments. A
software API deployment typically has an associated OAuth 2.0
authorization server as well as a client registration endpoint.
The means by which endpoints are obtained are out of scope for
this specification.</t>
<t hangText="Software API Publisher"><vspace/>The organization
that defines a particular web-accessible API that may be deployed
in one or more deployment environments. A publisher may be any
standards body, commercial, public, private, or open source
organization that is responsible for publishing and distributing
software and API specifications that may be protected via OAuth
2.0. In some cases, a software API publisher and a client
developer may be the same organization. At the time of publication
of a web-accessible API, the software publisher often does not
have a prior relationship with the deploying organizations.</t>
<t hangText="Software Statement"><vspace/>A digitally signed or
MACed JSON Web Token (JWT) <xref target="RFC7519"/> that asserts
metadata values about the client software. In some cases, a
software statement will be issued directly by the client
developer. In other cases, a software statement will be issued by
a third-party organization for use by the client developer. In
both cases, the trust relationship the authorization server has
with the issuer of the software statement is intended to be used
as an input to the evaluation of whether the registration request
is accepted. A software statement can be presented to an
authorization server as part of a client registration request.</t>
</list></t>
</section>
<section anchor="ProtocolFlow" title="Protocol Flow">
<figure>
<artwork><![CDATA[
+--------(A)- Initial Access Token (OPTIONAL)
|
| +----(B)- Software Statement (OPTIONAL)
| |
v v
+-----------+ +---------------+
| |--(C)- Client Registration Request -->| Client |
| Client or | | Registration |
| Developer |<-(D)- Client Information Response ---| Endpoint |
| | or Client Error Response +---------------+
+-----------+
]]></artwork>
<postamble>Figure 1: Abstract Dynamic Client Registration
Flow</postamble>
</figure>
<t/>
<t>The abstract OAuth 2.0 client dynamic registration flow illustrated
in Figure 1 describes the interaction between the client or developer
and the endpoint defined in this specification. This figure does not
demonstrate error conditions. This flow includes the following
steps:</t>
<t><list style="hanging" hangIndent="6">
<t hangText="(A)">Optionally, the client or developer is issued an
initial access token giving access to the client registration
endpoint. The method by which the initial access token is issued
to the client or developer is out of scope for this
specification.</t>
<t hangText="(B)">Optionally, the client or developer is issued a
software statement for use with the client registration endpoint.
The method by which the software statement is issued to the client
or developer is out of scope for this specification.</t>
<t hangText="(C)">The client or developer calls the client
registration endpoint with the client's desired registration
metadata, optionally including the initial access token from (A)
if one is required by the authorization server.</t>
<t hangText="(D)">The authorization server registers the client
and returns: <list style="symbols">
<t>the client's registered metadata,</t>
<t>a client identifier that is unique at the server, and</t>
<t>a set of client credentials such as a client secret, if
applicable for this client.</t>
</list></t>
</list></t>
<t>Examples of different configurations and usages are included in
<xref target="UseCases"/>.</t>
</section>
</section>
<section anchor="ClientMetadata" title="Client Metadata">
<t>Registered clients have a set of metadata values associated with
their client identifier at an authorization server, such as the list of
valid redirection URIs or a display name.</t>
<t>These client metadata values are used in two ways:</t>
<t><list style="symbols">
<t>as input values to registration requests, and</t>
<t>as output values in registration responses.</t>
</list></t>
<t>The following client metadata fields are defined by this
specification. The implementation and use of all client metadata fields
is OPTIONAL, unless stated otherwise. All data member types (strings,
arrays, numbers) are defined in terms of their <xref
target="RFC7159">JSON</xref> representations.</t>
<t><list style="hanging">
<t hangText="redirect_uris"><vspace/>Array of redirection URI
strings for use in redirect-based flows such as the authorization
code and implicit flows. As required by Section 2 of <xref
target="RFC6749">OAuth 2.0</xref>, clients using flows with
redirection MUST register their redirection URI values.
Authorization servers that support dynamic registration for
redirect-based flows MUST implement support for this metadata
value.</t>
<t hangText="token_endpoint_auth_method"><vspace/>String indicator
of the requested authentication method for the token endpoint.
Values defined by this specification are: <list style="symbols">
<t><spanx style="verb">none</spanx>: The client is a public
client as defined in OAuth 2.0, Section 2.1, and does not have a client
secret.</t>
<t><spanx style="verb">client_secret_post</spanx>: The client
uses the HTTP POST parameters as defined in OAuth 2.0, Section
2.3.1.</t>
<t><spanx style="verb">client_secret_basic</spanx>: The client
uses HTTP Basic as defined in OAuth 2.0, Section 2.3.1.</t>
</list>Additional values can be defined via the IANA OAuth Token
Endpoint Authentication Methods Registry established in <xref
target="TEAMRegistry"/>. Absolute URIs can also be used as values
for this parameter without being registered. If unspecified or
omitted, the default is <spanx style="verb">client_secret_basic</spanx>,
denoting the HTTP Basic authentication scheme as specified in Section
2.3.1 of OAuth 2.0.</t>
<t hangText="grant_types"><vspace/>Array of OAuth 2.0 grant type
strings that the client can use at the token endpoint. These grant
types are defined as follows: <list style="symbols">
<t><spanx style="verb">authorization_code</spanx>: The
authorization code grant type described in OAuth 2.0, Section 4.1.</t>
<t><spanx style="verb">implicit</spanx>: The implicit grant type
described in OAuth 2.0, Section 4.2.</t>
<t><spanx style="verb">password</spanx>: The resource owner
password credentials grant type described in OAuth 2.0, Section
4.3.</t>
<t><spanx style="verb">client_credentials</spanx>: The client
credentials grant type described in OAuth 2.0, Section 4.4.</t>
<t><spanx style="verb">refresh_token</spanx>: The refresh token
grant type described in OAuth 2.0, Section 6.</t>
<t><spanx style="verb">urn:ietf:params:oauth:grant-type:jwt-bearer</spanx>:
The JWT Bearer Token Grant Type defined in <xref target="RFC7523">OAuth JWT
Bearer Token Profiles</xref>.</t>
<t><spanx style="verb">urn:ietf:params:oauth:grant-type:saml2-bearer</spanx>:
The SAML 2.0 Bearer Assertion Grant defined in <xref target="RFC7522">OAuth
SAML 2 Bearer Token Profiles</xref>.</t>
</list>If the token endpoint is used in the grant type, the value
of this parameter MUST be the same as the value of the <spanx
style="verb">grant_type</spanx> parameter passed to the token
endpoint defined in the grant type definition. Authorization servers
MAY allow for other values as defined in the grant type extension
process described in OAuth 2.0, Section 4.5. If omitted, the default
behavior is that the client will use only the <spanx style="verb">authorization_code</spanx>
Grant Type.</t>
<t hangText="response_types"><vspace/>Array of the OAuth 2.0
response type strings that the client can use at the authorization
endpoint. These response types are defined as follows: <list
style="symbols">
<t><spanx style="verb">code</spanx>: The authorization code
response described in OAuth 2.0, Section 4.1.</t>
<t><spanx style="verb">token</spanx>: The implicit response
described in OAuth 2.0, Section 4.2.</t>
</list>If the authorization endpoint is used by the grant type,
the value of this parameter MUST be the same as the value of the
<spanx style="verb">response_type</spanx> parameter passed to the
authorization endpoint defined in the grant type definition.
Authorization servers MAY allow for other values as defined in the
grant type extension process is described in OAuth 2.0, Section 4.5.
If omitted, the default is that the client will use only the <spanx
style="verb">code</spanx> response type.</t>
<t hangText="client_name"><vspace/>Human-readable string name of the
client to be presented to the end-user during authorization. If
omitted, the authorization server MAY display the raw <spanx
style="verb">client_id</spanx> value to the end-user instead. It is
RECOMMENDED that clients always send this field. The value of this
field MAY be internationalized, as described in <xref
target="HumanReadableClientMetadata"/>.</t>
<t hangText="client_uri"><vspace/>URL string of a web page providing
information about the client. If present, the server SHOULD display
this URL to the end-user in a clickable fashion. It is RECOMMENDED
that clients always send this field. The value of this field MUST
point to a valid web page. The value of this field MAY be
internationalized, as described in <xref
target="HumanReadableClientMetadata"/>.</t>
<t hangText="logo_uri"><vspace/>URL string that references a logo
for the client. If present, the server SHOULD display this image to
the end-user during approval. The value of this field MUST point to
a valid image file. The value of this field MAY be
internationalized, as described in <xref
target="HumanReadableClientMetadata"/>.</t>
<t hangText="scope"><vspace/>String containing a space-separated
list of scope values (as described in Section 3.3 of <xref
target="RFC6749">OAuth 2.0</xref>) that the client can use when
requesting access tokens. The semantics of values in this list are
service specific. If omitted, an authorization server MAY register a
client with a default set of scopes.</t>
<t hangText="contacts"><vspace/>Array of strings representing ways
to contact people responsible for this client, typically email
addresses. The authorization server MAY make these contact addresses
available to end-users for support requests for the client. See
<xref target="Privacy"/> for information on Privacy
Considerations.</t>
<t hangText="tos_uri"><vspace/>URL string that points to a
human-readable terms of service document for the client that
describes a contractual relationship between the end-user and the
client that the end-user accepts when authorizing the client. The
authorization server SHOULD display this URL to the end-user if it
is provided. The value of this field MUST point to a valid web page.
The value of this field MAY be internationalized, as described in
<xref target="HumanReadableClientMetadata"/>.</t>
<t hangText="policy_uri"><vspace/>URL string that points to a
human-readable privacy policy document that describes how the
deployment organization collects, uses, retains, and discloses
personal data. The authorization server SHOULD display this URL to
the end-user if it is provided. The value of this field MUST point
to a valid web page. The value of this field MAY be
internationalized, as described in <xref
target="HumanReadableClientMetadata"/>.</t>
<t hangText="jwks_uri"><vspace/>URL string referencing the client's
JSON Web Key (JWK) Set <xref target="RFC7517"/> document, which contains
the client's public keys. The value of this field MUST point to a
valid JWK Set document. These keys can be used by higher-level
protocols that use signing or encryption. For instance, these keys
might be used by some applications for validating signed requests
made to the token endpoint when using JWTs for client authentication
<xref target="RFC7523"/>. Use of this parameter is preferred over
the <spanx style="verb">jwks</spanx> parameter, as it allows for
easier key rotation. The <spanx style="verb">jwks_uri</spanx> and
<spanx style="verb">jwks</spanx> parameters MUST NOT both be present
in the same request or response.</t>
<t hangText="jwks"><vspace/>Client's JSON Web Key Set <xref
target="RFC7517"/> document value, which contains the client's
public keys. The value of this field MUST be a JSON object
containing a valid JWK Set. These keys can be used by higher-level
protocols that use signing or encryption. This parameter is intended
to be used by clients that cannot use the <spanx style="verb">jwks_uri</spanx>
parameter, such as native clients that cannot host public URLs. The
<spanx style="verb">jwks_uri</spanx> and <spanx style="verb">jwks</spanx>
parameters MUST NOT both be present in the same request or
response.</t>
<t hangText="software_id"><vspace/>A unique identifier
string (e.g., a Universally Unique Identifier (UUID)) assigned by the client developer or
software publisher used by registration endpoints to
identify the client software to be dynamically
registered. Unlike <spanx style="verb">client_id</spanx>,
which is issued by the authorization server and SHOULD vary
between instances, the <spanx
style="verb">software_id</spanx> SHOULD remain the same for
all instances of the client software. The <spanx
style="verb">software_id</spanx> SHOULD remain the same
across multiple updates or versions of the same piece of
software. The value of this field is not intended to be
human readable and is usually opaque to the client and
authorization server.</t>
<t hangText="software_version"><vspace/>A version identifier string
for the client software identified by <spanx style="verb">software_id</spanx>.
The value of the <spanx style="verb">software_version</spanx> SHOULD
change on any update to the client software identified by the same
<spanx style="verb">software_id</spanx>. The value of this field is
intended to be compared using string equality matching and no other
comparison semantics are defined by this specification. The value of
this field is outside the scope of this specification, but it is
not intended to be human readable and is usually opaque to the
client and authorization server. The definition of what constitutes
an update to client software that would trigger a change to this
value is specific to the software itself and is outside the scope of
this specification.</t>
</list></t>
<t>Extensions and profiles of this specification can expand this list
with metadata names and descriptions registered in accordance with the
IANA Considerations in <xref target="IANA"/> of this document. The
authorization server MUST ignore any client metadata sent by the client
that it does not understand (for instance, by silently removing unknown
metadata from the client's registration record during processing). The
authorization server MAY reject any requested client metadata values by
replacing requested values with suitable defaults as described in <xref
target="ClientInfoResponse"/> or by returning an error response as
described in <xref target="ClientRegistrationError"/>.</t>
<t>Client metadata values can be either communicated directly in the
body of a registration request, as described in <xref
target="RegistrationRequest"/>, or included as claims in a software
statement, as described in <xref target="SoftwareStatement"/>; a
mixture of both is also possible. If the same client metadata name is present in both
locations and the software statement is trusted by the authorization
server, the value of a claim in the software statement MUST take
precedence.</t>
<section anchor="GrantTypesAndResponseTypes"
title="Relationship between Grant Types and Response Types">
<t>The <spanx style="verb">grant_types</spanx> and <spanx
style="verb">response_types</spanx> values described above are
partially orthogonal, as they refer to arguments passed to different
endpoints in the OAuth protocol. However, they are related in that the
<spanx style="verb">grant_types</spanx> available to a client
influence the <spanx style="verb">response_types</spanx> that the
client is allowed to use, and vice versa. For instance, a <spanx
style="verb">grant_types</spanx> value that includes <spanx
style="verb">authorization_code</spanx> implies a <spanx style="verb">response_types</spanx>
value that includes <spanx style="verb">code</spanx>, as both values
are defined as part of the OAuth 2.0 authorization code grant. As
such, a server supporting these fields SHOULD take steps to ensure
that a client cannot register itself into an inconsistent state, for
example, by returning an <spanx style="verb">invalid_client_metadata</spanx>
error response to an inconsistent registration request.</t>
<t>The correlation between the two fields is listed in the table
below.</t>
<texttable>
<ttcol>grant_types value includes:</ttcol>
<ttcol>response_types value includes:</ttcol>
<c>authorization_code</c>
<c>code</c>
<c>implicit</c>
<c>token</c>
<c>password</c>
<c>(none)</c>
<c>client_credentials</c>
<c>(none)</c>
<c>refresh_token</c>
<c>(none)</c>
<c>urn:ietf:params:oauth:grant-type:jwt-bearer</c>
<c>(none)</c>
<c>urn:ietf:params:oauth:grant-type:saml2-bearer</c>
<c>(none)</c>
</texttable>
<t>Extensions and profiles of this document that introduce new values
to either the <spanx style="verb">grant_types</spanx> or <spanx
style="verb">response_types</spanx> parameter MUST document all
correspondences between these two parameter types.</t>
</section>
<section anchor="HumanReadableClientMetadata"
title="Human-Readable Client Metadata">
<t>Human-readable client metadata values and client metadata values
that reference human-readable values MAY be represented in multiple
languages and scripts. For example, the values of fields such as
<spanx style="verb">client_name</spanx>, <spanx style="verb">tos_uri</spanx>,
<spanx style="verb">policy_uri</spanx>, <spanx style="verb">logo_uri</spanx>,
and <spanx style="verb">client_uri</spanx> might have multiple
locale-specific values in some client registrations to facilitate use
in different locations.</t>
<t>To specify the languages and scripts, <xref
target="RFC5646">BCP 47</xref> language tags are added to client
metadata member names, delimited by a <spanx style="verb">#</spanx> character. Since <xref
target="RFC7159">JSON</xref> member names are case sensitive, it is
RECOMMENDED that language tag values used in Claim Names be spelled
using the character case with which they are registered in the <xref
target="IANA.Language">IANA Language Subtag Registry</xref>. In
particular, normally language names are spelled with lowercase
characters, region names are spelled with uppercase characters, and
languages are spelled with mixed-case characters. However, since BCP 47
language tag values are case-insensitive, implementations SHOULD
interpret the language tag values supplied in a case insensitive
manner. Per the recommendations in BCP 47, language tag values used in
metadata member names should only be as specific as necessary. For
instance, using <spanx style="verb">fr</spanx> might be sufficient in
many contexts, rather than <spanx style="verb">fr-CA</spanx> or <spanx
style="verb">fr-FR</spanx>.</t>
<!--[rfced] Please update the following in post-xml2rfc processing per J. Richer:
Section 2.2: nit, formatting of quotes around example values consisting of quoted strings. I would recommend making this edit post xml2rfc so that the XML file retains the semantic "spanx:verb" tags around these elements.
OLD:
For example, a client could represent its name in English as
""client_name#en": "My Client"" and its name in Japanese as
""client_name#ja-Jpan-JP":
"\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"" within the same
NEW:
For example, a client could represent its name in English as
"client_name#en": "My Client" and its name in Japanese as
"client_name#ja-Jpan-JP":
"\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D" within the same
-->
<t>For example, a client could represent its name in English as <spanx
style="verb">"client_name#en": "My Client"</spanx> and its name in
Japanese as <spanx style="verb">"client_name#ja-Jpan-JP": "\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D"</spanx>
within the same registration request. The authorization server MAY
display any or all of these names to the resource owner during the
authorization step, choosing which name to display based on system
configuration, user preferences or other factors.</t>
<t>If any human-readable field is sent without a language tag, parties
using it MUST NOT make any assumptions about the language, character
set, or script of the string value, and the string value MUST be used
as is wherever it is presented in a user interface. To facilitate
interoperability, it is RECOMMENDED that clients and servers use a
human-readable field without any language tags in addition to any
language-specific fields, and it is RECOMMENDED that any
human-readable fields sent without language tags contain values
suitable for display on a wide variety of systems.</t>
<t>Implementer's Note: Many JSON libraries make it possible to
reference members of a JSON object as members of an object construct
in the native programming environment of the library. However, while
the <spanx style="verb">#</spanx> character is a valid character
inside of a JSON object's member names, it is not a valid character
for use in an object member name in many programming environments.
Therefore, implementations will need to use alternative access forms
for these claims. For instance, in JavaScript, if one parses the JSON
as follows, <spanx style="verb">var j = JSON.parse(json);</spanx>,
then as a workaround the member <spanx style="verb">client_name#en-us</spanx>
can be accessed using the JavaScript syntax <spanx style="verb">j["client_name#en-us"]</spanx>.</t>
</section>
<section anchor="SoftwareStatement" title="Software Statement">
<t>A software statement is a JSON Web Token (JWT) <xref
target="RFC7519"/> that asserts metadata values about the client
software as a bundle. A set of claims that can be used in a software
statement are defined in <xref target="ClientMetadata"/>. When
presented to the authorization server as part of a client registration
request, the software statement MUST be digitally signed or MACed
using <xref target="RFC7515">JSON Web Signature (JWS)</xref> and MUST contain an <spanx
style="verb">iss</spanx> (issuer) claim denoting the party attesting
to the claims in the software statement. It is RECOMMENDED that
software statements be digitally signed using the <spanx style="verb">RS256</spanx>
signature algorithm, although particular applications MAY specify the
use of different algorithms. It is RECOMMENDED that software
statements contain the <spanx style="verb">software_id</spanx> claim
to allow authorization servers to correlate different instances of
software using the same software statement.</t>
<t>For example, a software statement could contain the following
claims:</t>
<figure>
<artwork><![CDATA[{
"software_id": "4NRB1-0XZABZI9E6-5SM3R",
"client_name": "Example Statement-based Client",
"client_uri": "https://client.example.net/"
}]]></artwork>
</figure>
<t/>
<t>The following non-normative example JWT includes these claims and
has been asymmetrically signed using RS256:</t>
<figure>
<preamble>(Line breaks are for display purposes only)</preamble>
<artwork><![CDATA[eyJhbGciOiJSUzI1NiJ9.
eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGll
bnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNs
aWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ.
GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHa
zdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn0
5X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxY
fHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxsk
U5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJf
IjoI3zTJ0Y2oe0_EJAiXbL6OyF9S5tKxDXV8JIndSA
]]></artwork>
</figure>
<t/>
<t>The software statement is typically distributed with all instances
of a client application. The means by which a client or developer
obtains a software statement are outside the scope of this
specification. Some common methods could include a client developer
generating a client-specific JWT by registering with a software
API publisher to obtain a software statement for a class of clients.</t>
<t>The criteria by which authorization servers determine whether to
trust and utilize the information in a software statement are outside
the scope of this specification.</t>
<t>In some cases, authorization servers MAY choose to accept a software
statement value directly as a client identifier in an authorization
request, without a prior dynamic client registration having been
performed. The circumstances under which an authorization server
would do so, and the specific software statement characteristics
required in this case, are outside the scope of this specification.</t>
</section>
</section>
<section anchor="RegistrationEndpoint"
title="Client Registration Endpoint">
<t>The client registration endpoint is an OAuth 2.0 endpoint defined in
this document that is designed to allow a client to be registered with
the authorization server. The client registration endpoint MUST accept
HTTP POST messages with request parameters encoded in the entity body
using the <spanx style="verb">application/json</spanx> format. The
client registration endpoint MUST be protected by a tranport-layer security mechanism, as described in <xref target="Security"/>.</t>
<t>The client registration endpoint MAY be an <xref
target="RFC6749">OAuth 2.0</xref> protected
resource and it MAY accept an initial access token in the form of an OAuth 2.0 access token to limit registration to
only previously authorized parties. The method by which the initial
access token is obtained by the client or developer is generally
out of band and is out of scope for this specification. The method by
which the initial access token is verified and validated by the client
registration endpoint is out of scope for this specification.</t>
<t>To support open registration and facilitate wider interoperability,
the client registration endpoint SHOULD allow registration requests with
no authorization (which is to say, with no initial access token in the
request). These requests MAY be rate-limited or otherwise limited to
prevent a denial-of-service attack on the client registration
endpoint.</t>
<section anchor="RegistrationRequest"
title="Client Registration Request">
<t>This operation registers a client with the authorization server.
The authorization server assigns this client a unique client
identifier, optionally assigns a client secret, and associates the
metadata provided in the request with the issued client identifier.
The request includes any client metadata parameters being specified
for the client during the registration. The authorization server MAY
provision default values for any items omitted in the client
metadata.</t>
<t>To register, the client or developer sends an HTTP POST to the
client registration endpoint with a content type of <spanx
style="verb">application/json</spanx>. The HTTP Entity Payload is a
<xref target="RFC7159">JSON</xref> document consisting of a JSON
object and all requested client metadata values as top-level members
of that JSON object.</t>
<t>For example, if the server supports open registration (with no
initial access token), the client could send the following
registration request to the client registration endpoint:</t>
<figure>
<preamble>The following is a non-normative example request not using
an initial access token (with line wraps within values for display
purposes only):</preamble>
<artwork><![CDATA[
POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: server.example.com
{
"redirect_uris": [
"https://client.example.org/callback",
"https://client.example.org/callback2"],
"client_name": "My Example Client",
"client_name#ja-Jpan-JP":
"\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D",
"token_endpoint_auth_method": "client_secret_basic",
"logo_uri": "https://client.example.org/logo.png",
"jwks_uri": "https://client.example.org/my_public_keys.jwks",
"example_extension_parameter": "example_value"
}
]]></artwork>
</figure>
<t>Alternatively, if the server supports authorized registration, the
developer or the client will be provisioned with an initial access
token. (The method by which the initial access token is obtained is
out of scope for this specification.) The developer or client sends
the following authorized registration request to the client
registration endpoint. Note that the initial access token sent in this
example as an OAuth 2.0 Bearer Token <xref target="RFC6750"/>, but any
OAuth 2.0 token type could be used by an authorization server.</t>
<figure>
<preamble>The following is a non-normative example request using an
initial access token and registering a JWK Set by value (with line
wraps within values for display purposes only):</preamble>
<artwork><![CDATA[
POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer ey23f2.adfj230.af32-developer321
Host: server.example.com
{
"redirect_uris": ["https://client.example.org/callback",
"https://client.example.org/callback2"],
"client_name": "My Example Client",
"client_name#ja-Jpan-JP":
"\u30AF\u30E9\u30A4\u30A2\u30F3\u30C8\u540D",
"token_endpoint_auth_method": "client_secret_basic",
"policy_uri": "https://client.example.org/policy.html",
"jwks": {"keys": [{
"e": "AQAB",
"n": "nj3YJwsLUFl9BmpAbkOswCNVx17Eh9wMO-_AReZwBqfaWFcfG
HrZXsIV2VMCNVNU8Tpb4obUaSXcRcQ-VMsfQPJm9IzgtRdAY8NN8Xb7PEcYyk
lBjvTtuPbpzIaqyiUepzUXNDFuAOOkrIol3WmflPUUgMKULBN0EUd1fpOD70p
RM0rlp_gg_WNUKoW1V-3keYUJoXH9NztEDm_D2MQXj9eGOJJ8yPgGL8PAZMLe
2R7jb9TxOCPDED7tY_TU4nFPlxptw59A42mldEmViXsKQt60s1SLboazxFKve
qXC_jpLUt22OC6GUG63p-REw-ZOr3r845z50wMuzifQrMI9bQ",
"kty": "RSA"
}]},
"example_extension_parameter": "example_value"
}
]]></artwork>
</figure>
<section anchor="ClientRegistrationSoftwareStatement"
title="Client Registration Request Using a Software Statement">
<t>In addition to JSON elements, client metadata values MAY also be
provided in a software statement, as described in <xref
target="SoftwareStatement"/>. The authorization server MAY ignore
the software statement if it does not support this feature. If the
server supports software statements, client metadata values conveyed
in the software statement MUST take precedence over those conveyed
using plain JSON elements.</t>
<t>Software statements are included in the requesting JSON object
using this OPTIONAL member: <list style="hanging">
<t hangText="software_statement"><vspace/> A software statement
containing client metadata values about the client software as
claims. This is a string value containing the entire signed
JWT.</t>
</list></t>
<figure>
<preamble>In the following example, some registration parameters
are conveyed as claims in a software statement from the example in
<xref target="SoftwareStatement"/>, while some values specific to
the client instance are conveyed as regular parameters (with line
wraps within values for display purposes only):</preamble>
<artwork><![CDATA[
POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: server.example.com
{
"redirect_uris": [
"https://client.example.org/callback",
"https://client.example.org/callback2"
],
"software_statement": "eyJhbGciOiJSUzI1NiJ9.
eyJzb2Z0d2FyZV9pZCI6IjROUkIxLTBYWkFCWkk5RTYtNVNNM1IiLCJjbGll
bnRfbmFtZSI6IkV4YW1wbGUgU3RhdGVtZW50LWJhc2VkIENsaWVudCIsImNs
aWVudF91cmkiOiJodHRwczovL2NsaWVudC5leGFtcGxlLm5ldC8ifQ.
GHfL4QNIrQwL18BSRdE595T9jbzqa06R9BT8w409x9oIcKaZo_mt15riEXHa
zdISUvDIZhtiyNrSHQ8K4TvqWxH6uJgcmoodZdPwmWRIEYbQDLqPNxREtYn0
5X3AR7ia4FRjQ2ojZjk5fJqJdQ-JcfxyhK-P8BAWBd6I2LLA77IG32xtbhxY
fHX7VhuU5ProJO8uvu3Ayv4XRhLZJY4yKfmyjiiKiPNe-Ia4SMy_d_QSWxsk
U5XIQl5Sa2YRPMbDRXttm2TfnZM1xx70DoYi8g6czz-CPGRi4SW_S2RKHIJf
IjoI3zTJ0Y2oe0_EJAiXbL6OyF9S5tKxDXV8JIndSA",
"scope": "read write",
"example_extension_parameter": "example_value"
}
]]></artwork>
</figure>
</section>
</section>
<section anchor="Responses" title="Responses">
<t>Upon a successful registration request, the authorization server
returns a client identifier for the client. The server responds with
an HTTP 201 Created status code and a body of type <spanx style="verb">application/json</spanx>
with content as described in <xref target="ClientInfoResponse"/>.</t>
<t>Upon an unsuccessful registration request, the authorization server
responds with an error, as described in <xref
target="ClientRegistrationError"/>.</t>
<section anchor="ClientInfoResponse"
title="Client Information Response">
<t>The response contains the client identifier as well as the client
secret, if the client is a confidential client. The response MAY
contain additional fields as specified by extensions to this
specification.</t>
<t><list style="hanging">
<t hangText="client_id"><vspace/> REQUIRED. OAuth 2.0 client
identifier string. It SHOULD NOT be currently valid for any
other registered client, though an authorization server MAY
issue the same client identifier to multiple instances of a
registered client at its discretion.</t>
<t hangText="client_secret"><vspace/> OPTIONAL. OAuth 2.0 client
secret string. If issued, this MUST be unique for each <spanx
style="verb">client_id</spanx> and SHOULD be unique for multiple
instances of a client using the same <spanx style="verb">client_id</spanx>.
This value is used by confidential clients to authenticate to
the token endpoint as described in <xref target="RFC6749">OAuth
2.0</xref>, Section 2.3.1.</t>
<t hangText="client_id_issued_at"><vspace/> OPTIONAL. Time at which the client identifier was issued. The
time is represented as the number of seconds from
1970-01-01T00:00:00Z as measured in UTC until the date/time of
issuance.</t>
<t hangText="client_secret_expires_at"><vspace/> REQUIRED if
<spanx style="verb">client_secret</spanx> is issued. Time at which the client
secret will expire or 0 if it will not expire. The time is
represented as the number of seconds from 1970-01-01T00:00:00Z as
measured in UTC until the date/time of expiration.</t>
</list></t>
<t>Additionally, the authorization server MUST return all registered
metadata about this client, including any fields provisioned by the
authorization server itself. The authorization server MAY reject or
replace any of the client's requested metadata values submitted
during the registration and substitute them with suitable values.
The client or developer can check the values in the response to
determine if the registration is sufficient for use (e.g., the
registered <spanx style="verb">token_endpoint_auth_method</spanx> is
supported by the client software) and determine a course of action
appropriate for the client software. The response to such a
situation is out of scope for this specification but could include
filing a report with the application developer or authorization
server provider, attempted re-registration with different metadata
values, or various other methods. For instance, if the server also
supports a registration management mechanism such as that defined in
<xref target="RFC7592"/>, the client or
developer could attempt to update the registration with different
metadata values. This process could also be aided by a service
discovery protocol, such as <xref target="OpenID.Discovery"/>, which
can list a server's capabilities, allowing a client to make a more
informed registration request. The use of any such management or
discovery system is optional and outside the scope of this
specification.</t>
<t>The successful registration response uses an HTTP 201 Created
status code with a body of type <spanx style="verb">application/json</spanx>
consisting of a single <xref target="RFC7159">JSON object</xref>
with all parameters as top-level members of the object.</t>
<t>If a software statement was used as part of the registration, its
value MUST be returned unmodified in the response along with other
metadata using the <spanx style="verb">software_statement</spanx>
member name. Client metadata elements used from the software
statement MUST also be returned directly as top-level client
metadata values in the registration response (possibly with
different values, since the values requested and the values used may
differ).</t>
<figure>
<preamble>The following is a non-normative example response of a
successful registration:</preamble>
<artwork><![CDATA[
HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{
"client_id": "s6BhdRkqt3",
"client_secret": "cf136dc3c1fc93f31185e5885805d",
"client_id_issued_at": 2893256800,
"client_secret_expires_at": 2893276800,
"redirect_uris": [
"https://client.example.org/callback",