UMA-Specifications/draft-uma-core.html at master · findthomas/UMA-Specifications · GitHub

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
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head profile="http://www.w3.org/2006/03/hcard http://dublincore.org/documents/2008/08/04/dc-html/">
  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />

  <title>User-Managed Access (UMA) Profile of OAuth 2.0</title>

  <style type="text/css" title="Xml2Rfc (sans serif)">
  /*<![CDATA[*/
	  a {
	  text-decoration: none;
	  }
      /* info code from SantaKlauss at http://www.madaboutstyle.com/tooltip2.html */
      a.info {
          /* This is the key. */
          position: relative;
          z-index: 24;
          text-decoration: none;
      }
      a.info:hover {
          z-index: 25;
          color: #FFF; background-color: #900;
      }
      a.info span { display: none; }
      a.info:hover span.info {
          /* The span will display just on :hover state. */
          display: block;
          position: absolute;
          font-size: smaller;
          top: 2em; left: -5em; width: 15em;
          padding: 2px; border: 1px solid #333;
          color: #900; background-color: #EEE;
          text-align: left;
      }
	  a.smpl {
	  color: black;
	  }
	  a:hover {
	  text-decoration: underline;
	  }
	  a:active {
	  text-decoration: underline;
	  }
	  address {
	  margin-top: 1em;
	  margin-left: 2em;
	  font-style: normal;
	  }
	  body {
	  color: black;
	  font-family: verdana, helvetica, arial, sans-serif;
	  font-size: 10pt;
	  max-width: 55em;

	  }
	  cite {
	  font-style: normal;
	  }
	  dd {
	  margin-right: 2em;
	  }
	  dl {
	  margin-left: 2em;
	  }

	  ul.empty {
	  list-style-type: none;
	  }
	  ul.empty li {
	  margin-top: .5em;
	  }
	  dl p {
	  margin-left: 0em;
	  }
	  dt {
	  margin-top: .5em;
	  }
	  h1 {
	  font-size: 14pt;
	  line-height: 21pt;
	  page-break-after: avoid;
	  }
	  h1.np {
	  page-break-before: always;
	  }
	  h1 a {
	  color: #333333;
	  }
	  h2 {
	  font-size: 12pt;
	  line-height: 15pt;
	  page-break-after: avoid;
	  }
	  h3, h4, h5, h6 {
	  font-size: 10pt;
	  page-break-after: avoid;
	  }
	  h2 a, h3 a, h4 a, h5 a, h6 a {
	  color: black;
	  }
	  img {
	  margin-left: 3em;
	  }
	  li {
	  margin-left: 2em;
	  margin-right: 2em;
	  }
	  ol {
	  margin-left: 2em;
	  margin-right: 2em;
	  }
	  ol p {
	  margin-left: 0em;
	  }
	  p {
	  margin-left: 2em;
	  margin-right: 2em;
	  }
	  pre {
	  margin-left: 3em;
	  background-color: lightyellow;
	  padding: .25em;
	  }
	  pre.text2 {
	  border-style: dotted;
	  border-width: 1px;
	  background-color: #f0f0f0;
	  width: 69em;
	  }
	  pre.inline {
	  background-color: white;
	  padding: 0em;
	  }
	  pre.text {
	  border-style: dotted;
	  border-width: 1px;
	  background-color: #f8f8f8;
	  width: 69em;
	  }
	  pre.drawing {
	  border-style: solid;
	  border-width: 1px;
	  background-color: #f8f8f8;
	  padding: 2em;
	  }
	  table {
	  margin-left: 2em;
	  }
	  table.tt {
	  vertical-align: top;
	  }
	  table.full {
	  border-style: outset;
	  border-width: 1px;
	  }
	  table.headers {
	  border-style: outset;
	  border-width: 1px;
	  }
	  table.tt td {
	  vertical-align: top;
	  }
	  table.full td {
	  border-style: inset;
	  border-width: 1px;
	  }
	  table.tt th {
	  vertical-align: top;
	  }
	  table.full th {
	  border-style: inset;
	  border-width: 1px;
	  }
	  table.headers th {
	  border-style: none none inset none;
	  border-width: 1px;
	  }
	  table.left {
	  margin-right: auto;
	  }
	  table.right {
	  margin-left: auto;
	  }
	  table.center {
	  margin-left: auto;
	  margin-right: auto;
	  }
	  caption {
	  caption-side: bottom;
	  font-weight: bold;
	  font-size: 9pt;
	  margin-top: .5em;
	  }

	  table.header {
	  border-spacing: 1px;
	  width: 95%;
	  font-size: 10pt;
	  color: white;
	  }
	  td.top {
	  vertical-align: top;
	  }
	  td.topnowrap {
	  vertical-align: top;
	  white-space: nowrap;
	  }
	  table.header td {
	  background-color: gray;
	  width: 50%;
	  }
	  table.header a {
	  color: white;
	  }
	  td.reference {
	  vertical-align: top;
	  white-space: nowrap;
	  padding-right: 1em;
	  }
	  thead {
	  display:table-header-group;
	  }
	  ul.toc, ul.toc ul {
	  list-style: none;
	  margin-left: 1.5em;
	  margin-right: 0em;
	  padding-left: 0em;
	  }
	  ul.toc li {
	  line-height: 150%;
	  font-weight: bold;
	  font-size: 10pt;
	  margin-left: 0em;
	  margin-right: 0em;
	  }
	  ul.toc li li {
	  line-height: normal;
	  font-weight: normal;
	  font-size: 9pt;
	  margin-left: 0em;
	  margin-right: 0em;
	  }
	  li.excluded {
	  font-size: 0pt;
	  }
	  ul p {
	  margin-left: 0em;
	  }

	  .comment {
	  background-color: yellow;
	  }
	  .center {
	  text-align: center;
	  }
	  .error {
	  color: red;
	  font-style: italic;
	  font-weight: bold;
	  }
	  .figure {
	  font-weight: bold;
	  text-align: center;
	  font-size: 9pt;
	  }
	  .filename {
	  color: #333333;
	  font-weight: bold;
	  font-size: 12pt;
	  line-height: 21pt;
	  text-align: center;
	  }
	  .fn {
	  font-weight: bold;
	  }
	  .hidden {
	  display: none;
	  }
	  .left {
	  text-align: left;
	  }
	  .right {
	  text-align: right;
	  }
	  .title {
	  color: #990000;
	  font-size: 18pt;
	  line-height: 18pt;
	  font-weight: bold;
	  text-align: center;
	  margin-top: 36pt;
	  }
	  .vcardline {
	  display: block;
	  }
	  .warning {
	  font-size: 14pt;
	  background-color: yellow;
	  }


	  @media print {
	  .noprint {
		display: none;
	  }

	  a {
		color: black;
		text-decoration: none;
	  }

	  table.header {
		width: 90%;
	  }

	  td.header {
		width: 50%;
		color: black;
		background-color: white;
		vertical-align: top;
		font-size: 12pt;
	  }

	  ul.toc a::after {
		content: leader('.') target-counter(attr(href), page);
	  }

	  ul.ind li li a {
		content: target-counter(attr(href), page);
	  }

	  .print2col {
		column-count: 2;
		-moz-column-count: 2;
		column-fill: auto;
	  }
	  }

	  @page {
	  @top-left {
		   content: "Internet-Draft";
	  }
	  @top-right {
		   content: "December 2010";
	  }
	  @top-center {
		   content: "Abbreviated Title";
	  }
	  @bottom-left {
		   content: "Doe";
	  }
	  @bottom-center {
		   content: "Expires June 2011";
	  }
	  @bottom-right {
		   content: "[Page " counter(page) "]";
	  }
	  }

	  @page:first {
		@top-left {
		  content: normal;
		}
		@top-right {
		  content: normal;
		}
		@top-center {
		  content: normal;
		}
	  }
  /*]]>*/
  </style>

  <link href="#rfc.toc" rel="Contents"/>
