forked from mrtopf/UMA-Specifications
/
oauth-uma-grant.xml
1886 lines (1590 loc) · 91.6 KB
/
oauth-uma-grant.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 PUBLIC "-//IETF//DTD RFC 2629//EN"
"http://xml2rfc.tools.ietf.org/authoring/rfc2629.dtd" [
<!ENTITY RFC6749 SYSTEM "http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6749.xml">
<!ENTITY RFC2119 SYSTEM "http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC7159 SYSTEM "http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7159.xml">
<!ENTITY RFC7591 SYSTEM "http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7591.xml">
<!ENTITY RFC5785 SYSTEM "http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.5785.xml">
<!ENTITY RFC3986 SYSTEM "http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.3986.xml">
<!ENTITY RFC6750 SYSTEM "http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6750.xml">
<!ENTITY RFC6819 SYSTEM "http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6819.xml">
<!ENTITY RFC7009 SYSTEM "http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7009.xml">
]>
<rfc category="std" docName="oauth-uma-grant" id="kantara" ipr="kantara"
target="draft" version="2.0">
<?xml-stylesheet texttype='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc='yes' ?>
<?rfc tocdepth='4' ?>
<?rfc symrefs='yes' ?>
<?rfc sortrefs='yes' ?>
<?rfc compact='yes' ?>
<?rfc subcompact='no' ?>
<front>
<title abbrev="">User-Managed Access (UMA) 2.0 Grant for OAuth 2.0
Authorization</title>
<author fullname="Eve Maler" initials="E." role="editor" surname="Maler">
<organization>ForgeRock</organization>
<address>
<email>eve.maler@forgerock.com</email>
</address>
</author>
<author fullname="Maciej Machulak" initials="M." surname="Machulak">
<organization>Self</organization>
<address>
<email>maciej.machulak@gmail.com</email>
</address>
</author>
<author fullname="Justin Richer" initials="J." surname="Richer">
<organization>Bespoke Engineering</organization>
<address>
<email>justin@bspk.io</email>
</address>
</author>
<date day="26" month="July" year="2017" />
<abstract>
<t>This specification defines a means for a client, representing a
requesting party, to use a permission ticket to request an OAuth 2.0
access token to gain access to a protected resource asynchronously from
the time a resource owner authorizes access.</t>
</abstract>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>This specification defines an extension OAuth 2.0 <xref
target="RFC6749" /> grant. The grant enhances OAuth capabilities in the
following ways:<list style="symbols">
<t>The resource owner authorizes protected resource access to
clients used by entities that are in a <spanx>requesting
party</spanx> role. This enables party-to-party authorization,
rather than authorization of application access alone.</t>
<t>The authorization server and resource server interact with the
client and requesting party in a way that is
<spanx>asynchronous</spanx> with respect to resource owner
interactions. This lets a resource owner configure an authorization
server with authorization grant rules (policy conditions) at will,
rather than authorizing access token issuance synchronously just
after authenticating.</t>
</list></t>
<t>For example, bank customer (resource owner) Alice with a bank account
service (resource server) can use a sharing management service
(authorization server) hosted by the bank to manage access to her
various protected resources by spouse Bob, accounting professional
Charline, and bank account aggregation company DecideAccount, all using
different client applications, to view account data and get access to
payment or withdrawal functions.</t>
<t>An OPTIONAL second specification, <xref target="UMAFedAuthz" />,
defines a means for an UMA-enabled authorization server and resource
server to be loosely coupled, or federated, in a resource owner context.
This specification, together with <xref target="UMAFedAuthz" />,
constitutes UMA 2.0.</t>
<section title="Notational 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
<xref target="RFC2119" />.</t>
<t>Unless otherwise noted, all parameter names and values are case
sensitive. JSON <xref target="RFC7159" /> data structures defined in
this specification MAY contain extension parameters that are not
defined in this specification. Any entity receiving or retrieving a
JSON data structure SHOULD ignore extension parameters it is unable to
understand. Extension names that are unprotected from collisions are
outside the scope of this specification.</t>
</section>
<section anchor="roles" title="Roles">
<t>The UMA grant enhances the OAuth definitions of entities in order
to accommodate the requesting party role.<list style="hanging">
<t hangText="resource owner"><vspace />An entity capable of
granting access to a protected resource, the "user" in
User-Managed Access. The resource owner MAY be an end-user
(natural person) or MAY be a non-human entity treated as a person
for limited legal purposes (legal person), such as a
corporation.</t>
<t hangText="requesting party"><vspace />A natural or legal person
that uses a client to seek access to a protected resource. The
requesting party may or may not be the same party as the resource
owner.</t>
<t hangText="client"><vspace />An application that is capable of
making requests for protected resources with the resource owner's
authorization and on the requesting party's behalf.</t>
<t hangText="resource server"><vspace />A server that hosts
resources on a resource owner's behalf and is capable of accepting
and responding to requests for protected resources.</t>
<t hangText="authorization server"><vspace />A server that
protects, on a resource owner's behalf, resources hosted at a
resource server.</t>
</list></t>
</section>
<section anchor="high-level-flow" title="Abstract Flow">
<t>The UMA grant enhances the abstract protocol flow of OAuth.</t>
<t><xref target="protocol-flow" /> shows an example flow. The steps
and artifacts chosen in this figure show a high degree of variety for
illustration purposes; for example, while both claims pushing and
interactive claims gathering are shown, both might not be used in a
single scenario.</t>
<figure anchor="protocol-flow" title="Example Flow">
<artwork><![CDATA[rrequesting authorization resource resource
party client server server owner
| | | | |
| | |Set policy| |
| | |conditions (anytime)|
| | |<- - - - - - - - - -|
| |Resource request (no access token) | |
| |------------------------------------->| |
| |401 response with new permission | |
| |ticket, authz server location | |
| |<-------------------------------------| |
| |Access token (RPT) request | | |
| |with permission ticket, | | |
| |claim token (push claims) | | |
| |-------------------------->| | |
| | +----|Authz | |
| | +--->|assessment| |
| |403 response with rotated | | |
| |permission ticket, | | |
| |need_info error, | | |
| |redirect_user hint | | |
| |<--------------------------| | |
|Redirect | | | |
|user with | | | |
|permission | | | |
|ticket | | | |
|<-----------| | | |
|Follow redirect to authz server | | |
|--------------------------------------->| | |
|Interactive claims gathering | | |
|<- - - - - - - - - - - - - - - - - - - >| | |
|Redirect back with rotated permission | | |
|ticket | | |
|<---------------------------------------| | |
|Follow | | | |
|redirect | | | |
|to client | | | |
|----------->| | | |
| |RPT request with permission| | |
| |ticket | | |
| |-------------------------->| | |
| | +----|Authz | |
| | +--->|assessment| |
| |Response with RPT and PCT | | |
| |<--------------------------| | |
| |Resource request with RPT | | |
| |------------------------------------->| |
| |Protected resource | | |
| |<-------------------------------------| |
]]></artwork>
</figure>
<t>Following are key concepts relevant to this specification:<list
style="hanging">
<t hangText="requesting party token (RPT)">An access token
associated with the UMA grant. An RPT is unique to a requesting
party, client, authorization server, resource server, and resource
owner.</t>
<t hangText="permission">Authorized access to a particular
resource with some number of scopes bound to that resource. A
permission ticket represents some number of requested permissions.
An RPT represents some number of granted permissions. Permissions
are part of the authorization server's process and are opaque to
the client.</t>
<t hangText="permission ticket">A correlation handle representing
requested permissions that is created and maintained by the
authorization server, initially passed to the client by the
resource server, and presented by the client at the token endpoint
and during requesting party redirects.</t>
<t hangText="persisted claims token (PCT)">A correlation handle
issued by an authorization server that represents a set of claims
collected during one authorization process, available for a client
to use in attempting to optimize a future authorization
process.</t>
<t hangText="claim">A statement of the value or values of one or
more attributes of an entity. The authorization server typically
needs to collect and assess one or more claims of the requesting
party or client against policy conditions as part of protecting a
resource. The two methods available for UMA claims collection are
claims pushing and interactive claims gathering. Note: Claims
collection might involve authentication for unique user
identification, but depending on policy conditions might
additionally or instead involve the collection of non-uniquely
identifying attributes, authorization for some action (for
example, see <xref target="redirect-back" />), or other statements
of agreement.</t>
<t hangText="claim token">A package of claims provided directly by
the client to the authorization server through claims pushing.</t>
<t hangText="authorization process">The process through which the
authorization server determines whether it should issue an RPT to
the client on the requesting party's behalf, potentially based on
a variety of inputs (see <xref
target="authorization-process" />).</t>
</list></t>
<t>Note: How the client acquired knowledge of the resource server's
interface and the specific endpoint of the desired protected resource
is outside the scope of this specification. For example, the resource
server might have a programmatic API or it might serve up simple web
pages, and the resource owner might have advertised the endpoint
publicly on a blog or other website, listed it in a discovery service,
or emailed a link to a particular intended requesting party.</t>
<section anchor="authorization-process" title="Authorization Process">
<t>The authorization process involves the following activities:<list
style="symbols">
<t>Claims collection. Claims pushing by a client is defined in
<xref target="uma-grant-type" />, and interactive claims
gathering with an end-user requesting party is defined in <xref
target="claim-redirect" />.</t>
<t>Authorization assessment (as defined in <xref
target="authorization-assessment" />). Authorization assessment
involves the authorization server assembling and evaluating
policy conditions, scopes, claims, and any other relevant
information sourced outside of UMA claims collection flows, in
order to mitigate access authorization risk.</t>
<t>Authorization results determination (as defined in <xref
target="authorization-assessment" />). The authorization server
either returns a success code (as defined in <xref
target="give-rpt" />), an RPT, and an optional PCT, or an error
code (as defined in <xref target="authorization-failure" />). If
the error code is <spanx style="verb">need_info</spanx> or
<spanx style="verb">request_submitted</spanx>, the authorization
server provides a permission ticket, giving the client an
opportunity to continue within the same authorization process
(including engaging in further claims collection). In the case
of a <spanx style="verb">need_info</spanx> error, the
authorization server can provide hints about what the client
should do next.</t>
</list></t>
<t>Different choices of claims collection methods, other inputs to
authorization assessment, and <spanx style="verb">need_info</spanx>
error hints might be best suited for different deployment
ecosystems. For example, where no pre-established relationship is
expected between the resource owner's authorization server and the
requesting party, initial requesting party redirection might be a
useful pattern, at which point the authorization server might either
authenticate the requesting party locally or serve as a relying
party for a remote identity provider. Where a common authorization
server functions as an identity provider for all resource owners and
requesting parties, having the client push claim tokens sourced from
that central server itself with a pre-negotiated format and contents
might be a useful pattern.</t>
</section>
</section>
</section>
<section anchor="as-config" title="Authorization Server Metadata">
<t>The authorization server supplies metadata in a discovery document to
declare its endpoints. The client uses this discovery document to
discover these endpoints for use in the flows defined in <xref
target="protocol-flow-details-sec" />.</t>
<t>The authorization server MUST make a discovery document available.
The structure of the discovery document MUST conform to that defined in
<xref target="OAuthMeta" />. The discovery document MUST be available at
an endpoint formed by concatenating the string <spanx
style="verb">/.well-known/uma2-configuration</spanx> to the <spanx
style="verb">issuer</spanx> metadata value defined in <xref
target="OAuthMeta" />, using the well-known URI syntax and semantics
defined in <xref target="RFC5785" />. In addition to the metadata
defined in <xref target="OAuthMeta" />, this specification defines the
following metadata for inclusion in the discovery document:<list
hangIndent="6" style="hanging">
<t hangText="claims_interaction_endpoint"><vspace />OPTIONAL. A
static endpoint URI at which the authorization server declares that
it interacts with end-user requesting parties to gather claims. If
the authorization server also provides a claims interaction endpoint
URI as part of its <spanx style="verb">redirect_user</spanx> hint in
a <spanx style="verb">need_info</spanx> response to a client on
authorization failure (see <xref target="authorization-failure" />),
that value overrides this metadata value. Providing the static
endpoint URI is useful for enabling interactive claims gathering
prior to any pushed-claims flows taking place, so that, for example,
it is possible to gather requesting party authorization
interactively for collecting all other claims in a "silent"
fashion.</t>
<t hangText="uma_profiles_supported"><vspace />OPTIONAL. UMA
profiles and extensions supported by this authorization server. The
value is an array of string values, where each string value is a URI
identifying an UMA profile or extension. As discussed in <xref
target="profiles" />, an authorization server supporting a profile
or extension related to UMA SHOULD supply the specification's
identifying URI (if any) here.</t>
</list></t>
<t>If the authorization server supports dynamic client registration, it
MUST allow client applications to register <spanx
style="verb">claims_redirect_uri</spanx> metadata, as defined in <xref
target="claim-redirect" />.</t>
</section>
<section anchor="protocol-flow-details-sec" title="Flow Details">
<section anchor="client-attempts-tokenless-access"
title="Client Requests Resource Without Providing an Access Token">
<t>The client requests a protected resource without providing any
access token.</t>
<t>Note: This process does not assume that any relevant policy
conditions have already been defined at the authorization server.</t>
<t>For an example of how the resource server can put resources under
the protection of an authorization server, see <xref
target="UMAFedAuthz" />.</t>
<figure>
<preamble>Example of a client request at a protected resource
carrying no token:</preamble>
<artwork><![CDATA[GET /users/alice/album/photo.jpg HTTP/1.1
Host: photoz.example.com
...
]]></artwork>
</figure>
</section>
<section anchor="rs-tokenless-response"
title="Resource Server Responds to Client's Tokenless Access Attempt">
<t>The resource server responds to the client's tokenless resource
request.</t>
<t>The resource server MUST obtain a permission ticket from the
authorization server to provide in its response, but the means of
doing so is outside the scope of this specification. For an example of
how the resource server can obtain the permission ticket, see <xref
target="UMAFedAuthz" />.</t>
<t>The process of choosing what permissions to request from the
authorization server may require interpretation and mapping of the
client's resource request. The resource server SHOULD request a set of
permissions with scopes that is reasonable for the client's resource
request.</t>
<t>Note: In order for the resource server to know which authorization
server to approach for the permission ticket and on which resource
owner's behalf, it needs to derive the necessary information using
cues provided by the structure of the API where the resource request
was made, rather than by an access token. Commonly, this information
can be passed through the URI, headers, or body of the client's
request. Alternatively, the entire interface could be dedicated to the
use of a single resource owner and protected by a single authorization
server.</t>
<t>See <xref target="ticket-management" /> for permission ticket
security considerations.</t>
<section anchor="permission-success-to-client"
title="Resource Server Response to Client on Permission Request Success">
<t>If the resource server is able to provide a permission ticket
from the authorization server, it responds to the client by
providing a <spanx style="verb">WWW-Authenticate</spanx> header with
the authentication scheme <spanx style="verb">UMA</spanx>, with the
<spanx style="verb">issuer</spanx> URI from the authorization
server's discovery document in an <spanx style="verb">as_uri</spanx>
parameter and the permission ticket in a <spanx
style="verb">ticket</spanx> parameter.</t>
<figure>
<preamble>For example:</preamble>
<artwork><![CDATA[HTTP/1.1 401 Unauthorized
WWW-Authenticate: UMA realm="example",
as_uri="https://as.example.com",
ticket="016f84e8-f9b9-11e0-bd6f-0021cc6004de"
...
]]></artwork>
</figure>
</section>
<section anchor="permission-failure-to-client"
title="Resource Server Response to Client on Permission Request Failure">
<t>If the resource server is unable to provide a permission ticket
from the authorization server, then it includes a header of the
following form in its response to the client: <spanx
style="verb">Warning: 199 - "UMA Authorization Server
Unreachable"</spanx>.</t>
<figure>
<preamble>For example:</preamble>
<artwork><![CDATA[HTTP/1.1 403 Forbidden
Warning: 199 - "UMA Authorization Server Unreachable"
...
]]></artwork>
</figure>
<t>Without an authorization server location and permission ticket,
the client is unable to continue.</t>
</section>
</section>
<section anchor="seek-authorization"
title="Client Seeks RPT on Requesting Party's Behalf">
<t>The client seeks issuance of an RPT from the token endpoint. Using
this endpoint is one option for the client in beginning to engage with
the authorization server as part of an authorization process. The
other option is to redirect the requesting party for interactive
claims gathering (see <xref target="claim-redirect" />).</t>
<t>This process assumes that:<list style="symbols">
<t>The client has obtained a permission ticket and an
authorization server location from the resource server.</t>
<t>The client has retrieved the authorization server's discovery
document as needed.</t>
<t>The client has obtained OAuth client credentials from the
authorization server, either dynamically through <xref
target="RFC7591" /> or <xref target="OIDCDynClientReg" />, or
alternatively through a static process, and is prepared to
authenticate itself to the token endpoint if appropriate.</t>
</list></t>
<section anchor="uma-grant-type"
title="Client Request to Authorization Server for RPT">
<t>The client makes a request to the token endpoint by sending the
following parameters:<list style="hanging">
<t hangText="grant_type">REQUIRED. MUST be the value <spanx
style="verb">urn:ietf:params:oauth:grant-type:uma-ticket</spanx>.</t>
<t hangText="ticket">REQUIRED. The most recent permission ticket
received by the client as part of this authorization
process.</t>
<t hangText="claim_token">OPTIONAL. If this parameter is used,
it MUST appear together with the <spanx
style="verb">claim_token_format</spanx> parameter. A string
containing directly pushed claim information in the indicated
format. It MUST be base64url encoded unless specified otherwise
by the claim token format. The client MAY provide this
information on both first and subsequent requests to this
endpoint. The client and authorization server together might
need to establish proper audience restrictions for the claim
token prior to claims pushing.</t>
<t hangText="claim_token_format">OPTIONAL. If this parameter is
used, it MUST appear together with the <spanx
style="verb">claim_token</spanx> parameter. A string specifying
the format of the claim token in which the client is directly
pushing claims to the authorization server. The string MAY be a
URI. Examples of potential types of claim token formats are
<xref target="OIDCCore" /> ID Tokens and SAML assertions.</t>
<t hangText="pct">OPTIONAL. If the authorization server
previously returned a PCT along with an RPT, the client MAY
include the PCT in order to optimize the process of seeking a
new RPT. Given that some claims represented by a PCT are likely
to contain identity information about a requesting party, a
client supplying a PCT in its RPT request MUST make a best
effort to ensure that the requesting party using the client now
is the same as the requesting party that was associated with the
PCT when it was issued. The client MAY use the PCT for the same
requesting party when seeking an RPT for a resource different
from the one sought when the PCT was issued, or a protected
resource at a different resource server entirely. See <xref
target="sec-consid-pct" /> for additional PCT security
considerations. See <xref target="give-rpt" /> for the form of
the authorization server's response with a PCT.</t>
<t hangText="rpt">OPTIONAL. Supplying an existing RPT gives the
authorization server the option of upgrading that RPT instead of
issuing a new one (see <xref target="rpt-upgrading" /> for more
about this option).</t>
<t hangText="scope">OPTIONAL. A string of space-separated values
representing requested scopes. For the authorization server to
consider any requested scope in its assessment, the client MUST
have pre-registered the same scope with the authorization
server. The client should consult the resource server's API
documentation for details about which scopes it can expect the
resource server's initial returned permission ticket to
represent as part of the authorization assessment (see <xref
target="authorization-assessment" />).</t>
</list></t>
<figure>
<preamble>Example of a request message with no optional parameters
(line breaks are shown only for display convenience):</preamble>
<artwork><![CDATA[POST /token HTTP/1.1
Host: as.example.com
Authorization: Basic jwfLG53^sad$#f
...
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Auma-ticket
&ticket=016f84e8-f9b9-11e0-bd6f-0021cc6004de
]]></artwork>
</figure>
<figure>
<preamble>Example of a request message that includes an existing
RPT for upgrading, a scope being sought that was previously
registered with the authorization server, and a PCT and a claim
token for consideration in the authorization process:</preamble>
<artwork><![CDATA[POST /token HTTP/1.1
Host: as.example.com
Authorization: Basic jwfLG53^sad$#f
...
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Auma-ticket
&ticket=016f84e8-f9b9-11e0-bd6f-0021cc6004de
&claim_token=eyj0...
&claim_token_format=http%3A%2F%2Fopenid.net%2Fspecs%2Fopenid-connect-core-1_0.html%23IDToken
&pct=c2F2ZWRjb25zZW50
&rpt=sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv
&scope=read
]]></artwork>
</figure>
<t>This specification provides a means to define profiles of claim
token formats for use with UMA (see <xref target="profiles" />). The
authorization server SHOULD document the profiles it supports in its
discovery document.</t>
</section>
<section anchor="claim-redirect"
title="Client Redirect of Requesting Party to Authorization Server for Interactive Claims-Gathering">
<t>The client redirects an end-user requesting party to the
authorization server's claims interaction endpoint for one or more
interactive claims-gathering processes as the authorization server
requires. These can include direct interactions, such as account
registration and authentication local to the authorization server as
an identity provider, filling out a questionnaire, or asking the
user to authorize persistent storage of any collected claims on a
persistent basis to optimize future authorization processes; this
last example could potentially be associated with the authorization
server's subsequent issuance of a PCT. Interactions could also
involve further redirection, for example, for federated (such as
social) authentication at a remote identity provider, and other
federated claims gathering.</t>
<t>Redirecting the requesting party to the authorization server is
one option for the client in beginning to engage with the
authorization server as part of an authorization process. The client
might, for example, have initiated redirection on receiving an
authorization failure response containing a <spanx
style="verb">redirect_user</spanx> hint (see <xref
target="authorization-failure" />). The other option is to seek
issuance of an RPT at the token endpoint (see <xref
target="seek-authorization" />).</t>
<t>If the client intends to redirect an end-user requesting party to
the claims interaction endpoint before approaching the token
endpoint, this process assumes, in addition to the other assumptions
in <xref target="seek-authorization" />, that the authorization
server has statically declared its claims interaction endpoint in
its discovery document.</t>
<t>The client constructs the request URI by adding the following
parameters to the query component of the claims interaction endpoint
URI using the <spanx
style="verb">application/x-www-form-urlencoded</spanx> format:<list
style="hanging">
<t hangText="client_id">REQUIRED. The client's identifier issued
by the authorization server.</t>
<t hangText="ticket">REQUIRED. The most recent permission ticket
received by the client as part of this authorization
process.</t>
<t hangText="claims_redirect_uri">REQUIRED if the client has
pre-registered multiple claims redirection URIs or has
pre-registered no claims redirection URI; OPTIONAL only if the
client has pre-registered a single claims redirection URI. The
URI to which the client wishes the authorization server to
direct the requesting party's user agent after completing its
interaction. The URI MUST be absolute, MAY contain an <spanx
style="verb">application/x-www-form-urlencoded</spanx>-formatted
query parameter component that MUST be retained when adding
additional parameters, and MUST NOT contain a fragment
component. The client SHOULD pre-register its <spanx
style="verb">claims_redirect_uri</spanx> with the authorization
server, and the authorization server SHOULD require all clients
to pre-register their claims redirection endpoints. Claims
redirection URIs are different from the redirection URIs defined
in <xref target="RFC6749" /> in that they are intended for the
exclusive use of requesting parties and not resource owners.
Therefore, authorization servers MUST NOT redirect requesting
parties to pre-registered redirection URIs defined in <xref
target="RFC6749" /> unless such URIs are also pre-registered
specifically as claims redirection URIs. If the URI is
pre-registered, this URI MUST exactly match one of the
pre-registered claims redirection URIs, with the matching
performed as described in Section 6.2.1 of <xref
target="RFC3986" /> (Simple String Comparison).</t>
<t hangText="state">RECOMMENDED. An opaque value used by the
client to maintain state between the request and callback. The
authorization server includes this value when redirecting the
user agent back to the client. The use of this parameter is for
preventing cross-site request forgery (see <xref
target="csrf" /> for further security information).</t>
</list></t>
<figure>
<preamble>Example of a request issued by a client application
(line breaks are shown only for display convenience):</preamble>
<artwork><![CDATA[GET /rqp_claims?client_id=some_client_id
&ticket=016f84e8-f9b9-11e0-bd6f-0021cc6004de
&state=abc
&claims_redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fredirect_claims HTTP/1.1
Host: as.example.com
]]></artwork>
</figure>
</section>
<section anchor="redirect-back"
title="Authorization Server Redirect of Requesting Party Back to Client After Interactive Claims-Gathering">
<t>At the conclusion of a successful interaction with the requesting
party, the authorization server returns the requesting party to the
client, adding the following parameters to the query component of
the claims redirection URI using the <spanx
style="verb">application/x-www-form-urlencoded</spanx> format:<list
style="hanging">
<t hangText="ticket">REQUIRED. A permission ticket that allows
the client to make further requests to the authorization server
during this authorization process. The value MUST NOT be the
same as the one the client used to make its request.</t>
<t hangText="state">OPTIONAL. The same state value that the
client provided in the request. It MUST be present if and only
if the client provided it (see <xref target="csrf" /> for
further security information).</t>
</list></t>
<t>Note: Interactive claims-gathering processes are outside the
scope of this specification. The purpose of the interaction is for
the authorization server to gather information for its own
authorization assessment purposes. This redirection does not involve
sending any of the information back to the client.</t>
<t>The authorization server MAY use interactive claims-gathering to
request authorization from the requesting party for persisting
claims across authorization processes. Such persisted claims will be
represented by a PCT issued to the client in a subsequent step.</t>
<t>The client MUST ignore unrecognized response parameters. If the
request fails due to a missing, invalid, or mismatching claims
redirection URI, or if the client identifier is missing or invalid,
the authorization server SHOULD inform the requesting party of the
error and MUST NOT automatically redirect the user agent to the
invalid redirection URI.</t>
<t>If the request fails for reasons other than a missing or invalid
claims redirection URI, the authorization server informs the client
by adding an <spanx style="verb">error</spanx> parameter to the
query component of the claims redirection URI as defined in Section
4.1.2.1 of <xref target="RFC6749" />.</t>
<figure>
<preamble>Example of a response issued by an authorization server
(line breaks are shown only for display convenience):</preamble>
<artwork><![CDATA[HTTP/1.1 302 Found
Location: https://client.example.com/redirect_claims?
ticket=cHJpdmFjeSBpcyBjb250ZXh0LCBjb250cm9s&state=abc
]]></artwork>
</figure>
</section>
<section anchor="authorization-assessment"
title="Authorization Assessment and Results Determination">
<t>When the authorization server has received a request for an RPT
from a client (see <xref target="seek-authorization" />), it
assesses whether the client is authorized to receive the requested
RPT and determines the results.</t>
<t>The authorization server MUST apply the following conceptual
authorization assessment calculation in determining authorization
results. Note: As this calculation is internal to authorization
server operations, its particulars are outside the scope of this
specification.</t>
<t>In this assessment calculation, let a set called
<spanx>ClientRegistered</spanx> stand for the scopes for which the
client pre-registered at the authorization server, either
dynamically or through some static process. Let a set called
<spanx>ClientRequested</spanx> stand for the scopes the client most
recently requested at the token endpoint. Let a set called
<spanx>PermissionTicket</spanx> stand for the scopes associated with
the permission ticket presented by the client at the token endpoint.
<list style="numbers">
<t>Determine the set of requested scopes as follows:
<spanx>RequestedScopes = PermissionTicket ∪
(ClientRequested ∩ ClientRegistered)</spanx>. Treat each
scope in <spanx>(ClientRequested ∩
ClientRegistered)</spanx> as applying to all matching
resource-bound scopes in <spanx>PermissionTicket</spanx>.</t>
<t>Determine all operative policy conditions, and claims and
other relevant information serving as input to them, for each
scope assocated with <spanx>RequestedScopes</spanx> and evaluate
its authorization status.</t>
<t>For each scope that passes the evaluation, add it to a set
called <spanx>CandidateGrantedScopes</spanx>.</t>
</list></t>
<t>Note: Claims and other information gathered during one
authorization process may become out of date in terms of their
relevance for future authorization processes. The authorization
server is responsible for managing such relevance wherever
information associated with a PCT, or other persistently stored
information, is used as input to authorization, including policy
conditions themselves.</t>
<t>Note: Since the authorization server's policy expression and
evaluation capabilities are outside the scope of this specification,
any one implementation might take a simple or arbitrarily complex
form, with varying abilities to combine or perform calculations over
claims and their values. For example, logical operations such as
accepting "either claim value A or claim value B" as correct might
be possible.</t>
<t>In the authorization results phase, the authorization server
examines the <spanx>CandidateGrantedScopes</spanx> set to determine
whether to issue an RPT and what permissions should be associated
with it.<list style="symbols">
<t>If <spanx>CandidateGrantedScopes = RequestedScopes</spanx>,
then the authorization server subsequently responds with a
success code and issues an RPT.</t>
<t>If <spanx>CandidateGrantedScopes <
RequestedScopes</spanx>, the authorization server subsequently
issues either an RPT containing
<spanx>CandidateGrantedScopes</spanx>, or one of the error
codes. The reason for the two options is that granting only
partial scopes might not be useful for the client's and
requesting party's purposes in seeking authorization for
access.</t>
</list></t>
<t>Note: It is not an error for the client to have requested a scope
for which it did not pre-register because
<spanx>RequestedScopes</spanx> might include that same scope,
requested on the client's behalf by the resource server when
obtaining the permission ticket. However, if such a scope were
requested only by the client at the token endpoint, that scope would
not be included in <spanx>RequestedScopes</spanx>.</t>
<t>The following example illustrates authorization assessment and
partial results: <list style="symbols">
<t>Assume two resources at a resource server, <spanx
style="verb">photo1</spanx> with scopes <spanx
style="verb">view</spanx>, <spanx style="verb">print</spanx>,
and <spanx style="verb">download</spanx> and <spanx
style="verb">photo2</spanx> with scopes <spanx
style="verb">view</spanx>, <spanx style="verb">print</spanx>,
<spanx style="verb">download</spanx>, and <spanx
style="verb">link</spanx>.</t>
<t>The resource owner has set policy conditions that allow
access to <spanx style="verb">photo1</spanx> only by requesting
parties that can provide claims proving they are family members,
and that allow access to <spanx style="verb">photo2</spanx> only
by requesting parties that can provide claims saying they agree
not to download, sell, or market any photo.</t>
<t>The client has pre-registered with the authorization server
for <spanx style="verb">download</spanx> scope (so
<spanx>ClientRegistered</spanx> contains <spanx
style="verb">download</spanx>).</t>
<t>The client requests a resource, in what the resource server
interprets as an attempt for <spanx style="verb">view</spanx>
access to <spanx style="verb">photo1</spanx>.</t>
<t>The nature of the resource server's API results in the
resource server's permission ticket from the authorization
server representing a request for <spanx
style="verb">view</spanx> and <spanx style="verb">print</spanx>
scopes for <spanx style="verb">photo1</spanx> on the client's
behalf (so <spanx>PermissionTicket</spanx> contains <spanx
style="verb">view</spanx> and <spanx
style="verb">print</spanx>).</t>
<t>The client requests <spanx style="verb">download</spanx>
scope on the requesting party's behalf while requesting an RPT
from the authorization server (so <spanx>ClientRequested</spanx>
contains <spanx style="verb">download</spanx>).</t>
<t>The authorization server determines that
<spanx>RequestedScopes</spanx> contains <spanx
style="verb">view</spanx>, <spanx style="verb">print</spanx>,
and <spanx style="verb">download</spanx>.</t>
<t>Based on the authorization server's evaluation of policy
conditions associated with these scopes,
<spanx>CandidateGrantedScopes</spanx> contains only <spanx
style="verb">view</spanx> and <spanx style="verb">print</spanx>
and not <spanx style="verb">download</spanx> (the dynamically
requested scope), which is less than in
<spanx>RequestedScopes</spanx>.</t>
<t>The authorization server has a choice whether to issue an RPT
in this case.</t>
</list></t>
<t>See <xref target="default-deny" /> for a discussion of
authorization implementation threats.</t>
</section>
<section anchor="give-rpt"
title="Authorization Server Response to Client on Authorization Success">
<t>If the authorization server's assessment process results in
issuance of permissions, it issues the RPT with which it has
associated the permissions by using the successful response form
defined in Section 5.1 of <xref target="RFC6749" />.</t>
<t>The authorization server MAY return a refresh token. See <xref
target="refresh" /> for more information about refreshing an
RPT.</t>
<t>The authorization server MAY add the following parameters to its
response:<list style="hanging">
<t hangText="pct">OPTIONAL. A correlation handle representing
claims and other information collected during this authorization
process, which the client is able to present later in order to
optimize future authorization processes on behalf of a
requesting party. The PCT MUST be unguessable by an attacker.
The PCT MUST NOT disclose claims from the requesting party
directly to possessors of the PCT. Instead, such claims SHOULD
be associated by reference to the PCT or expressed in an
encrypted format that can be decrypted only by the authorization
server that issued the PCT. See <xref target="claim-redirect" />
for more information about the end-user requesting party
interaction option. See <xref target="sec-consid-pct" /> for
additional PCT security considerations.</t>
<t hangText="upgraded">OPTIONAL. Boolean value. If the client
submits an RPT in the request and the authorization server
includes the permissions of the RPT from the request as part of
the newly issued RPT, then it MUST set this value to <spanx
style="verb">true</spanx>. If it sets the value to <spanx
style="verb">false</spanx> or the value is absent, the client
MUST act as if the newly issued RPT does not include the
permissions associated with the RPT from the request. (See <xref
target="rpt-upgrading" />.)</t>
</list></t>
<t>The authorization server MAY include any of the parameters
defined in Section 5.1 of <xref target="RFC6749" /> on its response,
except that it SHOULD NOT include the <spanx
style="verb">scope</spanx> parameter. This is because for an RPT's
permissions, each scope is associated with a specific resource, even
though this association is opaque to the client. Note: The outcome
of authorization assessment may result in expiration periods for
RPTs, permissions, and refresh tokens that can affect the client's
later requests for refreshing the RPT.</t>
<figure>
<preamble>Example:</preamble>
<artwork><![CDATA[HTTP/1.1 200 OK
Content-Type: application/json
...
{
"access_token":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
"token_type":"Bearer"
}
]]></artwork>
</figure>
<figure>
<preamble>Example with a PCT in the response:</preamble>
<artwork><![CDATA[HTTP/1.1 200 OK
Content-Type: application/json
...
{
"access_token":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
"token_type":"Bearer",
"pct":"c2F2ZWRjb25zZW50"
}
]]></artwork>
</figure>
<section anchor="rpt-upgrading"
title="Authorization Server Upgrades RPT">
<t>The authorization server MAY implement RPT upgrading. The
authorization server SHOULD document its practices regarding RPT
upgrades and to act consistently with respect to RPT upgrades so
as to enable clients to manage received RPTs efficiently.</t>
<t>If the authorization server has implemented RPT upgrading, the
client has submitted an RPT in its request, and the result is
success, the authorization server adds the permissions from the
client's previous RPT to the RPT it is about to issue, setting the
value of <spanx style="verb">upgraded</spanx> in its response
containing the upgraded RPT to <spanx
style="verb">true</spanx>.</t>
<t>If the authorization server is upgrading an RPT, and the RPT
string is new rather than repeating the RPT provided by the client
in the request, then the authorization server SHOULD revoke the
existing RPT, if possible, and the client MUST discard its
previous RPT. If the authorization server does not upgrade the RPT
but issues a new RPT, the client MAY retain the existing RPT.</t>
<figure>
<preamble>Example with <spanx style="verb">upgraded</spanx> in
the response:</preamble>
<artwork><![CDATA[HTTP/1.1 200 OK
Content-Type: application/json
...
{
"access_token":"sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
"token_type":"Bearer",
"upgraded":true
}
]]></artwork>
</figure>
</section>
</section>
<section anchor="authorization-failure"
title="Authorization Server Response to Client on Authorization Failure">
<t>If the client's request to the token endpoint is insufficient for
granting an RPT, the authorization server responds using an error
code and corresponding HTTP status code.<list style="hanging">
<t hangText="invalid_grant">If the provided permission ticket
was not found at the authorization server, or the provided
permission ticket has expired, or the client is not authorized
to have these permissions added, or any other original reasons
to use this error response are found as defined in <xref
target="RFC6749" />, the authorization server responds with the
HTTP 400 (Bad Request) status code.</t>
<t hangText="invalid_scope">At least one of the scopes included
in the request does not match an available scope for any of the
resources associated with requested permissions for the