forked from mrtopf/UMA-Specifications
-
Notifications
You must be signed in to change notification settings - Fork 21
/
oauth-uma-grant.xml
2074 lines (1752 loc) · 100 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="recommendation" 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>HSBC</organization>
<address>
<email>maciej.p.machulak@hsbc.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="7" month="January" year="2018" />
<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 and financial information aggregation company Decide
Account, all using different client applications. Each of her bank
accounts is a protected resource, and two different scopes of access she
can control on them are viewing account data and accessing payment
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 illustrating
a variety of messaging paths and artifacts. The resource owner entity
and its communications with the authorization server are included for
completeness, although policy condition setting is outside the scope
of this specification and communications among the other four entities
are asynchrjonous with respect to resource owner actions. Further,
although both claims pushing and interactive claims gathering are
shown, both might not typically be used in one scenario.</t>
<figure anchor="protocol-flow" title="Example Flow">
<artwork><![CDATA[requesting authorization resource resource
party client server server owner
| | | | |
| | |Set policy| |
| | |conditions (anytime)|
| | |<- - - - - - - - - -|
| |Resource request (no access token) | |
| |------------------------------------->| |
| |401 response with initial permission | |
| |ticket, authz server location | |
| |<-------------------------------------| |
| |Access token (RPT) request | | |
| |with permission ticket, | | |
| |claim token (push claims) | | |
| |-------------------------->| | |
| | +----|Authz | |
| | +--->|assessment| |
| |403 response with new | | |
| |permission ticket, | | |
| |need_info error, | | |
| |redirect_user hint | | |
| |<--------------------------| | |
|Redirect | | | |
|user with | | | |
|permission | | | |
|ticket | | | |
|<-----------| | | |
|Follow redirect to authz server | | |
|--------------------------------------->| | |
|Interactive claims gathering | | |
|<- - - - - - - - - - - - - - - - - - - >| | |
|Redirect back with new 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, as
illustrated in the figure:<list style="hanging">
<t hangText="requesting party token (RPT)">An OAuth 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="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, based on a variety of
inputs. A key component of the process is authorization
assessment. (See <xref target="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="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>
</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).</t>
</list></t>
<t>Different choices of claims collection methods, other inputs to
authorization assessment, and error codes 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, for example, for
gathering authorization for subsequent claim pushing (see <xref
target="claim-redirect" />).</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" />, using the following metadata field:<list
hangIndent="6" style="hanging">
<t hangText="claims_redirect_uris"><vspace />OPTIONAL. Array of one
or more claims redirection URIs.</t>
</list></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
without providing an access 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.</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 a client identifier or a full set of
client credentials as appropriate, either statically or
dynamically (for example, through <xref target="RFC7591" /> or
<xref target="OIDCDynClientReg" />). This grant works with clients
of both confidential and public types.</t>
</list></t>
<t>Initiation of this process has two options. One option is for the
client to request an RPT from the token endpoint immediately, as
defined in <xref target="uma-grant-type" />. Claim pushing is
available at this endpoint. The other option, if the authorization
server’s discovery document statically provided a claims
interaction endpoint, is for the client to redirect the requesting
party immediately to that endpoint for interactive claims gathering,
as defined in <xref target="claim-redirect" />.</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. See <xref target="trust-push" />
and <xref target="rqp-privacy" /> for security and privacy
considerations regarding pushing of claims.</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. See <xref target="trust-push" /> and
<xref target="rqp-privacy" /> for additional security and
privacy considerations regarding persistence of claims. 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-exposure" /> 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 (which MAY
be expired) 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 been pre-registered for 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 subsequent collection of claims by interaction or
pushing, and persistent storage of such claims (for example, as
associated with 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. See <xref target="trust-push" /> and <xref
target="rqp-privacy" /> for security and privacy considerations
regarding pushing and persistence of claims.</t>
<t>The client might have initiated redirection immediately on
receiving an initial permission ticket from the resource server, or,
for example, in response to receiving a <spanx
style="verb">redirect_user</spanx> hint in a <spanx
style="verb">need_info</spanx> error (see <xref
target="authorization-failure" />).</t>
<t>In order for the client to redirect the requesting party
immediately on receiving the initial permission ticket from the
resource server, this process assumes 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,
and MUST require public clients, to pre-register their claims
redirection endpoints (see <xref target="as-config" />). 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
&claims_redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fredirect_claims
&state=abc 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 as defined in <xref target="uma-grant-type" />, 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. <list style="numbers">
<t>Assemble a set called <spanx>RegisteredScopes</spanx>
containing the scopes for which the client is pre-registered
(either dynamically or through some static process) at the
authorization server. Assemble a set called
<spanx>RequestedScopes</spanx> containing the scopes the client
most recently requested at the token endpoint. The permission
ticket that was presented by the client at the token endpoint
represents some number of resources, each with some number of
scopes; for each of those resources, assemble a set called
<spanx>TicketScopes(resource)</spanx> containing the scopes
associated with that resource.</t>
<t>For each resource in the permission ticket, determine a final
set of requested scopes as follows:
<spanx>RequestedScopes(resource)={TicketScopes(resource) ∪
{RegisteredScopes ∩ RequestedScopes}}</spanx>. Treat each
scope in <spanx>{RegisteredScopes ∩
RequestedScopes}</spanx> as matching any available scope
associated with a resource found in the permission ticket.</t>
<t>For each <spanx>RequestedScopes(resource)</spanx> set,
determine all operative policy conditions, and claims and other
relevant information serving as input to them, and evaluate its
authorization status.</t>
<t>For each scope in <spanx>RequestedScopes(resource)</spanx>
that passes the evaluation, add it to a set called
<spanx>CandidateGrantedScopes(resource)</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 are
possible to implement.</t>
<t>In the authorization results phase, the authorization server
examines each <spanx>CandidateGrantedScopes(resource)</spanx> set to
determine whether to issue an RPT and what permissions should be
associated with it. If all <spanx>RequestedScopes(resource)</spanx>
sets can be granted, then the authorization server subsequently
responds with a success code and issues an RPT containing
<spanx>CandidateGrantedScopes</spanx> for each resource.</t>
<t>Otherwise, the authorization server subsequently issues either an
RPT containing <spanx>CandidateGrantedScopes</spanx> for each
resource, or one of the error codes, as appropriate. 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. The choice of error depends on policy
conditions and the authorization server's implementation choices.
The conditions for the <spanx style="verb">need_info</spanx>, <spanx
style="verb">request_denied</spanx>, and <spanx
style="verb">request_submitted</spanx> error codes are dependent on
authorization assessment and thus these codes might be more likely
than the others to be issued subsequent to such a calculation.</t>
<t>The following example illustrates authorization assessment and
partial results. <list style="symbols">
<t>The resource server has three of the resource owner's
resources of interest to the client and requesting party, <spanx
style="verb">photo1</spanx> and <spanx
style="verb">photo2</spanx> with scopes <spanx
style="verb">view</spanx>, <spanx style="verb">resize</spanx>,
<spanx style="verb">print</spanx>, and <spanx
style="verb">download</spanx>, and <spanx
style="verb">album</spanx> with scopes <spanx
style="verb">view</spanx>, <spanx style="verb">edit</spanx>, and
<spanx style="verb">download</spanx>. It considers <spanx
style="verb">photo1</spanx> and <spanx
style="verb">photo2</spanx> to be logically "inside" <spanx
style="verb">album</spanx>.</t>
<t>Though the exact contents of RPTs, permissions, and
permission requests are opaque to the client, the resource
server has documented its API, available scopes, and permission
requesting practices. For example, if the client requests an
album resource, it expects that the resource server will request
a permission for the album with a scope that approximates the
attempted client operation, but will also request permissions
for all the photos "inside" the album, with <spanx
style="verb">view</spanx> scope only.</t>
<t>The client has a pre-registered scope of <spanx
style="verb">download</spanx> with the authorization server.
This enables the client later to request this scope dynamically
on behalf of its requesting party from the token endpoint. The
authorization server assembles the set
<spanx>RegisteredScopes</spanx> with contents of scope <spanx
style="verb">download</spanx>.</t>
<t>The client requests the album resource in an attempt to edit
it, so the resource server obtains a permission ticket with
three permissions in it: for <spanx style="verb">album</spanx>
with a scope of <spanx style="verb">edit</spanx>, and for <spanx
style="verb">photo1</spanx> and <spanx
style="verb">photo2</spanx>, each with a scope of <spanx
style="verb">view</spanx>. The authorization server assembles
the following sets: <spanx>TicketScopes</spanx>(<spanx
style="verb">album</spanx>) containing <spanx
style="verb">edit</spanx>, <spanx>TicketScopes</spanx>(<spanx
style="verb">photo1</spanx>) containing <spanx
style="verb">view</spanx>, and
<spanx>TicketScopes</spanx>(<spanx style="verb">photo2</spanx>)
containing <spanx style="verb">view</spanx>.</t>
<t>While asking for an RPT at the token endpoint, the client
requests <spanx style="verb">download</spanx> scope on the
requesting party's behalf. The authorization server determines
the contents of the following sets:
<spanx>RequestedScopes</spanx>(<spanx
style="verb">album</spanx>) containing <spanx
style="verb">edit</spanx> and <spanx
style="verb">download</spanx>,
<spanx>RequestedScopes</spanx>(<spanx
style="verb">photo1</spanx>) containing <spanx
style="verb">view</spanx> and <spanx
style="verb">download</spanx>, and
<spanx>RequestedScopes</spanx>(<spanx
style="verb">photo2</spanx>) containing <spanx
style="verb">view</spanx> and <spanx
style="verb">download</spanx>.</t>
<t>The resource owner has set policy conditions that allow
access by this particular requesting party only to <spanx
style="verb">photo1</spanx> and only for <spanx
style="verb">view</spanx> scope.</t>
<t>Based on the authorization server's authorization assessment
calculation, it determines the contents of the following sets:
<spanx>CandidateGrantedScopes</spanx>(<spanx
style="verb">album</spanx>) containing no scopes,
<spanx>CandidateGrantedScopes</spanx>(<spanx
style="verb">photo1</spanx>) containing <spanx
style="verb">view</spanx>, and
<spanx>CandidateGrantedScopes</spanx>(<spanx
style="verb">photo2</spanx>) containing no scopes. This adds up
to less than in the corresponding <spanx>RequestedScopes</spanx>
sets. The authorization server therefore has a choice whether to
issue an RPT (in this case, containing a permission for <spanx
style="verb">photo1</spanx> with <spanx
style="verb">view</spanx> scope) or an error (say, <spanx
style="verb">request_denied</spanx>, or <spanx
style="verb">request_submitted</spanx> if has a way to notify
the resource owner about the album editing resource request and
seek an added policy covering it).</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-exposure" />
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