<link href="#rfc.section.1" rel="Chapter" title="1 Introduction"/>
<link href="#rfc.section.1.1" rel="Chapter" title="1.1 Notational Conventions"/>
<link href="#rfc.section.1.2" rel="Chapter" title="1.2 Terminology"/>
<link href="#rfc.section.1.3" rel="Chapter" title="1.3 Achieving Distributed Protection Through APIs and Tokens"/>
<link href="#rfc.section.1.3.1" rel="Chapter" title="1.3.1 Protection API"/>
<link href="#rfc.section.1.3.2" rel="Chapter" title="1.3.2 Authorization API"/>
<link href="#rfc.section.1.3.3" rel="Chapter" title="1.3.3 Protected Resource Interface"/>
<link href="#rfc.section.1.3.4" rel="Chapter" title="1.3.4 Time-to-Live Considerations"/>
<link href="#rfc.section.1.4" rel="Chapter" title="1.4 Authorization Server Configuration Data"/>
<link href="#rfc.section.2" rel="Chapter" title="2 Protecting a Resource"/>
<link href="#rfc.section.3" rel="Chapter" title="3 Getting Authorization and Accessing a Resource"/>
<link href="#rfc.section.3.1" rel="Chapter" title="3.1 Client Attempts to Access Protected Resource"/>
<link href="#rfc.section.3.1.1" rel="Chapter" title="3.1.1 Client Presents No RPT"/>
<link href="#rfc.section.3.1.2" rel="Chapter" title="3.1.2 Client Presents RPT"/>
<link href="#rfc.section.3.2" rel="Chapter" title="3.2 Resource Server Registers Requested Permission With Authorization Server"/>
<link href="#rfc.section.3.3" rel="Chapter" title="3.3 Resource Server Determines RPT's Status"/>
<link href="#rfc.section.3.3.1" rel="Chapter" title="3.3.1 Token Introspection"/>
<link href="#rfc.section.3.3.2" rel="Chapter" title="3.3.2 RPT Profile: Bearer"/>
<link href="#rfc.section.3.4" rel="Chapter" title="3.4 Client Seeks Authorization for Access"/>
<link href="#rfc.section.3.4.1" rel="Chapter" title="3.4.1 Client Obtains RPT"/>
<link href="#rfc.section.3.5" rel="Chapter" title="3.5 Claims-Gathering Flows"/>
<link href="#rfc.section.4" rel="Chapter" title="4 Error Messages"/>
<link href="#rfc.section.4.1" rel="Chapter" title="4.1 OAuth Error Responses"/>
<link href="#rfc.section.4.2" rel="Chapter" title="4.2 UMA Error Responses"/>
<link href="#rfc.section.5" rel="Chapter" title="5 Profiles for API Extensibility"/>
<link href="#rfc.section.5.1" rel="Chapter" title="5.1 Protection API Extensibility Profile"/>
<link href="#rfc.section.5.2" rel="Chapter" title="5.2 Authorization API Extensibility Profile"/>
<link href="#rfc.section.5.3" rel="Chapter" title="5.3 Resource Interface Extensibility Profile"/>
<link href="#rfc.section.6" rel="Chapter" title="6 Specifying Additional Profiles"/>
<link href="#rfc.section.6.1" rel="Chapter" title="6.1 Specifying Profiles of UMA"/>
<link href="#rfc.section.6.2" rel="Chapter" title="6.2 Specifying RPT Profiles"/>
<link href="#rfc.section.6.3" rel="Chapter" title="6.3 Specifying Claim Profiles"/>
<link href="#rfc.section.7" rel="Chapter" title="7 Security Considerations"/>
<link href="#rfc.section.8" rel="Chapter" title="8 Privacy Considerations"/>
<link href="#rfc.section.9" rel="Chapter" title="9 Conformance"/>
<link href="#rfc.section.10" rel="Chapter" title="10 IANA Considerations"/>
<link href="#rfc.section.11" rel="Chapter" title="11 Acknowledgments"/>
<link href="#rfc.section.12" rel="Chapter" title="12 Issues"/>
<link href="#rfc.references" rel="Chapter" title="13 References"/>
<link href="#rfc.references.1" rel="Chapter" title="13.1 Normative References"/>
<link href="#rfc.references.2" rel="Chapter" title="13.2 Informative References"/>
<link href="#rfc.appendix.A" rel="Chapter" title="A Document History"/>
<link href="#rfc.authors" rel="Chapter"/>


  <meta name="generator" content="xml2rfc version 2.4.9dev0 - http://tools.ietf.org/tools/xml2rfc" />
  <link rel="schema.dct" href="http://purl.org/dc/terms/" />

  <meta name="dct.creator" content="Hardjono, T., Ed." />
  <meta name="dct.identifier" content="urn:ietf:id:draft-hardjono-oauth-umacore-11" />
  <meta name="dct.issued" scheme="ISO8601" content="2014-10-23" />
  <meta name="dct.abstract" content="User-Managed Access (UMA) is a profile of OAuth 2.0. UMA defines how resource owners can control protected-resource access by clients operated by arbitrary requesting parties, where the resources reside on any number of resource servers, and where a centralized authorization server governs access based on resource owner policy. This revision of the specification is part of the &quot;candidate V1.0&quot; process." />
  <meta name="description" content="User-Managed Access (UMA) is a profile of OAuth 2.0. UMA defines how resource owners can control protected-resource access by clients operated by arbitrary requesting parties, where the resources reside on any number of resource servers, and where a centralized authorization server governs access based on resource owner policy. This revision of the specification is part of the &quot;candidate V1.0&quot; process." />

</head>

<body>

  <table class="header">
    <tbody>

    	<tr>
  <td class="left">Network Working Group</td>
  <td class="right">T. Hardjono, Ed.</td>
</tr>
<tr>
  <td class="left">Internet-Draft</td>
  <td class="right">MIT</td>
</tr>
<tr>
  <td class="left">Intended status: Standards Track</td>
  <td class="right">October 23, 2014</td>
</tr>
<tr>
  <td class="left">Expires: April 26, 2015</td>
  <td class="right"></td>
</tr>


    </tbody>
  </table>

  <p class="title">User-Managed Access (UMA) Profile of OAuth 2.0<br />
  <span class="filename">draft-hardjono-oauth-umacore-11</span></p>

  <h1 id="rfc.abstract">
  <a href="#rfc.abstract">Abstract</a>
</h1>
<p>User-Managed Access (UMA) is a profile of OAuth 2.0. UMA defines how resource owners can control protected-resource access by clients operated by arbitrary requesting parties, where the resources reside on any number of resource servers, and where a centralized authorization server governs access based on resource owner policy. This revision of the specification is part of the "candidate V1.0" process.</p>
<h1 id="rfc.status">
  <a href="#rfc.status">Status of This Memo</a>
</h1>
<p>This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.</p>
<p>Internet-Drafts are working documents of the Internet Engineering Task Force (IETF).  Note that other groups may also distribute working documents as Internet-Drafts.  The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.</p>
<p>Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time.  It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."</p>
<p>This Internet-Draft will expire on April 26, 2015.</p>
<h1 id="rfc.copyrightnotice">
  <a href="#rfc.copyrightnotice">Copyright Notice</a>
</h1>
<p>Copyright (c) 2014 IETF Trust and the persons identified as the document authors.  All rights reserved.</p>
<p>This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document.  Please review these documents carefully, as they describe your rights and restrictions with respect to this document.  Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.</p>


  <hr class="noprint" />
  <h1 class="np" id="rfc.toc"><a href="#rfc.toc">Table of Contents</a></h1>
  <ul class="toc">

  	<li>1.   <a href="#rfc.section.1">Introduction</a></li>
<ul><li>1.1.   <a href="#rfc.section.1.1">Notational Conventions</a></li>
<li>1.2.   <a href="#rfc.section.1.2">Terminology</a></li>
<li>1.3.   <a href="#rfc.section.1.3">Achieving Distributed Protection Through APIs and Tokens</a></li>
<ul><li>1.3.1.   <a href="#rfc.section.1.3.1">Protection API</a></li>
<li>1.3.2.   <a href="#rfc.section.1.3.2">Authorization API</a></li>
<li>1.3.3.   <a href="#rfc.section.1.3.3">Protected Resource Interface</a></li>
<li>1.3.4.   <a href="#rfc.section.1.3.4">Time-to-Live Considerations</a></li>
</ul><li>1.4.   <a href="#rfc.section.1.4">Authorization Server Configuration Data</a></li>
</ul><li>2.   <a href="#rfc.section.2">Protecting a Resource</a></li>
<li>3.   <a href="#rfc.section.3">Getting Authorization and Accessing a Resource</a></li>
<ul><li>3.1.   <a href="#rfc.section.3.1">Client Attempts to Access Protected Resource</a></li>
<ul><li>3.1.1.   <a href="#rfc.section.3.1.1">Client Presents No RPT</a></li>
<li>3.1.2.   <a href="#rfc.section.3.1.2">Client Presents RPT</a></li>
</ul><li>3.2.   <a href="#rfc.section.3.2">Resource Server Registers Requested Permission With Authorization Server</a></li>
<li>3.3.   <a href="#rfc.section.3.3">Resource Server Determines RPT's Status</a></li>
<ul><li>3.3.1.   <a href="#rfc.section.3.3.1">Token Introspection</a></li>
<li>3.3.2.   <a href="#rfc.section.3.3.2">RPT Profile: Bearer</a></li>
</ul><li>3.4.   <a href="#rfc.section.3.4">Client Seeks Authorization for Access</a></li>
<ul><li>3.4.1.   <a href="#rfc.section.3.4.1">Client Obtains RPT</a></li>
</ul><li>3.5.   <a href="#rfc.section.3.5">Claims-Gathering Flows</a></li>
</ul><li>4.   <a href="#rfc.section.4">Error Messages</a></li>
<ul><li>4.1.   <a href="#rfc.section.4.1">OAuth Error Responses</a></li>
<li>4.2.   <a href="#rfc.section.4.2">UMA Error Responses</a></li>
</ul><li>5.   <a href="#rfc.section.5">Profiles for API Extensibility</a></li>
<ul><li>5.1.   <a href="#rfc.section.5.1">Protection API Extensibility Profile</a></li>
<li>5.2.   <a href="#rfc.section.5.2">Authorization API Extensibility Profile</a></li>
<li>5.3.   <a href="#rfc.section.5.3">Resource Interface Extensibility Profile</a></li>
</ul><li>6.   <a href="#rfc.section.6">Specifying Additional Profiles</a></li>
<ul><li>6.1.   <a href="#rfc.section.6.1">Specifying Profiles of UMA</a></li>
<li>6.2.   <a href="#rfc.section.6.2">Specifying RPT Profiles</a></li>
<li>6.3.   <a href="#rfc.section.6.3">Specifying Claim Profiles</a></li>
</ul><li>7.   <a href="#rfc.section.7">Security Considerations</a></li>
<li>8.   <a href="#rfc.section.8">Privacy Considerations</a></li>
<li>9.   <a href="#rfc.section.9">Conformance</a></li>
<li>10.   <a href="#rfc.section.10">IANA Considerations</a></li>
<li>11.   <a href="#rfc.section.11">Acknowledgments</a></li>
<li>12.   <a href="#rfc.section.12">Issues</a></li>
<li>13.   <a href="#rfc.references">References</a></li>
<ul><li>13.1.   <a href="#rfc.references.1">Normative References</a></li>
<li>13.2.   <a href="#rfc.references.2">Informative References</a></li>
</ul><li>Appendix A.   <a href="#rfc.appendix.A">Document History</a></li>
<li><a href="#rfc.authors">Author's Address</a></li>


  </ul>

  <h1 id="rfc.section.1"><a href="#rfc.section.1">1.</a> <a href="#introduction" id="introduction">Introduction</a></h1>
