forked from mrtopf/UMA-Specifications
-
Notifications
You must be signed in to change notification settings - Fork 21
/
oauth-uma-federated-authz.xml
1485 lines (1269 loc) · 66.2 KB
/
oauth-uma-federated-authz.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 RFC7662 SYSTEM "http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7662.xml">
<!ENTITY RFC6750 SYSTEM "http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.6750.xml">
<!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 RFC2616 SYSTEM "http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2616.xml">
<!ENTITY RFC7591 SYSTEM "http://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.7591.xml">
]>
<rfc category="std" docName="oauth-uma-federated-authz" 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="">Federated Authorization for User-Managed Access (UMA)
2.0</title>
<author fullname="Eve Maler" initials="E." role="editor" surname="Maler">
<organization>ForgeRock</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author fullname="Maciej Machulak" initials="M." surname="Machulak">
<organization>HSBC</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<author fullname="Justin Richer" initials="J." surname="Richer">
<organization>Bespoke Engineering</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<date day="7" month="January" year="2018" />
<abstract>
<t>This specification defines a means for an UMA-enabled authorization
server and resource server to be loosely coupled, or federated, in a
secure and authorized resource owner context.</t>
</abstract>
</front>
<middle>
<section anchor="introduction" title="Introduction">
<t>This specification extends and complements <xref target="UMAGrant" />
to loosely couple, or federate, its authorization process. This enables
multiple resource servers operating in different domains to communicate
with a single authorization server operating in yet another domain that
acts on behalf of a resource owner. A service ecosystem can thus
automate resource protection, and the resource owner can monitor and
control authorization grant rules through the authorization server over
time. Further, authorization grants can increase and decrease at the
level of individual resources and scopes.</t>
<t>Building on the example provided in the introduction in <xref
target="UMAGrant" />, bank customer (resource owner) Alice has a bank
account service (resource server), a cloud file system (different
resource server hosted elsewhere), and a dedicated sharing management
service (authorization server) hosted by the bank. She can manage access
to her various protected resources by spouse Bob, accounting
professional Charline, financial information aggregation company
DecideAccount, and neighbor Erik (requesting parties), all using
different client applications. Her bank accounts and her various files
and folders are protected resources, and she can use the same sharing
management service to monitor and control different scopes of access to
them by these different parties, such as viewing, editing, or printing
files and viewing account data or accessing payment functions.</t>
<t>This specification, together with <xref target="UMAGrant" />,
constitutes UMA 2.0. This specification is OPTIONAL to use with the UMA
grant.</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="abstract-flow" title="Abstract Flow">
<t>The UMA grant defined in <xref target="UMAGrant" /> enhances the
abstract protocol flow of OAuth. This specification enhances the UMA
grant by defining formal communications between the UMA-enabled
authorization server and resource server as they act on behalf of the
resource owner, responding to authorization and resource requests,
respectively, by a client that is acting on behalf of a requesting
party.</t>
<t>A summary of UMA 2.0 communications, combining the UMA grant with
federated authorization, is shown in <xref
target="abstract-flow-fig" />.</t>
<figure anchor="abstract-flow-fig"
title="Federated Authorization Enhancements to UMA Grant Flow">
<artwork><![CDATA[ +------------------+
| resource |
+------------manage (out of scope)----| owner |
| +------------------+
| |
| protection |
| API access control
| token (PAT) (out of scope)
| |
v v
+------------+ +----------+------------------+
| | |protection| |
| resource | | API | authorization |
| server |<-----protect-------| (needs | server |
| | | PAT) | |
+------------+ +----------+------------------+
| protected | | UMA |
| resource | | grant |
|(needs RPT) | requesting | (PCT optional) |
+------------+ party token +------------------+
^ (RPT) ^ persisted ^
| | claims |
| push token |
| claim (PCT) |
| tokens interact
| +--------+ for
+------------access--------------------| client | claims
+--------+ gathering
+---------------+
| requesting |
| party |
+---------------+
]]></artwork>
</figure>
<t>This specification uses all of the terms and concepts in <xref
target="UMAGrant" />. This figure introduces the following new
concepts: <list hangIndent="6" style="hanging">
<t hangText="protection API">The API presented by the
authorization server to the resource server, defined in this
specification. This API is OAuth-protected.</t>
<t hangText="protection API access token (PAT)">An <xref
target="RFC6749" /> access token with the scope <spanx
style="verb">uma_protection</spanx>, used by the resource server
as a client of the authorization server's protection API. The
resource owner involved in the UMA grant is the same entity taking
on the role of the resource owner authorizing issuance of the
PAT.</t>
</list></t>
</section>
<section anchor="api-sec"
title="HTTP Usage, API Security, and Identity Context">
<t>This specification is designed for use with HTTP <xref
target="RFC2616" />, and for interoperability and security in the
context of loosely coupled services and applications operated by
independent parties in independent domains. The use of UMA over any
protocol other than HTTP is undefined. In such circumstances, it is
RECOMMENDED to define profiles or extensions to achieve
interoperability among independent implementations (see Section 4 of
<xref target="UMAGrant" />).</t>
<t>The authorization server MUST use TLS protection over its
protection API endpoints, as governed by <xref target="BCP195" />,
which discusses deployment and adoption characteristics of different
TLS versions.</t>
<t>The authorization server MUST use OAuth and require a valid PAT to
secure its protection API endpoints. The authorization server and the
resource server (as an OAuth client) MUST support bearer usage of the
PAT, as defined in <xref target="RFC6750" />. All examples in this
specification show the use of bearer-style PATs in this format.</t>
<t>As defined in <xref target="UMAGrant" />, the resource owner -- the
entity here authorizing PAT issuance -- MAY be an end-user (natural
person) or a non-human entity treated as a person for limited legal
purposes (legal person), such as a corporation. A PAT is unique to a
resource owner, resource server used for resource management, and
authorization server used for protection of those resources. The
issuance of the PAT represents the authorization of the resource owner
for the resource server to use the authorization server for protecting
those resources.</t>
<t>Different grant types for PAT issuance might be appropriate for
different types of resource owners; for example, the client
credentials grant is useful in the case of an organization acting as a
resource owner, whereas an interactive grant type is typically more
appropriate for capturing the approval of an end-user resource owner.
Where an identity token is desired in addition to an access token, it
is RECOMMENDED to use <xref target="OIDCCore" /> in addition.</t>
</section>
<section anchor="fed-authz"
title="Separation of Responsibility and Authority">
<t>Federation of authorization for the UMA grant delivers a conceptual
separation of responsibility and authority:<list style="symbols">
<t>The resource owner can control access to resources residing at
multiple resource servers from a single authorization server, by
virtue of authorizing PAT issuance for each resource server. Any
one resource server MAY be operated by a party different from the
one operating the authorization server.</t>
<t>The resource server defines the boundaries of resources and the
scopes available to each resource, and interprets how clients'
resource requests map to permission requests, by virtue of being
the publisher of the API being protected and using the protection
API to communicate to the authorization server.</t>
<t>The resource owner works with the authorization server to
configure policy conditions (authorization grant rules), which the
authorization server executes in the process of issuing access
tokens. The authorization process makes use of claims gathered
from the requesting party and client in order to satisfy all
operative operative policy conditions.</t>
</list></t>
<t>The separation of authorization decision making and authorization
enforcement is similar to the architectural separation often used in
enterprises between policy decision points and policy enforcement
points. However, the resource server MAY apply additional
authorization controls beyond those imposed by the authorization
server. For example, even if an RPT provides sufficient permissions
for a particular case, the resource server can choose to bar access
based on its own criteria.</t>
<t>Practical control of access among loosely coupled parties typically
requires more than just messaging protocols. It is outside the scope
of this specification to define more than the technical contract
between UMA-conforming entities. Laws may govern
authorization-granting relationships. It is RECOMMENDED for the
resource owner, authorization server, and resource server to establish
agreements about which parties are responsible for establishing and
maintaining authorization grant rules and other authorization rules on
a legal or contractual level, and parties operating entities claiming
to be UMA-conforming should provide documentation of rights and
obligations between and among them. See Section 4 of <xref
target="UMAGrant" /> for more information.</t>
<t>Except for PAT issuance, the resource owner-resource server and
resource owner-authorization server interfaces -- including the
setting of policy conditions -- are outside the scope of this
specification (see <xref target="priv-consid" /> and Section 6.1 of
<xref target="UMAGrant" /> for privacy considerations). Some elements
of the protection API enable the building of user interfaces for
policy condition setting (for example, see <xref target="reg-api" />,
which can be used in concert with user interaction for resource
protection and sharing and offers an end-user redirection mechanism
for policy interactions).</t>
<t>Note: The resource server typically requires access to at least the
permission and token introspection endpoints when an end-user resource
owner is not available ("offline" access). Thus, the authorization
server needs to manage the PAT in a way that ensures this outcome.
<xref target="UMA-Impl" /> discusses ways the resource server can
enhance its error handling when the PAT is invalid.</t>
</section>
<section title="Protection API Summary">
<t>The protection API defines the following endpoints:<list
style="symbols">
<t>Resource registration endpoint as defined in <xref
target="resource-registration-endpoint" />. The API available at
this endpoint provides a means for the resource server to put
resources under the protection of an authorization server on
behalf of the resource owner and manage them over time.</t>
<t>Permission endpoint as defined in <xref
target="permission-endpoint" />. This endpoint provides a means
for the resource server to request a set of one or more
permissions on behalf of the client based on the client's resource
request when that request is unaccompanied by an access token or
is accompanied by an RPT that is insufficient for access to that
resource.</t>
<t>OPTIONAL token introspection endpoint as defined in <xref
target="RFC7662" /> and as extended in <xref
target="introspection-endpoint" />. This endpoint provides a means
for the resource server to introspect the RPT.</t>
</list></t>
<t>Use of these endpoints assumes that the resource server has
acquired OAuth client credentials from the authorization server by
static or dynamic means, and has a valid PAT. Note: Although the
resource identifiers that appear in permission and token introspection
request messages could sufficiently identify the resource owner, the
PAT is still required because it represents the resource owner's
authorization to use the protection API, as noted in <xref
target="api-sec" />.</t>
<t>The authorization server MUST declare its protection API endpoints
in the discovery document (see <xref target="as-config" />).</t>
<section title="Permissions">
<t>A permission is (requested or granted) authorized access to a
particular resource with some number of scopes bound to that
resource. The concept of permissions is used in authorization
assessment, results calculation, and RPT issuance in <xref
target="UMAGrant" />. This concept takes on greater significance in
relation to the protection API.</t>
<t>The resource server's resource registration operations at the
authorization server result in a set of resource owner-specific
resource identifiers. When the client makes a resource request that
is unaccompanied by an access token or its resource request fails,
the resource server is responsible for interpreting that request and
mapping it to a choice of authorization server, resource owner,
resource identifier(s), and set of scopes for each identifier, in
order to request one or more permissions -- resource identifiers and
a set of scopes -- and obtain a permission ticket on the client's
behalf. Finally, when the client has made a resource request
accompanied by an RPT and token introspection is in use, the
returned token introspection object reveals the structure of
permissions, potentially including expiration of individual
permissions.</t>
</section>
</section>
</section>
<section anchor="as-config" title="Authorization Server Metadata">
<t>This specification makes use of the authorization server discovery
document structure and endpoint defined in <xref target="UMAGrant" />.
The resource server uses this discovery document to discover the
endpoints it needs.</t>
<t>In addition to the metadata defined in that specification and <xref
target="OAuthMeta" />, this specification defines the following metadata
for inclusion in the discovery document:<list style="hanging">
<t hangText="permission_endpoint"><vspace />REQUIRED. The endpoint
URI at which the resource server requests permissions on the
client's behalf.</t>
<t hangText="resource_registration_endpoint"><vspace />REQUIRED. The
endpoint URI at which the resource server registers resources to put
them under authorization manager protection.</t>
</list></t>
<t>Following are additional requirements related to metadata:<list
style="hanging">
<t hangText="introspection_endpoint"><vspace />If the authorization
server supports token introspection as defined in this
specification, it MUST supply this metadata value (defined in <xref
target="OAuthMeta" />).</t>
</list></t>
<t>The authorization server SHOULD document any profiled or extended
features it supports explicitly, ideally by supplying the URI
identifying each UMA profile and extension as an <spanx
style="verb">uma_profiles_supported</spanx> metadata array value
(defined in <xref target="UMAGrant" />), and by using extension metadata
to indicate specific usage details as necessary.</t>
</section>
<section anchor="resource-registration-endpoint"
title="Resource Registration Endpoint">
<t>The API available at the resource registration endpoint enables the
resource server to put resources under the protection of an
authorization server on behalf of the resource owner and manage them
over time. Protection of a resource at the authorization server begins
on successful registration and ends on successful deregistration.</t>
<t>The resource server uses a RESTful API at the authorization server's
resource registration endpoint to create, read, update, and delete
resource descriptions, along with retrieving lists of such descriptions.
The descriptions consist of JSON documents that are maintained as web
resources at the authorization server. (Note carefully the similar but
distinct senses in which the word "resource" is used in this
section.)</t>
<t><xref target="resource-registration-endpoint-fig" /> illustrates the
resource registration API operations, with requests and success
responses shown.</t>
<figure anchor="resource-registration-endpoint-fig"
title="Resource Registration Endpoint and API: Requests and Success Responses">
<artwork><![CDATA[authorization resource resource
server server owner
| | |
|*PROTECTION API: | |
|*Resource registration | |
|endpoint/API | |
| | |
|*Create resource (POST)| |
|<----------------------| |
|*201 Created with | |
|resource ID | |
|---------------------->| |
| | |
|Set policy conditions (anytime |
|before deletion/deregistration) |
|<- - - - - - - - - - - - - - - - - - - -|
| | |
|*Read (GET) with | |
|resource ID | |
|<----------------------| |
|*200 OK with resource | |
|representation | |
|---------------------->| |
|*Update (PUT) with | |
|resource ID | |
|<----------------------| |
|*200 OK with resource | |
|ID | |
|---------------------->| |
|*List (GET) | |
|<----------------------| |
|*200 OK with list of | |
|resource IDs | |
|---------------------->| |
|*Delete (DELETE) with | |
|resource ID | |
|<----------------------| |
|*200 OK or 204 No | |
|Content | |
|---------------------->| |
]]></artwork>
</figure>
<t>The resource server MAY protect any subset of the resource owner's
resources using different authorization servers or other means entirely,
or to protect some resources and not others. Additionally, the choice of
protection regimes MAY be made explicitly by the resource owner or
implicitly by the resource server. Any such partitioning by the resource
server or owner is outside the scope of this specification.</t>
<t>The resource server MAY register a single resource for protection
that, from its perspective, has multiple parts, or has dynamic elements
such as the capacity for querying or filtering, or otherwise has
internal complexity. The resource server alone is responsible for
maintaining any required mappings between internal representations and
the resource identifiers and scopes known to the authorization
server.</t>
<t>Note: The resource server is responsible for managing the process and
timing of registering resources, maintaining the registration of
resources, and deregistering resources at the authorization server.
Motivations for updating a resource might include, for example, new
scopes added to a new API version or resource owner actions at a
resource server that result in new resource description text. See <xref
target="UMA-Impl" /> for a discussion of initial resource registration
timing options.</t>
<section anchor="resource-set-desc" title="Resource Description">
<t>A resource description is a JSON document that describes the
characteristics of a resource sufficiently for an authorization server
to protect it. A resource description has the following
parameters:<list style="hanging">
<t hangText="resource_scopes">REQUIRED. An array of strings,
serving as scope identifiers, indicating the available scopes for
this resource. Any of the strings MAY be either a plain string or
a URI.</t>
<t hangText="description">OPTIONAL. A human-readable string
describing the resource at length. The authorization server MAY
use this description in any user interface it presents to a
resource owner, for example, for resource protection monitoring or
policy setting. The value of this parameter MAY be
internationalized, as described in Section 2.2 of <xref
target="RFC7591" />.</t>
<t hangText="icon_uri">OPTIONAL. A URI for a graphic icon
representing the resource. The authorization server MAY use the
referenced icon in any user interface it presents to a resource
owner, for example, for resource protection monitoring or policy
setting.</t>
<t hangText="name">OPTIONAL. A human-readable string naming the
resource. The authorization server MAY use this name in any user
interface it presents to a resource owner, for example, for
resource protection monitoring or policy setting. The value of
this parameter MAY be internationalized, as described in Section
2.2 of <xref target="RFC7591" />.</t>
<t hangText="type">OPTIONAL. A string identifying the semantics of
the resource. For example, if the resource is an identity claim
that leverages standardized claim semantics for "verified email
address", the value of this parameter could be an identifying URI
for this claim. The authorization server MAY use this information
in processing information about the resource or displaying
information about it in any user interface it presents to a
resource owner.</t>
</list></t>
<figure>
<preamble>For example, this description characterizes a resource (a
photo album) that can potentially be viewed or printed; the scope
URI points to a scope description as defined in <xref
target="scope-desc" />:</preamble>
<artwork><![CDATA[{
"resource_scopes":[
"view",
"http://photoz.example.com/dev/scopes/print"
],
"description":"Collection of digital photographs",
"icon_uri":"http://www.example.com/icons/flower.png",
"name":"Photo Album",
"type":"http://www.example.com/rsrcs/photoalbum"
}
]]></artwork>
</figure>
<section anchor="scope-desc" title="Scope Description">
<t>A scope description is a JSON document that describes the
characteristics of a scope sufficiently for an authorization server
to protect the resource with this available scope.</t>
<t>While a scope URI appearing in a resource description (see <xref
target="resource-set-desc" />) MAY resolve to a scope description
document, and thus scope description documents are possible to
standardize and reference publicly, the authorization server is not
expected to resolve scope description details at resource
registration time or at any other run-time requirement. The resource
server and authorization server are presumed to have negotiated any
required interpretation of scope handling out of band.</t>
<t>A scope description has the following parameters:<list
style="hanging">
<t hangText="description">OPTIONAL. A human-readable string
describing the resource at length. The authorization server MAY
use this description in any user interface it presents to a
resource owner, for example, for resource protection monitoring
or policy setting. The value of this parameter MAY be
internationalized, as described in Section 2.2 of <xref
target="RFC7591" />.</t>
<t hangText="icon_uri">OPTIONAL. A URI for a graphic icon
representing the scope. The authorization server MAY use the
referenced icon in any user interface it presents to a resource
owner, for example, for resource protection monitoring or policy
setting.</t>
<t hangText="name">OPTIONAL. A human-readable string naming the
scope. The authorization server MAY use this name in any user
interface it presents to a resource owner, for example, for
resource protection monitoring or policy setting. The value of
this parameter MAY be internationalized, as described in Section
2.2 of <xref target="RFC7591" />.</t>
</list></t>
<figure>
<preamble>For example, this scope description characterizes a
scope that involves printing (as opposed to, say, creating or
editing in some fashion):</preamble>
<artwork><![CDATA[{
"description":"Print out and produce PDF files of photos",
"icon_uri":"http://www.example.com/icons/printer",
"name":"Print"
}
]]></artwork>
</figure>
</section>
</section>
<section anchor="reg-api" title="Resource Registration API">
<t>The authorization server MUST support the following five
registration options and MUST require a valid PAT for access to them;
any other operations are undefined by this specification. Here, <spanx
style="emph">rreguri</spanx> stands for the resource registration
endpoint and <spanx style="emph">_id</spanx> stands for the
authorization server-assigned identifier for the web resource
corresponding to the resource at the time it was created, included
within the URL returned in the Location header. Each operation is
defined in its own section below.<list style="symbols">
<t>Create resource description: POST <spanx
style="emph">rreguri</spanx>/</t>
<t>Read resource description: GET <spanx
style="emph">rreguri</spanx>/<spanx style="emph">_id</spanx></t>
<t>Update resource description: PUT <spanx
style="emph">rreguri</spanx>/<spanx style="emph">_id</spanx></t>
<t>Delete resource description: DELETE <spanx
style="emph">rreguri</spanx>/<spanx style="emph">_id</spanx></t>
<t>List resource descriptions: GET <spanx
style="emph">rreguri</spanx>/</t>
</list></t>
<t>Within the JSON body of a successful response, the authorization
server includes common parameters, possibly in addition to
method-specific parameters, as follows:<list style="hanging">
<t hangText="_id">REQUIRED (except for the Delete and List
methods). A string value repeating the authorization
server-defined identifier for the web resource corresponding to
the resource. Its appearance in the body makes it readily
available as an identifier for various protected resource
management tasks.</t>
<t hangText="user_access_policy_uri">OPTIONAL. A URI that allows
the resource server to redirect an end-user resource owner to a
specific user interface within the authorization server where the
resource owner can immediately set or modify access policies
subsequent to the resource registration action just completed. The
authorization server is free to choose the targeted user
interface, for example, in the case of a deletion action, enabling
the resource server to direct the end-user to a policy-setting
interface for an overall "folder" resource formerly "containing"
the deleted resource (a relationship the authorization server is
not aware of), to enable adjustment of related policies.</t>
</list></t>
<t>If the request to the resource registration endpoint is incorrect,
then the authorization server instead responds as follows (see <xref
target="errors" /> for information about error messages):<list
style="symbols">
<t>If the referenced resource cannot be found, the authorization
server MUST respond with an HTTP 404 (Not Found) status code and
MAY respond with a <spanx style="verb">not_found</spanx> error
code.</t>
<t>If the resource server request used an unsupported HTTP method,
the authorization server MUST respond with the HTTP 405 (Method
Not Allowed) status code and MAY respond with an <spanx
style="verb">unsupported_method_type</spanx> error code.</t>
<t>If the request is missing a required parameter, includes an
invalid parameter value, includes a parameter more than once, or
is otherwise malformed, the authorization server MUST respond with
the HTTP 400 (Bad Request) status code and MAY respond with an
<spanx style="verb">invalid_request</spanx> error code.</t>
</list></t>
<section anchor="create-rreg" title="Create Resource Description">
<t>Adds a new resource description to the authorization server using
the POST method. If the request is successful, the resource is
thereby registered and the authorization server MUST respond with an
HTTP 201 status message that includes a <spanx
style="verb">Location</spanx> header and an <spanx
style="verb">_id</spanx> parameter.</t>
<figure>
<preamble>Form of a create request, with a PAT in the
header:</preamble>
<artwork><![CDATA[POST /rreg/ HTTP/1.1 Content-Type: application/json
Authorization: Bearer MHg3OUZEQkZBMjcx
...
{
"resource_scopes":[
"read-public",
"post-updates",
"read-private",
"http://www.example.com/scopes/all"
],
"icon_uri":"http://www.example.com/icons/sharesocial.png",
"name":"Tweedl Social Service",
"type":"http://www.example.com/rsrcs/socialstream/140-compatible"
}
]]></artwork>
</figure>
<figure>
<preamble>Form of a successful response, also containing an
optional <spanx style="verb">user_access_policy_uri</spanx>
parameter:</preamble>
<artwork><![CDATA[HTTP/1.1 201 Created
Content-Type: application/json
Location: /rreg/KX3A-39WE
...
{
"_id":"KX3A-39WE",
"user_access_policy_uri":"http://as.example.com/rs/222/resource/KX3A-39WE/policy"
}
]]></artwork>
</figure>
</section>
<section anchor="read-rreg" title="Read Resource Description">
<t>Reads a previously registered resource description using the GET
method. If the request is successful, the authorization server MUST
respond with an HTTP 200 status message that includes a body
containing the referenced resource description, along with an <spanx
style="verb">_id</spanx> parameter.</t>
<figure>
<preamble>Form of a read request, with a PAT in the
header:</preamble>
<artwork><![CDATA[GET /rreg/KX3A-39WE HTTP/1.1
Authorization: Bearer MHg3OUZEQkZBMjcx
...
]]></artwork>
</figure>
<figure>
<preamble>Form of a successful response, containing all the
parameters that were registered as part of the
description:</preamble>
<artwork><![CDATA[HTTP/1.1 200 OK
Content-Type: application/json
...
{
"_id":"KX3A-39WE",
"resource_scopes":[
"read-public",
"post-updates",
"read-private",
"http://www.example.com/scopes/all"
],
"icon_uri":"http://www.example.com/icons/sharesocial.png",
"name":"Tweedl Social Service",
"type":"http://www.example.com/rsrcs/socialstream/140-compatible"
}
]]></artwork>
</figure>
</section>
<section anchor="update-resource-set"
title="Update Resource Description">
<t>Updates a previously registered resource description, by means of
a complete replacement of the previous resource description, using
the PUT method. If the request is successful, the authorization
server MUST respond with an HTTP 200 status message that includes an
<spanx style="verb">_id</spanx> parameter.</t>
<figure>
<preamble>Form of an update request adding a <spanx
style="verb">description</spanx> parameter to a resource
description that previously had none, with a PAT in the
header:</preamble>
<artwork><![CDATA[PUT /rreg/9UQU-DUWW HTTP/1.1
Content-Type: application/json
Authorization: Bearer 204c69636b6c69
...
{
"resource_scopes":[
"http://photoz.example.com/dev/scopes/view",
"public-read"
],
"description":"Collection of digital photographs",
"icon_uri":"http://www.example.com/icons/sky.png",
"name":"Photo Album",
"type":"http://www.example.com/rsrcs/photoalbum"
}
]]></artwork>
</figure>
<figure>
<preamble>Form of a successful response, not containing the
optional <spanx style="verb">user_access_policy_uri</spanx>
parameter:</preamble>
<artwork><![CDATA[HTTP/1.1 200 OK
...
{
"_id":"9UQU-DUWW"
}
]]></artwork>
</figure>
</section>
<section anchor="delete-rreg" title="Delete Resource Description">
<t>Deletes a previously registered resource description using the
DELETE method. If the request is successful, the resource is thereby
deregistered and the authorization server MUST respond with an HTTP
200 or 204 status message.</t>
<figure>
<preamble>Form of a delete request, with a PAT in the
header:</preamble>
<artwork><![CDATA[DELETE /rreg/9UQU-DUWW
Authorization: Bearer 204c69636b6c69
...
]]></artwork>
</figure>
<figure>
<preamble>Form of a successful response:</preamble>
<artwork><![CDATA[HTTP/1.1 204 No content
...
]]></artwork>
</figure>
</section>
<section anchor="list-rreg" title="List Resource Descriptions">
<t>Lists all previously registered resource identifiers for this
resource owner using the GET method. The authorization server MUST
return the list in the form of a JSON array of <spanx
style="verb">_id</spanx> string values.</t>
<t>The resource server can use this method as a first step in
checking whether its understanding of protected resources is in full
synchronization with the authorization server's understanding.</t>
<figure>
<preamble>Form of a list request, with a PAT in the
header:</preamble>
<artwork><![CDATA[GET /rreg/ HTTP/1.1
Authorization: Bearer 204c69636b6c69
...
]]></artwork>
</figure>
<figure>
<preamble>Form of a successful response:</preamble>
<artwork><![CDATA[HTTP/1.1 200 OK
...
[
"KX3A-39WE",
"9UQU-DUWW"
]
]]></artwork>
</figure>
</section>
</section>
</section>
<section anchor="permission-endpoint" title="Permission Endpoint">
<t>The permission endpoint defines a means for the resource server to
request one or more permissions (resource identifiers and corresponding
scopes) with the authorization server on the client's behalf, and to
receive a permission ticket in return, in order to respond as indicated
in Section 3.2 of <xref target="UMAGrant" />. The resource server uses
this endpoint on the following occasions:<list style="symbols">
<t>After the client's initial resource request without an access
token</t>
<t>After the client's resource request that was accompanied by an
invalid RPT or a valid RPT that had insufficient permissions
associated with it</t>
</list></t>
<t>The use of the permission endpoint is illustrated in <xref
target="permission-endpoint-fig" />, with a request and a success
response shown.</t>
<figure anchor="permission-endpoint-fig"
title="Permission Endpoint: Request and Success Response">
<artwork><![CDATA[ authorization resource
client server server
| | |
|Request resource (no or insufficient |
|access token) | |
|--------------------------------------->|
| | |
| |*PROTECTION API: |
| |*Permission endpoint |
| | |
| |*Request permissions |
| |(POST) |
| |<--------------------|
| |*201 Created with |
| |permission ticket |
| |-------------------->|
| | |
|401 response with permission ticket, |
|authz server location |
|<---------------------------------------|
]]></artwork>
</figure>
<t>The PAT provided in the API request enables the authorization server
to map the resource server's request to the appropriate resource owner.
It is only possible to request permissions for access to the resources
of a single resource owner, protected by a single authorization server,
at a time.</t>
<t>In its response, the authorization server returns a permission ticket
for the resource server to give to the client that represents the same
permissions that the resource server requested.</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. The resource server MAY request multiple permissions, and any
permission MAY have zero scopes associated with it. Requesting multiple
permissions might be appropriate, for example, in cases where the
resource server expects the requesting party to need access to several
related resources if they need access to any one of the resources (see
Section 3.3.4 of <xref target="UMAGrant" /> for an example). Requesting
a permission with no scopes might be appropriate, for example, in cases
where an access attempt involves an API call that is ambiguous without
further context (role-based scopes such as <spanx
style="verb">user</spanx> and <spanx style="verb">admin</spanx> could
have this ambiguous quality, and an explicit client request for a
particular scope at the token endpoint later can clarify the desired
access). The resource server SHOULD document its intended pattern of
permission requests in order to assist the client in pre-registering for
and requesting appropriate scopes at the authorization server. See <xref
target="UMA-Impl" /> for a discussion of permission request
patterns.</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 (enabling a choice of permission endpoint and PAT), 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>
<section title="Resource Server Request to Permission Endpoint">
<t>The resource server uses the POST method at the permission
endpoint. The body of the HTTP request message contains a JSON object
for requesting a permission for single resource identifier, or an
array of one or more objects for requesting permissions for a
corresponding number of resource identifiers. The object format in
both cases is derived from the resource description format specified
in <xref target="resource-set-desc" />; it has the following
parameters:<list style="hanging">
<t hangText="resource_id">REQUIRED. The identifier for a resource
to which the resource server is requesting a permission on behalf
of the client. The identifier MUST correspond to a resource that
was previously registered.</t>
<t hangText="resource_scopes">REQUIRED. An array referencing zero
or more identifiers of scopes to which the resource server is
requesting access for this resource on behalf of the client. Each
scope identifier MUST correspond to a scope that was previously
registered by this resource server for the referenced
resource.</t>
</list></t>
<figure>
<preamble>Example of an HTTP request for a single permission at the
authorization server's permission endpoint, with a PAT in the
header:</preamble>
<artwork><![CDATA[POST /perm HTTP/1.1
Content-Type: application/json
Host: as.example.com
Authorization: Bearer 204c69636b6c69
...
{
"resource_id":"112210f47de98100",
"resource_scopes":[
"view",
"http://photoz.example.com/dev/actions/print"
]
}
]]></artwork>
</figure>
<figure>
<preamble>Example of an HTTP request for multiple permissions at the
authorization server's permission endpoint, with a PAT in the
header:</preamble>
<artwork><![CDATA[POST /perm HTTP/1.1
Content-Type: application/json
Host: as.example.com
Authorization: Bearer 204c69636b6c69
...
[
{
"resource_id":"7b727369647d",
"resource_scopes":[
"view",
"crop",
"lightbox"
]
},
{
"resource_id":"7b72736964327d",
"resource_scopes":[
"view",
"layout",
"print"
]
},
{