<p id="rfc.section.1.p.1">User-Managed Access (UMA) is a profile of OAuth 2.0 <a href="#OAuth2">[OAuth2]</a>. UMA defines how resource owners can control protected-resource access by clients operated by arbitrary requesting parties, where the resources reside on any number of resource servers, and where a centralized authorization server governs access based on resource owner policy. Resource owners configure authorization servers with access policies that serve as implicit authorization grants. Thus, the UMA profile of OAuth can be considered to encompass an authorization grant flow.</p>
<p id="rfc.section.1.p.2">UMA serves numerous use cases where a resource owner outsources authorization for access to their resources, potentially even without the run-time presence of the resource owner. A typical example is the following: a web user (an end-user resource owner) can authorize a web app (client) to gain one-time or ongoing access to a protected resource containing his home address stored at a "personal data store" service (resource server), by telling the resource server to respect access entitlements issued by his chosen cloud-based authorization service (authorization server). The requesting party operating the client might be the resource owner himself, using a web or native app run by an e-commerce company that needs to know where to ship a purchased item, or it might be his friend who is using an online address book service to collect contact information, or it might be a survey company that uses an autonomous web service to compile population demographics. A variety of scenarios and use cases can be found in <a href="#UMA-usecases">[UMA-usecases]</a> and <a href="#UMA-casestudies">[UMA-casestudies]</a>.</p>
<p id="rfc.section.1.p.3">Practical control of access among loosely coupled parties requires more than just messaging protocols. This specification defines only the technical "contract" between UMA-conforming entities; its companion Binding Obligations specification <a href="#UMA-obligations">[UMA-obligations]</a> defines the expected behaviors of parties operating and using these entities. Parties operating entities that claim to be UMA-conforming MUST provide documentation affirmatively stating their acceptance of the binding obligations contractual framework defined in the Binding Obligations specification.</p>
<p id="rfc.section.1.p.4">In enterprise settings, application access management sometimes involves letting back-office applications serve only as policy enforcement points (PEPs), depending entirely on access decisions coming from a central policy decision point (PDP) to govern the access they give to requesters. This separation eases auditing and allows policy administration to scale in several dimensions. UMA makes use of a separation similar to this, letting the resource owner serve as a policy administrator crafting authorization strategies for resources under their control.</p>
<p id="rfc.section.1.p.5">In order to increase interoperable communication among the authorization server, resource server, and client, UMA defines several purpose-built APIs related to the outsourcing of authorization, themselves protected by OAuth in embedded fashion.</p>
<p id="rfc.section.1.p.6">The UMA protocol has three broad phases, as shown in <a href="#UMA-phases">Figure 1</a>.</p>
<div id="rfc.figure.1"/>
<div id="UMA-phases"/>
<p>The Three Phases of the UMA Profile of OAuth</p>
<pre>                                           +--------------+
                                           |   resource   |
          +---------manage (A)------------ |     owner    |
          |                                +--------------+
          |         Phase 1:                      |
          |         protect a                control (B)
          |         resource                      |
          v                                       v
   +------------+               +----------+--------------+
   |            |               |protection|              |
   |  resource  |               |   API    | authorization|
   |   server   |&lt;-protect (C)--|  (needs  |    server    |
   |            |               |   PAT)   |              |
   +------------+               +----------+--------------+
   | protected  |                          | authorization|
   | resource   |                          |     API      |
   |(needs RPT) |                          |  (needs AAT) |
   +------------+                          +--------------+
          ^                                       |
          |         Phases 2 and 3:         authorize (D)
          |         get authorization,            |
          |         access a resource             v
          |                                +--------------+
          +---------access (E)-------------|    client    |
                                           +--------------+

                                           requesting party
</pre>
<p class="figure">Figure 1</p>
<p id="rfc.section.1.p.7">The phases work as follows: </p>

<dl>
  <dt>Protect a resource</dt>
  <dd style="margin-left: 8">(Described in <a href="#protecting-a-resource">Section 2</a>.) The resource owner, who manages online resources at the resource server ("A"), introduces it to the authorization server so that the latter can begin controlling the resources' protection. To accomplish this protection, the authorization server presents a protection API ("C") to the resource server. This API is OAuth-protected and requires a protection API token (PAT) for access. Out of band, the resource owner configures the authorization server with policies associated with the registered resource sets ("B").</dd>
  <dt>Get authorization</dt>
  <dd style="margin-left: 8">(Described in <a href="#getting-authz-accessing-resource">Section 3</a>.) The client approaches the resource server seeking access to an UMA-protected resource. In order to access it successfully, the client must first use the authorization server's authorization API ("D") to obtain a requesting party token (RPT) on behalf of its requesting party, and the requesting party must supply to the authorization server any identity claims needed in order for the server to associate sufficient authorization data with that RPT. The API is OAuth-protected and requires an authorization API token (AAT) for access.</dd>
  <dt>Access a resource</dt>
  <dd style="margin-left: 8">(Described along with Phase 2 in <a href="#getting-authz-accessing-resource">Section 3</a>.) The client successfully presents an RPT that has sufficient authorization data associated with it to the resource server, gaining access to the desired resource ("E"). In this sense, this phase is the "happy path" within phase 2. The nature of the authorization data varies according to the RPT profile in use.</dd>
</dl>
<p id="rfc.section.1.p.8">Implementers have the oportunity to develop profiles (see <a href="#profiles">Section 6</a>) that specify and restrict various UMA protocol, RPT, and identity claim options, according to deployment and usage conditions.</p>
<h1 id="rfc.section.1.1"><a href="#rfc.section.1.1">1.1.</a> Notational Conventions</h1>
<p id="rfc.section.1.1.p.1">The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', 'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this document are to be interpreted as described in <a href="#RFC2119">[RFC2119]</a>.</p>
<p id="rfc.section.1.1.p.2">Unless otherwise noted, all the protocol properties and values are case sensitive.</p>
<h1 id="rfc.section.1.2"><a href="#rfc.section.1.2">1.2.</a> <a href="#terminology" id="terminology">Terminology</a></h1>
<p id="rfc.section.1.2.p.1">UMA introduces the following new terms and enhancements of OAuth term definitions.</p>

<dl>
  <dt>resource owner</dt>
  <dd style="margin-left: 6"><br/>An OAuth resource that is the "user" in User-Managed Access. This is typically an end-user (a natural person) but it can also be a corporation or other legal person.</dd>
  <dt>requesting party</dt>
  <dd style="margin-left: 6"><br/>An end-user, or a corporation or other 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.</dd>
  <dt>client</dt>
  <dd style="margin-left: 6"><br/>An application making protected resource requests with the resource owner's authorization and on the requesting party's behalf.</dd>
  <dt>claim</dt>
  <dd style="margin-left: 6"><br/>A statement of the value or values of one or more identity attributes of a requesting party. A requesting party may need to provide claims to an authorization server in order to satisfy policy and gain permission for access to a protected resource.</dd>
  <dt>resource set</dt>
  <dd style="margin-left: 6">A set of one or more protected resources. In authorization policy terminology, a resource set is the "object" being protected.</dd>
  <dt>scope</dt>
  <dd style="margin-left: 6">A bounded extent of access that is possible to perform on a resource set. In authorization policy terminology, a scope is one of the potentially many "verbs" that can logically apply to a resource set ("object"). UMA associates scopes with labeled resource sets.</dd>
  <dt>authorization data</dt>
  <dd style="margin-left: 6">Data associated with a requesting party token that enables some combination of the authorization server and resource server to determine the correct extent of access to allow to a client. Authorization data is a key part of the definition of an RPT profile.</dd>
  <dt>permission</dt>
  <dd style="margin-left: 6">A scope of access over a particular resource set at a particular resource server that is being requested by, or granted to, a requesting party. In authorization policy terminology, a permission is an entitlement that includes a "subject" (requesting party), "verbs" (one or more scopes of access), and an "object" (resource set). A permission is one example of authorization data that an authorization server may add to a requesting party token.</dd>
  <dt>permission ticket</dt>
  <dd style="margin-left: 6">A correlation handle that is conveyed from an authorization server to a resource server, from a resource server to a client, and ultimately from a client to an authorization server, to enable the authorization server to assess the correct resource owner policies to apply to a request for an authorization grant.</dd>
</dl>
<h1 id="rfc.section.1.3"><a href="#rfc.section.1.3">1.3.</a> <a href="#endpoint-discussion" id="endpoint-discussion">Achieving Distributed Protection Through APIs and Tokens</a></h1>
<p id="rfc.section.1.3.p.1">The software components that fill the roles of UMA authorization servers, resource servers, and clients respectively are intended to work in an interoperable fashion when each is operated by an entirely separate party (for example, different organizations). For this reason, UMA specifies communications channels that the authorization server MUST implement as HTTP-based APIs that MUST use TLS and OAuth protection, and that the resource server MUST implement as an HTTP-based interface. UMA's use of TLS transport-layer security is governed by Section 1.6 of <a href="#OAuth2">[OAuth2]</a>, which discusses deployment and adoption characteristics of different TLS versions. Three different types of access tokens are issued and used for a variety of purposes as part of these inter-role interactions.</p>
<p id="rfc.section.1.3.p.2">It is also REQUIRED, in turn, for resource servers and clients on the requesting side of UMA interactions to use these channels, unless a profile is being used that enables API extensibility. Profiles that enable such alternatives are described in <a href="#comms-profiles">Section 5</a>.</p>
<h1 id="rfc.section.1.3.1"><a href="#rfc.section.1.3.1">1.3.1.</a> <a href="#protection-api" id="protection-api">Protection API</a></h1>
<p id="rfc.section.1.3.1.p.1">The authorization server MUST present a TLS- and OAuth-protected, HTTP-based protection API for use by resource servers. The authorization server thus has an OAuth token endpoint and user authorization endpoint, and has the option to issue an OAuth refresh token along with any access tokens issued for these APIs. The authorization server MUST declare all of its protection API endpoints in its configuration data (see <a href="#am-endpoints">Section 1.4</a>).</p>
<p id="rfc.section.1.3.1.p.2">The protection API consists of three endpoints:</p>

<ul>
  <li>OAuth resource set registration endpoint as defined by <a href="#OAuth-resource-reg">[OAuth-resource-reg]</a></li>
  <li>Endpoint for registering client-requested permissions</li>
  <li>OAuth token introspection endpoint as defined by <a href="#OAuth-introspection">[OAuth-introspection]</a> and <a href="#token-introspection">Section 3.3.1</a></li>
</ul>
<p id="rfc.section.1.3.1.p.3">An entity seeking protection API access MUST have the scope "http://docs.kantarainitiative.org/uma/scopes/prot.json". (This URI resolves to a JSON-encoded scope description, as defined in <a href="#OAuth-resource-reg">[OAuth-resource-reg]</a>. The description is non-normative for UMA purposes.) An access token with at least this scope is called a protection API token (PAT) and an entity with this scope is definitionally a resource server. A single entity can serve in both resource server and client roles if it has the appropriate OAuth scopes. If a request to an endpoint fails due to an invalid, missing, or expired PAT, or requires higher privileges at this endpoint than provided by the PAT, the authorization server responds with an OAuth error.</p>
<p id="rfc.section.1.3.1.p.4">The authorization server MUST support the OAuth bearer token profile for PAT issuance, and MAY support other OAuth token profiles (for example, the SAML bearer token grant type <a href="#OAuth-SAML">[OAuth-SAML]</a>). It MUST declare all supported token profiles and grant types for PAT issuance in its configuration data.</p>
<p id="rfc.section.1.3.1.p.5">A PAT binds a resource owner, a resource server the owner uses for resource management, and an authorization server the owner uses for protection of resources at this resource server. It is not specific to any client or requesting party. The issuance of a PAT represents the approval of the resource owner for this resource server to trust this authorization server for protecting its resources belonging to this resource owner.</p>
<h1 id="rfc.section.1.3.2"><a href="#rfc.section.1.3.2">1.3.2.</a> <a href="#authorization-api" id="authorization-api">Authorization API</a></h1>
<p id="rfc.section.1.3.2.p.1">The authorization server MUST present a TLS- and OAuth-protected, HTTP-based authorization API for use by clients. The authorization server thus has an OAuth token endpoint and user authorization endpoint, and has the option to issue an OAuth refresh token along with any access tokens issued for these APIs. The authorization server MUST declare all of its authorization API endpoints in its configuration data (see <a href="#am-endpoints">Section 1.4</a>).</p>
<p id="rfc.section.1.3.2.p.2">The authorization API consists of two endpoints:</p>

<ul>
  <li>Endpoint for RPT issuance</li>
  <li>Endpoint for requesting authorization</li>
</ul>
<p id="rfc.section.1.3.2.p.3">An entity seeking authorization API access MUST have the scope "http://docs.kantarainitiative.org/uma/scopes/authz.json". (This URI resolves to a JSON-encoded scope description, as defined in <a href="#OAuth-resource-reg">[OAuth-resource-reg]</a>. The description is non-normative for UMA purposes.) An access token with at least this scope is called an authorization API token (AAT) and an entity with this scope is definitionally a client. A single entity can serve in both resource server and client roles if it has the appropriate OAuth scopes. If a request to an endpoint fails due to an invalid, missing, or expired AAT, or requires higher privileges at this endpoint than provided by the AAT, the authorization server responds with an OAuth error.</p>
<p id="rfc.section.1.3.2.p.4">The authorization server MUST support the OAuth bearer token profile for AAT issuance, and MAY support other OAuth token profiles (for example, the SAML bearer token grant type <a href="#OAuth-SAML">[OAuth-SAML]</a>). It MUST declare all supported token profiles and grant types for AAT issuance in its configuration data.</p>
<p id="rfc.section.1.3.2.p.5">An AAT binds a requesting party, a client being used by that party, and an authorization server that protects resources this client is seeking access to on this requesting party's behalf. It is not specific to any resource server or resource owner. The issuance of an AAT represents the approval of this requesting party for this client to engage with this authorization server to supply claims, ask for authorization, and perform any other tasks needed for obtaining authorization for access to resources at all resource servers that use this authorization server. The authorization server is able to manage future processes of authorization and claims-caching efficiently for this client/requesting party pair across all resource servers they try to access; however, these management processes are outside the scope of this specification.</p>
<h1 id="rfc.section.1.3.3"><a href="#rfc.section.1.3.3">1.3.3.</a> <a href="#resource-api" id="resource-api">Protected Resource Interface</a></h1>
<p id="rfc.section.1.3.3.p.1">The resource server MAY present to clients whatever HTTP-based APIs or endpoints it wishes. To protect any of its resources available in this fashion using UMA, it MUST require a requesting party token (RPT) with sufficient authorization data for access.</p>
<p id="rfc.section.1.3.3.p.2">This specification defines one RPT profile, call "bearer" (see <a href="#uma-bearer-token-profile">Section 3.3.2</a>), which the authorization server MUST support. It MAY support additional RPT profiles, and MUST declare all supported RPT profiles in its configuration data (see <a href="#am-endpoints">Section 1.4</a>).</p>
<p id="rfc.section.1.3.3.p.3">An RPT binds a requesting party, the client being used by that party, the resource server at which protected resources of interest reside, and the authorization server that protects those resources.  It is not specific to a single resource owner, though its internal components are likely to be bound to individual resource owners, depending on the RPT profile in use.</p>
<h1 id="rfc.section.1.3.4"><a href="#rfc.section.1.3.4">1.3.4.</a> Time-to-Live Considerations</h1>
<p id="rfc.section.1.3.4.p.1">The authorization server has the opportunity to manage the validity periods of access tokens that it issues, their corresponding refresh tokens where applicable, the individual data components associated with RPTs where applicable, and even the client credentials that it issues. Different time-to-live strategies may be suitable for different resources and scopes of access, and the authorization server has the opportunity to give the resource owner control over lifetimes of tokens and authorization data issued on their behalf through policy. These options are all outside the scope of this specification.</p>
<h1 id="rfc.section.1.4"><a href="#rfc.section.1.4">1.4.</a> <a href="#am-endpoints" id="am-endpoints">Authorization Server Configuration Data</a></h1>
<p id="rfc.section.1.4.p.1">The authorization server MUST provide configuration data in a JSON <a href="#RFC4627">[RFC4627]</a> document that resides in an /uma-configuration directory at its hostmeta <a href="#hostmeta">[hostmeta]</a> location. The configuration data documents conformance options and endpoints supported by the authorization server. (At the appropriate time, this section will instead profile whatever self-describing metadata specification OAuth adopts, for example, <a href="#OAuth-linktypes">[OAuth-linktypes]</a> or <a href="#OAuth-meta">[OAuth-meta]</a>.)</p>
<p id="rfc.section.1.4.p.2">The configuration data has the following properties.</p>

<dl>
  <dt>version</dt>
  <dd style="margin-left: 6"><br/>REQUIRED. The version of the UMA core protocol to which this authorization server conforms. The value MUST be the string "1.0".</dd>
  <dt>issuer</dt>
  <dd style="margin-left: 6"><br/>REQUIRED. A URI indicating the party operating the authorization server.</dd>
  <dt>pat_profiles_supported</dt>
  <dd style="margin-left: 6"><br/>REQUIRED. OAuth access token profiles supported by this authorization server for PAT issuance. The property value is an array of string values, where each string value is either a reserved keyword defined in this specification or a URI identifying an access token profile defined elsewhere. The reserved keyword "bearer" as a value for this property stands for the OAuth bearer token profile <a href="#OAuth-bearer">[OAuth-bearer]</a>. The authorization server is REQUIRED to support this profile, and to supply this string value explicitly. The authorization server MAY declare its support for additional access token profiles for PATs.</dd>
  <dt>aat_profiles_supported</dt>
  <dd style="margin-left: 6"><br/>REQUIRED. OAuth access token profiles supported by this authorization server for AAT issuance. The property value is an array of string values, where each string value is either a reserved keyword defined in this specification or a URI identifying an access token profile defined elsewhere. The reserved keyword "bearer" as a value for this property stands for the OAuth bearer token profile <a href="#OAuth-bearer">[OAuth-bearer]</a>. The authorization server is REQUIRED to support this profile, and to supply this string value explicitly. The authorization server MAY declare its support for additional access token profiles for AATs.</dd>
  <dt>rpt_profiles_supported</dt>
  <dd style="margin-left: 6"><br/>REQUIRED. UMA RPT profiles supported by this authorization server for RPT issuance.  The property value is an array of string values, where each string value is either a reserved keyword defined in this specification or a URI identifying an RPT profile defined elsewhere. The reserved keyword "bearer" as a value for this property stands for the UMA bearer RPT profile defined in <a href="#uma-bearer-token-profile">Section 3.3.2</a>. The authorization server is REQUIRED to support this profile, and to supply this string value explicitly. The authorization server MAY declare its support for additional RPT profiles.</dd>
  <dt>pat_grant_types_supported</dt>
  <dd style="margin-left: 6"><br/>REQUIRED. OAuth grant types supported by this authorization server in issuing PATs. The property value is an array of string values. Each string value MUST be one of the grant_type values defined in <a href="#OAuth2">[OAuth2]</a>, or alternatively a URI identifying a grant type defined elsewhere.</dd>
  <dt>aat_grant_types_supported</dt>
  <dd style="margin-left: 6"><br/>REQUIRED. OAuth grant types supported by this authorization server in issuing AATs. The property value is an array of string values. Each string value MUST be one of the grant_type values defined in <a href="#OAuth2">[OAuth2]</a>, or alternatively a URI identifying a grant type defined elsewhere.</dd>
  <dt>claim_profiles_supported</dt>
  <dd style="margin-left: 6"><br/>OPTIONAL. Claim formats and associated sub-protocols for gathering claims from requesting parties, as supported by this authorization server. The property value is an array of string values, which each string value is either a reserved keyword defined in this specification or a URI identifying a claim profile defined elsewhere.</dd>
  <dt>uma_profiles_supported</dt>
  <dd style="margin-left: 6"><br/>OPTIONAL. UMA profiles supported by this authorization server. The property value is an array of string values, which each string value is either a reserved keyword defined in this specification or a URI identifying an UMA profile defined elsewhere. The reserved keywords "prot-ext", "authz-ext", and "rsrc-ext" as values for this property stand for the extensibility profiles defined, respectively, in <a href="#comms-profiles">Section 5</a>.</dd>
  <dt>dynamic_client_endpoint</dt>
  <dd style="margin-left: 6"><br/>OPTIONAL. The endpoint to use for performing dynamic client registration. Usage of this endpoint is defined by <a href="#DynClientReg">[DynClientReg]</a>. The presence of this property indicates authorization server support for the dynamic client registration feature and its absence indicates a lack of support.</dd>
  <dt>token_endpoint</dt>
  <dd style="margin-left: 6"><br/>REQUIRED. The endpoint URI at which the resource server or client asks the authorization server for a PAT or AAT, respectively. A requested scope of "http://docs.kantarainitiative.org/uma/scopes/prot.json" results in a PAT. A requested scope of "http://docs.kantarainitiative.org/uma/scopes/authz.json" results in an AAT. Usage of this endpoint is defined by <a href="#OAuth2">[OAuth2]</a>.</dd>
  <dt>user_endpoint</dt>
  <dd style="margin-left: 6"><br/>REQUIRED. The endpoint URI at which the resource server gathers the consent of the end-user resource owner or the client gathers the consent of the end-user requesting party, if the "authorization_code" grant type is used.  Usage of this endpoint is defined by <a href="#OAuth2">[OAuth2]</a>.</dd>
  <dt>introspection_endpoint</dt>
  <dd style="margin-left: 6"><br/>REQUIRED. The endpoint URI at which the resource server introspects an RPT presented to it by a client. Usage of this endpoint is defined by <a href="#OAuth-introspection">[OAuth-introspection]</a> and <a href="#token-introspection">Section 3.3.1</a>. A valid PAT MUST accompany requests to this protected endpoint.</dd>
  <dt>resource_set_registration_endpoint</dt>
  <dd style="margin-left: 6"><br/>REQUIRED.  The endpoint URI at which the resource server registers resource sets to put them under authorization manager protection. Usage of this endpoint is defined by <a href="#OAuth-resource-reg">[OAuth-resource-reg]</a> and <a href="#protecting-a-resource">Section 2</a>. A valid PAT MUST accompany requests to this protected endpoint.</dd>
  <dt>permission_registration_endpoint</dt>
  <dd style="margin-left: 6"><br/>REQUIRED.  The endpoint URI at which the resource server registers a client-requested permission with the authorization server. Usage of this endpoint is defined by <a href="#h-am-register-permission">Section 3.2</a>. A valid PAT MUST accompany requests to this protected endpoint.</dd>
  <dt>authorization_request_endpoint</dt>
  <dd style="margin-left: 6"><br/>REQUIRED.  The endpoint URI at which the client asks for authorization data.  Usage of this endpoint is defined in <a href="#r-am-obtain-permission">Section 3.4</a>. A valid AAT and a permission ticket MUST, and an RPT MAY, accompany requests to this protected endpoint.</dd>
</dl>
<p>Example of authorization server configuration data that resides at https://example.com/.well-known/uma-configuration (note the use of https: for endpoints throughout):</p>
<pre>{
"version":"1.0",
"issuer":"https://example.com",
"pat_profiles_supported":["bearer"],
"aat_profiles_supported":["bearer"],
"rpt_profiles_supported":["bearer"],
"pat_grant_types_supported":["authorization_code"],
"aat_grant_types_supported":["authorization_code"],
"claim_profiles_supported":["openid"],
"dynamic_client_endpoint":"https://as.example.com/dyn_client_reg_uri",
"token_endpoint":"https://as.example.com/token_uri",
"user_endpoint":"https://as.example.com/user_uri",
"resource_set_registration_endpoint":"https://as.example.com/rs/rsrc_uri",
"introspection_endpoint":"https://as.example.com/rs/status_uri",
"permission_registration_endpoint":"https://as.example.com/rs/perm_uri",
"authorization_request_endpoint":"https://as.example.com/client/perm_uri"
}</pre>
<p id="rfc.section.1.4.p.3">Authorization server configuration data MAY contain extension properties that are not defined in this specification. Extension names that are unprotected from collisions are outside the scope of this specification.</p>
<h1 id="rfc.section.2"><a href="#rfc.section.2">2.</a> <a href="#protecting-a-resource" id="protecting-a-resource">Protecting a Resource</a></h1>
<p id="rfc.section.2.p.1">The resource owner, resource server, and authorization server perform the following actions to put resources under protection. This list assumes that the resource server has discovered the authorization server's configuration data and endpoints as needed.</p>

<ol>
  <li>The authorization server issues client credentials to the resource server. It is OPTIONAL for the client credentials to be provided dynamically through <a href="#DynClientReg">[DynClientReg]</a>; alternatively, they MAY use a static process.</li>
  <li>The resource server acquires a PAT from the authorization server.  It is OPTIONAL for the resource owner to introduce the resource server to the authorization server dynamically (for example, through a "NASCAR"-style user interface where the resource owner selects a chosen authorization server); alternatively, they MAY use a static process that may or may not directly involve the resource owner at introduction time.</li>
  <li>In an ongoing fashion, the resource server registers any resource sets with the authorization server for which it intends to outsource protection, using the resource set registration endpoint of the protection API (see <a href="#OAuth-resource-reg">[OAuth-resource-reg]</a>).</li>
</ol>
<p id="rfc.section.2.p.2">Note: The resource server is free to offer the option to 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 can 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.</p>
<p id="rfc.section.2.p.3">Once a resource set has been placed under authorization server protection through the registration of a resource set description for it, and until such a description's deletion by the resource server, the resource server MUST limit access to corresponding resources, requiring sufficient authorization data associated with client-presented RPTs by the authorization server (see <a href="#client-presents-rpt">Section 3.1.2</a>).</p>
<h1 id="rfc.section.3"><a href="#rfc.section.3">3.</a> <a href="#getting-authz-accessing-resource" id="getting-authz-accessing-resource">Getting Authorization and Accessing a Resource</a></h1>
<p id="rfc.section.3.p.1">An authorization server orchestrates and controls clients' access (on their requesting parties' behalf) to a resource owner's protected resources at a resource server, under conditions dictated by that resource owner.</p>
<p id="rfc.section.3.p.2">The process of getting authorization and accessing a resource always begins with the client attempting access at a protected resource endpoint at the resource server. How the client came to learn about this endpoint is out of scope for this specification. The resource owner might, for example, have advertised its availability publicly on a blog or other website, listed it in a discovery service, or emailed a link to a particular intended requesting party.</p>
<p id="rfc.section.3.p.3">The resource server responds to the client's access request with whatever its application-specific resource interface defines as a success response, either immediately or having first performed one or more embedded interactions with the authorization server. Depending on the nature of the resource server's response to an failed access attempt, the client and its requesting party engage in embedded interactions with the authorization server before re-attempting access.</p>
<p id="rfc.section.3.p.4">The interactions are as follows. The recipient of each request message SHOULD respond unless it detects a security concern, such as a suspected denial of service attack that can be mitigated by rate limiting.</p>

<ul>
  <li>The client attempts to access a protected resource.<ul><li>If the access attempt is unaccompanied by an RPT, the resource server registers a suitable requested permission at the authorization server, and then responds with an HTTP 403 (Forbidden) response, a permission ticket, and instructions on where to go to obtain an RPT and authorization data.</li><li>If the access attempt is accompanied by an RPT, the resource server checks the RPT's status.<ul><li>If the RPT is invalid, or if the RPT is valid but has insufficient authorization data, the resource server registers a suitable requested permission at the authorization server, and then responds with an HTTP 403 (Forbidden) response, a permission ticket, and instructions on where to go to obtain a valid RPT and authorization data for it.</li><li>If the RPT is valid, and if the authorization data associated with the token is sufficient for allowing access, the resource server responds with an HTTP 2xx (Success) response.</li></ul></li></ul></li>
  <li>IIf the client received a 403 response and a permission ticket, it asks the authorization server for authorization data that matches the ticket using the authorization request endpoint of the authorization API. If the authorization server needs requesting party claims in order to assess this client's authorization, it engages in a claims-gathering flow.</li>
  <li>If the client does not already have an AAT at the appropriate authorization server to be able to use its authorization API, it first obtains one.<ul><li>If the client does not already have an AAT at the appropriate authorization server to be able to use its authorization API, it first obtains one.</li></ul></li>
</ul>
<p id="rfc.section.3.p.5">The interactions are described in detail in the following sections.</p>
<h1 id="rfc.section.3.1"><a href="#rfc.section.3.1">3.1.</a> <a href="#r-h-attempt-access" id="r-h-attempt-access">Client Attempts to Access Protected Resource</a></h1>
<p id="rfc.section.3.1.p.1">This interaction assumes that the resource server has previously registered one or more resource sets that correspond to the resource to which access is being attempted.</p>
<p id="rfc.section.3.1.p.2">The client attempts to access a protected resource (for example, when an end-user requesting party clicks on a thumbnail representation of the resource to retrieve a larger version). It is expected to discover, or be provisioned or configured with, knowledge of the protected resource and its location out of band. Further, the client is expected to acquire its own knowledge about the application-specific methods made available by the resource server for operating on this protected resource (such as viewing it with a GET method, or transforming it with some complex API call).</p>
<p id="rfc.section.3.1.p.3">The access attempt either is or is not accompanied by an RPT.</p>
<h1 id="rfc.section.3.1.1"><a href="#rfc.section.3.1.1">3.1.1.</a> <a href="#no-rpt" id="no-rpt">Client Presents No RPT</a></h1>
<p>Example of a request carrying no RPT:</p>
<pre>
GET /album/photo.jpg HTTP/1.1
Host: photoz.example.com
...
</pre>
<p id="rfc.section.3.1.1.p.1">If the client does not present an RPT with the request, the resource server uses the protection API to register a requested permission with the authorization server that would suffice for that scope of access (see <a href="#h-am-register-permission">Section 3.2</a>). It then responds with the HTTP 403 (Forbidden) status code, providing the authorization server's URI in an "as_uri" property in the header and the permission ticket it just received from the authorization server in the body in a JSON-encoded "ticket" property.</p>
<p>For example:</p>
<pre>
HTTP/1.1 403 Forbidden
WWW-Authenticate: UMA realm="example",
  as_uri="https://as.example.com"

{
"ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
}
   ...
</pre>
<h1 id="rfc.section.3.1.2"><a href="#rfc.section.3.1.2">3.1.2.</a> <a href="#client-presents-rpt" id="client-presents-rpt">Client Presents RPT</a></h1>
<p>Example of a request carrying an RPT using the UMA bearer RPT profile:</p>
<pre>
GET /album/photo.jpg HTTP/1.1
Authorization: Bearer vF9dft4qmT
Host: photoz.example.com
...
</pre>
<p id="rfc.section.3.1.2.p.1">If the client presents an RPT with its request, the resource server MUST determine the RPT's status (see <a href="#h-am-rpt-status">Section 3.3</a>) before responding.</p>
<p id="rfc.section.3.1.2.p.2">If the RPT is invalid, or if the RPT is valid but has insufficient authorization data for the type of access sought, the resource server uses the protection API to register a requested permission with the authorization server that would suffice for that scope of access (see <a href="#h-am-register-permission">Section 3.2</a>). It then responds with the HTTP 403 (Forbidden) status code and providing the authorization server's URI in an "as_uri" property in the header and the permission ticket it just received from the authorization server in the body in a JSON-encoded "ticket" property.</p>
<p>Example of the resource server's response after having registered a requested permission and received a ticket:</p>
<pre>
HTTP/1.1 403 Forbidden
WWW-Authenticate: UMA realm="example",
  as_uri="https://as.example.com"
  error="insufficient_scope"

{
"ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
}
</pre>
<p id="rfc.section.3.1.2.p.3">If the RPT's status is associated with authorization data that is sufficient for the access sought by the client, the resource server MUST give access to the desired resource.</p>
<p>Example of the resource server's response after having determined that the RPT is valid and associated with sufficient authorization data:</p>
<pre>
HTTP/1.1 200 OK
Content-Type: image/jpeg
...

/9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja
3kAAQAEAAAAPAAA/+4ADkFkb2JlAGTAAAAAAf
/bAIQABgQEBAUEBgUFBgkGBQYJCwgGBggLDAo
KCwoKDBAMDAwMDAwQDA4PEA8ODBMTFBQTExwb
</pre>
<p id="rfc.section.3.1.2.p.4">The resource server MUST NOT give access where the token's status is not associated with sufficient authorization data for the attempted scope of access.</p>
<h1 id="rfc.section.3.2"><a href="#rfc.section.3.2">3.2.</a> <a href="#h-am-register-permission" id="h-am-register-permission">Resource Server Registers Requested Permission With Authorization Server</a></h1>
<p id="rfc.section.3.2.p.1">The resource server uses the protection API's permission registration endpoint to register a requested permission with the authorization server that would be sufficient for the type of access sought. The authorization server returns a permission ticket for the resource server to give to the client in its response. The PAT provided in the API request implicitly identifies the resource owner ("subject") to which the permission applies.</p>
<p id="rfc.section.3.2.p.2">Note: The resource server is free to choose the extent of the requested permission that it registers, as long as it minimally suffices for the type of access attempted by the client. For example, it can choose to register a permission that covers several scopes or a resource set that is greater in extent than the specific resource that the client attempted to access.</p>
<p id="rfc.section.3.2.p.3">The resource server uses the POST method at the endpoint. The body of the HTTP request message contains a JSON object providing the requested permission, using a format derived from the scope description format specified in <a href="#OAuth-resource-reg">[OAuth-resource-reg]</a>, as follows. The object has the following properties:</p>

<dl>
  <dt>resource_set_id</dt>
  <dd style="margin-left: 8">REQUIRED. The identifier for a resource set to which this client is seeking access. The identifier MUST correspond to a resource set that was previously registered.</dd>
  <dt>scopes</dt>
  <dd style="margin-left: 8">REQUIRED. An array referencing one or more identifiers of scopes to which access is needed for this resource set. Each scope identifier MUST correspond to a scope that was registered by this resource server for the referenced resource set.</dd>
</dl>
<p>Example of an HTTP request that registers a requested permission at the authorization server's permission registration endpoint:</p>
<pre>
POST /host/scope_reg_uri/photoz.example.com HTTP/1.1
Content-Type: application/json
Host: as.example.com

{
  "resource_set_id": "112210f47de98100",
  "scopes": [
      "http://photoz.example.com/dev/actions/view",
      "http://photoz.example.com/dev/actions/all"
  ]
}
</pre>
<p id="rfc.section.3.2.p.4">If the registration request is successful, the authorization server responds with an HTTP 201 (Created) status code and includes the Location header in its response as well as the "ticket" property in the JSON-formatted body.</p>
<p id="rfc.section.3.2.p.5">The permission ticket is a short-lived opaque structure whose form is determined by the authorization server. The ticket value MUST be securely random (for example, not merely part of a predictable sequential series), to avoid denial-of-service attacks. Since the ticket is an opaque structure from the point of view of the client, the authorization server is free to include information regarding expiration time within the opaque ticket for its own consumption. When the client subsequently uses the authorization API to ask the authorization server for authorization data to be associated with its RPT, it will submit this ticket to the authorization server.</p>
<p>For example:</p>
<pre>
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://as.example.com/permreg/host/photoz.example.com/5454345rdsaa4543
...

{
"ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
}
</pre>
<p id="rfc.section.3.2.p.6">If the registration request is authenticated properly but fails due to other reasons, the authorization server responds with an HTTP 400 (Bad Request) status code and includes one of the following UMA error codes (see <a href="#uma-error-response">Section 4.2</a>):</p>

<dl>
  <dt>invalid_resource_set_id</dt>
  <dd style="margin-left: 8">The provided resource set identifier was not found at the authorization server.</dd>
  <dt>invalid_scope</dt>
  <dd style="margin-left: 8">At least one of the scopes included in the request was not registered previously by this resource server.</dd>
</dl>
<h1 id="rfc.section.3.3"><a href="#rfc.section.3.3">3.3.</a> <a href="#h-am-rpt-status" id="h-am-rpt-status">Resource Server Determines RPT's Status</a></h1>
<p id="rfc.section.3.3.p.1">The resource server MUST determine a received RPT's status, including both its validity and, if valid, its associated authorization data, before giving or refusing access to the client. An RPT is associated with a set of authorization data that governs whether the client is authorized for access. The token's nature and format are dictated by its profile; the profile might allow it to be self-contained, such that the resource server is able to determine its status locally, or might require or allow the resource server to make a run-time introspection request of the authorization server that issued the token.</p>
<p id="rfc.section.3.3.p.2">This specification makes one type of RPT REQUIRED for the authorization server to support: the UMA bearer token profile, as defined in <a href="#uma-bearer-token-profile">Section 3.3.2</a>.  Implementers MAY define and use other RPT profiles.</p>
<h1 id="rfc.section.3.3.1"><a href="#rfc.section.3.3.1">3.3.1.</a> <a href="#token-introspection" id="token-introspection">Token Introspection</a></h1>
<p id="rfc.section.3.3.1.p.1">Within any RPT profile, when a resource server needs to introspect a token in a non-self-contained way to determine its status, it MAY require, allow, or prohibit use of the OAuth token introspection endpoint (defined by <a href="#OAuth-introspection">[OAuth-introspection]</a>) that is part of the protection API, and MAY profile its usage. The resource server MUST use the POST method in interacting with the endpoint, not the GET method also defined by <a href="#OAuth-introspection">[OAuth-introspection]</a>.</p>
<h1 id="rfc.section.3.3.2"><a href="#rfc.section.3.3.2">3.3.2.</a> <a href="#uma-bearer-token-profile" id="uma-bearer-token-profile">RPT Profile: Bearer</a></h1>
<p id="rfc.section.3.3.2.p.1">This section defines the UMA bearer token profile. Following is a summary:</p>

<ul>
  <li>Identifying URI: http://docs.kantarainitiative.org/uma/profiles/uma-token-bearer-1.0</li>
  <li>Profile author and contact information: Thomas Hardjono (hardjono@mit.edu)</li>
  <li>Updates or obsoletes: None; this profile is new.</li>
  <li>Keyword in HTTP Authorization header: "Bearer".</li>
  <li>Syntax and semantics of token data: As defined below. The token data format mainly involves time-bounded permissions.</li>
  <li>Token data association: The data associated to the on-the-wire token by reference and retrieved at run time by the resource server through profiled use of the OAuth token introspection endpoint <a href="#OAuth-introspection">[OAuth-introspection]</a>, as defined below.</li>
  <li>Token data processing: As defined in this section and throughout <a href="#getting-authz-accessing-resource">Section 3</a> of this specification.</li>
  <li>Grant type restrictions: None.</li>
  <li>Error states: As defined below.</li>
  <li>Security and privacy considerations: As defined in this section and throughout <a href="#getting-authz-accessing-resource">Section 3</a> of this specification.</li>
  <li>Binding obligations: Because this RPT profile is mandatory for authorization servers to implement, binding obligations related to the use of this token profile are documented in <a href="#UMA-obligations">[UMA-obligations]</a>.</li>
</ul>
<p id="rfc.section.3.3.2.p.2">On receiving an RPT of the "Bearer" type in an authorization header from a client making an access attempt, the resource server introspects the token by using the token introspection endpoint of the protection API. The PAT used by the resource server to make the introspection request provides resource-owner context to the authorization server.</p>
<p id="rfc.section.3.3.2.p.3">The authorization server responds with a JSON object with the structure dictated by <a href="#OAuth-introspection">[OAuth-introspection]</a>. If the valid property has a "true" value, then the JSON object MUST also contain an extension property with the name "permissions" that contains an array of zero or more values, each of which is an object consisting of these properties:</p>

<dl>
  <dt>resource_set_id</dt>
  <dd style="margin-left: 8">REQUIRED. A string that uniquely identifies the resource set, access to which has been granted to this client on behalf of this requesting party. The identifier MUST correspond to a resource set that was previously registered as protected.</dd>
  <dt>scopes</dt>
  <dd style="margin-left: 8">REQUIRED. An array referencing one or more URIs of scopes to which access was granted for this resource set. Each scope MUST correspond to a scope that was registered by this resource server for the referenced resource set.</dd>
  <dt>expires_at</dt>
  <dd style="margin-left: 8">REQUIRED. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this permission will expire.</dd>
  <dt>issued_at</dt>
  <dd style="margin-left: 8">OPTIONAL. Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this permission was originally issued.</dd>
</dl>
<p>Example:</p>
<pre>
HTTP/1.1 200 OK
   Content-Type: application/json
   Cache-Control: no-store

   {
    "valid": true,
    "expires_at": "1256953732",
    "issued_at": "1256912345",
    "permissions": [
      {
        "resource_set_id": "112210f47de98100",
        "scopes": [
          "http://photoz.example.com/dev/actions/view",
          "http://photoz.example.com/dev/actions/all"
         ],
        "expires_at" : "1256923456"
      }
    ]
   }
</pre>
<h1 id="rfc.section.3.4"><a href="#rfc.section.3.4">3.4.</a> <a href="#r-am-obtain-permission" id="r-am-obtain-permission">Client Seeks Authorization for Access</a></h1>
<p id="rfc.section.3.4.p.1">In order to access a protected resource successfully, a client needs to present a valid RPT with sufficient authorization data for access. To get to this stage requires a number of previously successful steps:</p>

<ol>
  <li>The authorization server issues client credentials to the client. It is OPTIONAL for the client credentials to be provided dynamically through <a href="#DynClientReg">[DynClientReg]</a>; alternatively, they MAY use a static process.</li>
  <li>The client acquires an AAT.</li>
  <li>The client uses the authorization API to acquire an RPT and to ask for authorization data, providing the permission ticket it got from the resource server. The authorization server associates authorization data with the RPT based on the permission ticket, the resource owner's operative policies, and the results of any claims-gathering flows.</li>
</ol>
<h1 id="rfc.section.3.4.1"><a href="#rfc.section.3.4.1">3.4.1.</a> <a href="#authz-permission-token" id="authz-permission-token">Client Obtains RPT</a></h1>
<p id="rfc.section.3.4.1.p.1">Once in possession of a permission ticket and an AAT for this authorization server, the client asks the authorization server to give it authorization data corresponding to that permission ticket.  It performs a POST on the authorization request endpoint, supplying its own AAT in the header and with a JSON object in the body with the property &#8220;ticket&#8221; containing the ticket as its value. If the client had included an RPT in its failed access attempt, It MAY also provide that RPT in an "rpt" property in its request to the authorization server.</p>
<p>Example of a request message containing an AAT, an RPT, and a permission ticket:</p>
<pre>POST /authz_request HTTP/1.1
Host: as.example.com
Authorization: Bearer jwfLG53^sad$#f
...

{
 "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
 "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de"
}</pre>
<p id="rfc.section.3.4.1.p.2">The authorization server uses the ticket to look up the details of the previously registered requested permission, maps the requested permission to operative resource owner policies based on the resource set identifier and scopes in it, undergoes any claims-gathering flows required (see <a href="#authz-flows">Section 3.5</a>), and ultimately responds to the request.</p>
<p id="rfc.section.3.4.1.p.3">The authorization server bases the issuing of authorization data on resource owner policies. The nature of these policies is outside the scope of UMA, but generally speaking, they can be thought of as either independent of requesting-party features (for example, dictating access based on time of day or client identity) or dependent on requesting-party features (for example, dictating access based on whether they are over 18 or present a certain identifier). Such requesting-party features can potentially be collected in a claims-gathering flow.</p>
<p id="rfc.section.3.4.1.p.4">The resource owner's policies at the authorization server amount to an implicit OAuth authorization grant in governing the issuance of authorization data. (The authorization server is also free to enable the resource owner to set policies that require the owner to provide a run-time authorization grant in the form of a consent interaction, mediated by the authorization server. This setting of policies and gathering of consent is outside the scope of this specification.)</p>
<p id="rfc.section.3.4.1.p.5">Once the authorization server adds the requested authorization data, it returns an HTTP 200 status code with a response body containing the RPT with which it associates the requested authorization data. If the client did not present an RPT in the request for authorization data, the authorization server creates and returns a new RPT. If the client did present an RPT in the request, the authorization server returns the RPT with which it associated the requested authorization data, which may be either the RPT that was in the request or a new one. Note: It is entirely an implementation issue whether the returned RPT is the same one that appeared in the request or a new RPT, and it is also an implementation issue whether the AS chooses to invalidate or retain the validity of the original RPT or any authorization data that was previously added to that RPT; to assist in client interoperablity and token caching expectations, it is RECOMMENDED for authorization servers to document their practices.</p>
<p>Example:</p>
<pre>
HTTP/1.1 200 Success
Content-Type: application/json

{
  "rpt": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv"
}

</pre>
<p id="rfc.section.3.4.1.p.6">If the authorization server does not add the requested authorization data, it responds using the appropriate HTTP status code and UMA error code (see <a href="#uma-error-response">Section 4.2</a>): </p>

<dl>
  <dt>invalid_ticket</dt>
  <dd style="margin-left: 8">The provided ticket was not found at the authorization server. The authorization server responds with the HTTP 400 (Bad Request) status code.</dd>
  <dt>expired_ticket</dt>
  <dd style="margin-left: 8">The provided ticket has expired.  The authorization server responds with the HTTP 400 (Bad Request) status code.</dd>
  <dt>not_authorized</dt>
  <dd style="margin-left: 8">The client is definitively not authorized for access. The authorization server responds with the HTTP 403 (Forbidden) status code.</dd>
  <dt>need_claims</dt>
  <dd style="margin-left: 8">The authorization server is unable to determine whether the client is authorized for this permission without gathering requesting party claims. The authorization server responds with the HTTP 403 (Forbidden) status code. The client is therefore not authorized, but has the opportunity to engage in a requesting party claims-gathering flow (see <a href="#authz-flows">Section 3.5</a>) to continue seeking authorization.</dd>
</dl>
<p>Example when the ticket has expired:</p>
<pre>
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
...

{
  "error": "expired_ticket"
}
</pre>
<h1 id="rfc.section.3.5"><a href="#rfc.section.3.5">3.5.</a> <a href="#authz-flows" id="authz-flows">Claims-Gathering Flows</a></h1>
<p id="rfc.section.3.5.p.1">The authorization server has a variety of options for coming into possession of claims in order to satisfy the resource owner's policy; this specification does not dictate a single answer. For example, the authorization server could interact with the requesting party to gather claims, or could accept claims delivered by a client, or could perform a lookup in some external system. The process for requesting and providing claims is extensible and can have a variety of dependencies on the type of requesting party (for example, natural person or legal person) and the type of client (for example, browser, native app, or autonomously running web service).</p>
<p id="rfc.section.3.5.p.2">This specification provides a required framework for extensibility through profiling. The authorization server MAY support any number of claim profiles, and SHOULD document the claim profiles it supports in its configuration data. For the business-level and legal implications of different claim profiles, see <a href="#UMA-obligations">[UMA-obligations]</a>. Optional claim profiles are defined in <a href="#UMAclaims">[UMAclaims]</a>.</p>
<p id="rfc.section.3.5.p.3">A client is operated by an end-user in one of two typical situations:</p>

<ul>
  <li>The requesting party is a natural person (for example, a friend or family member of the resource owner); the requesting party may even be the resource owner herself.</li>
  <li>The requesting party is a legal person such as a corporation, and the end-user operating the client is acting as an agent of that legal person (for example, a customer support specialist representing a credit card company).</li>
</ul>
<p id="rfc.section.3.5.p.4">Where a claim profile dictates end-user interaction, a further variety of options is possible. The end-user could be required to register for and/or log in to an account or personal profile, or fill in a questionnaire, or complete a purchase. Several of these operations could even be required, where the order is treated as significant for evaluating resource owner policies.</p>
<h1 id="rfc.section.4"><a href="#rfc.section.4">4.</a> <a href="#errors" id="errors">Error Messages</a></h1>
<p id="rfc.section.4.p.1">Ultimately the resource server is responsible for either granting the access the client attempted, or returning an error response to the client with a reason for the failure. <a href="#OAuth2">[OAuth2]</a> defines several error responses for a resource server to return. UMA makes use of these error responses, but requires the resource server to "outsource" the determination of some error conditions to the authorization server. This specification defines additional UMA-specific error responses that the authorization server may give to the resource server and client as they interact with it, and that the resource server may give to the client.</p>
<h1 id="rfc.section.4.1"><a href="#rfc.section.4.1">4.1.</a> <a href="#oauth-error-response" id="oauth-error-response">OAuth Error Responses</a></h1>
<p id="rfc.section.4.1.p.1">When a resource server or client attempts to access one of the authorization server endpoints or a client attempts to access a protected resource at the resource server, it has to make an authenticated request by including an OAuth access token in the HTTP request as described in <a href="#OAuth2">[OAuth2]</a> Section 7.2.</p>
<p id="rfc.section.4.1.p.2">If the request failed authentication, the authorization server or the resource server responds with an OAuth error message as described throughout <a href="#protecting-a-resource">Section 2</a> and <a href="#getting-authz-accessing-resource">Section 3</a>.</p>
<h1 id="rfc.section.4.2"><a href="#rfc.section.4.2">4.2.</a> <a href="#uma-error-response" id="uma-error-response">UMA Error Responses</a></h1>
<p id="rfc.section.4.2.p.1">When a resource server or client attempts to access one of the authorization server endpoints or a client attempts to access a protected resource at the resource server, if the request is successfully authenticated by OAuth means, but is invalid for another reason, the authorization server or resource server responds with an UMA error response by adding the following properties to the entity body of the HTTP response: </p>

<dl>
  <dt>error</dt>
  <dd style="margin-left: 8">REQUIRED. A single error code. Values for this property are defined throughout this specification.</dd>
  <dt>error_description</dt>
  <dd style="margin-left: 8">OPTIONAL. Human-readable text providing additional information.</dd>
  <dt>error_uri</dt>
  <dd style="margin-left: 8">OPTIONAL. A URI identifying a human-readable web page with information about the error.</dd>
</dl>
<p id="rfc.section.4.2.p.2">The following is a common error code that applies to several UMA-specified request messages: </p>

<dl>
  <dt>invalid_request</dt>
  <dd style="margin-left: 8">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.</dd>
</dl>
<p>For example:</p>
<pre>
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
...

{
  "error": "invalid_request",
  "error_description": "There is already a resource with this identifier.",
  "error_uri": "http://as.example.com/errors/resource_exists"
}
</pre>
<h1 id="rfc.section.5"><a href="#rfc.section.5">5.</a> <a href="#comms-profiles" id="comms-profiles">Profiles for API Extensibility</a></h1>
<p id="rfc.section.5.p.1">In some circumstances, it is desirable to couple UMA roles tightly.  For example, an authorization server application might also need to act as a client application in order to retrieve protected resources so that it can present to resource owners a dashboard-like user interface that accurately guides the setting of policy; it might need to access itself-as-authorization server for that purpose. For another example, the same organization might operate both an authorization server and a resource server that communicate only with each other behind a firewall, and it might seek more efficient communication methods between them.</p>
<p id="rfc.section.5.p.2">This section defines profiles that allow inter-role communications channels and methods to vary in these specific circumstances. This specification still REQUIRES authorization servers to issue PATs, AATs, and RPTs and associate authorization data with RPTs, and REQUIRES resource servers to give clients access only when RPTs are associated with sufficient authorization data. This is because, although tokens might not always appear on the wire in the normal fashion in these cases, they represent binding obligations that might involve additional parties unable to take part in these optimization opportunities (see <a href="#UMA-obligations">[UMA-obligations]</a>).</p>
<p id="rfc.section.5.p.3">In circumstances where alternate communications channels are being used between independently implemented system entities, it is RECOMMENDED, for reasons of implementation interoperability, to define concrete extension profiles that build on these extensibility profiles (see <a href="#uma-profiles">Section 6.1</a>).</p>
<p id="rfc.section.5.p.4">An authorization server using any of the opportunities afforded by the protection and/or authorization API extensibility profile MUST declare use of each profile by supplying the relevant "uma_profiles_supported" values in its configuration data (see <a href="#am-endpoints">Section 1.4</a>).</p>
<h1 id="rfc.section.5.1"><a href="#rfc.section.5.1">5.1.</a> <a href="#alt-prot-profile" id="alt-prot-profile">Protection API Extensibility Profile</a></h1>
<p id="rfc.section.5.1.p.1">This section defines a profile for UMA where the authorization server and resource server roles either reside in the same system entity or otherwise have a privileged communications channel between them. Following is a summary:</p>

<ul>
  <li>Identifying URI: http://docs.kantarainitiative.org/uma/profiles/prot-ext-1.0</li>
  <li>Profile author and contact information: Mark Dobrinic (mdobrinic@cozmanova.com)</li>
  <li>Updates or obsoletes: None; this profile is new.</li>
  <li>Security considerations: If the entities do not use TLS but communicate across a transport layer as opposed to using internal same-entity communication, it is STRONGLY RECOMMENDED to use an alternate means of transport-layer security.</li>
  <li>Privacy considerations: If the relationship between the roles is established in a manner that does not involve the resource owner at all, they each may maliciously leverage this relationship to observe the resource owner's personally identifiable information held in each system.</li>
  <li>Error states: See below.</li>
  <li>Binding obligations: Any applicable binding obligations are documented in <a href="#UMA-obligations">[UMA-obligations]</a>.</li>
</ul>
<p id="rfc.section.5.1.p.2">Using this profile, the resource server MAY use means other than the TLS- and OAuth-protected HTTP-based protection API to communicate with the authorization server. This involves the following opportunities:</p>

<ul>
  <li>A PAT MAY be issued without requiring an OAuth flow to establish one.</li>
  <li>Resource sets MAY be registered (or configured) without requiring explicit use of the resource set registration endpoint or presentation of a PAT in any registration request.</li>