-
Notifications
You must be signed in to change notification settings - Fork 15
/
Copy pathindex.html
2417 lines (1948 loc) · 94.6 KB
/
index.html
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>
<html lang="en">
<head>
<meta name="generator" content=
"HTML Tidy for HTML5 (experimental) for Linux https://github.com/w3c/tidy-html5/tree/c63cc39">
<meta http-equiv="Content-Type" content=
"text/html; charset=utf-8">
<meta charset="utf-8">
<title>Blue Button+ REST API</title>
<meta name="viewport" content=
"width=device-width, initial-scale=1.0">
<meta name="description" content="">
<meta name="author" content=""><!-- Le styles -->
<link href="assets/css/bootstrap.css" rel="stylesheet">
<link href="assets/css/bootstrap-responsive.css" rel=
"stylesheet">
<link href="assets/css/docs.css" rel="stylesheet">
<link rel="stylesheet" href="assets/css/gh-fork-ribbon.css">
<!--[if IE]>
<link rel="stylesheet" href="assets/css/gh-fork-ribbon.ie.css" />
<![endif]-->
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src="assets/js/html5shiv.js"></script>
<![endif]-->
</head>
<body data-spy="scroll" data-target=".bs-docs-sidebar"
data-twttr-rendered="true">
<div class="github-fork-ribbon-wrapper right">
<div class="github-fork-ribbon">
<a href=
"https://github.com/blue-button/blue-button-plus-pull">Fork
me on GitHub</a>
</div>
</div><!-- Navbar
================================================== -->
<!-- Subhead
================================================== -->
<header class="jumbotron subhead" id="overview">
<div class="container">
<h1>Blue Button REST API</h1>
<p class="lead">OAuth2 API for RESTful access to patient data</p>
</div>
</header>
<div class="container">
<!-- Docs nav
================================================== -->
<div class="row">
<div class="span3 bs-docs-sidebar">
<ul class="nav nav-list bs-docs-sidenav" data-offset-top=
"200">
<li>
<a href="#registration"><i class=
"icon-chevron-right"></i> App Registration <span class=
"label section label-success">Common</span></a>
</li>
<li class="sidenav-indent">
<a href="#client-types"><i class=
"icon-chevron-right"></i> Client Types</a>
</li>
<li class="sidenav-indent">
<a href="#registration-open"><i class=
"icon-chevron-right"></i> Open Registration</a>
</li>
<li class="sidenav-indent">
<a href="#registration-trusted"><i class=
"icon-chevron-right"></i> Trusted Registration</a>
</li>
<li>
<a href="#discovery"><i class="icon-chevron-right"></i>
Endpoint Discovery <span class=
"label section label-success">Common</span></a>
</li>
<li class="sidenav-indent">
<a href="#discovery-registry"><i class=
"icon-chevron-right"></i> BB+ Registries</a>
</li>
<li class="sidenav-indent">
<a href="#discovery-providers"><i class=
"icon-chevron-right"></i>Registered Providers</a>
</li>
<li class="sidenav-indent">
<a href="#discovery-apps"><i class=
"icon-chevron-right"></i>Registered Apps</a>
</li>
<li>
<a href="#scopes"><i class=
"icon-chevron-right"></i> Standard Scopes
<span class="label section label-success">Common</span></a>
</li>
<li>
<a href="#authorization"><i class=
"icon-chevron-right"></i> App Authorization
<span class="label section label-info">Pull</span></a>
</li>
<li class="sidenav-indent">
<a href="#authorization-code"><i class=
"icon-chevron-right"></i> Authorization Code Grant</a>
</li>
<li class="sidenav-indent">
<a href="#authorization-implicit"><i class=
"icon-chevron-right"></i> Implicit Grant</a>
</li>
<li>
<a href="#clinical-api"><i class="icon-chevron-right"></i>
Clinical Data API <span class=
"label section label-info">Pull</span> </a>
</li>
<li class="sidenav-indent">
<a href="#clinical-summary"><i class=
"icon-chevron-right"></i> Clinical Summary</a>
</li>
<li class="sidenav-indent">
<a href="#clinical-search"><i class=
"icon-chevron-right"></i> Document Search</a>
</li>
<li class="sidenav-indent">
<a href="#clinical-document-retrieval"><i class=
"icon-chevron-right"></i> Document Retrieval</a>
</li>
<li>
<a href="#push-authorization"><i class=
"icon-chevron-right"></i> Push Authorization
<span class=
"label section label-warning">Push</span></a>
</li>
<li>
<a href="#demo"><i class=
"icon-chevron-right"></i> Demo App</a>
</li>
<li>
<a href="#authors"><i class=
"icon-chevron-right"></i> Authors</a>
</li>
</ul>
</div>
<div class="span7">
<section id="explanation">
<div class="well alert-info">
<strong>Note:</strong> This page documents
specifications applicable to both BB+ <span class=
"label section label-warning">Push</span> (Direct email
transport) and BB+ <span class=
"label section label-info">Pull</span> (HTTP RESTful
transport) protocols. It is the goal of this proposal
to re-use <span class=
"label section label-success">Common</span> components
for Push and Pull apps. In this way, a system
implementing both would be able to re-use the same code
and patterns for common activities such as end-user
authorization, dynamic client registration, and service
discovery.
</div>
</section>
<section id="registration">
<div class="page-header">
<h1>App Registration <small>up-front,
partially-automated</small> <span class=
"label label-success">Common</span></h1></div>
<p>Before an app connects to a BlueButton+ provider, it
registers with that provider as an OAuth2 Client. The
registration process informs the provider what the app
is called, where to find it, what permissions it might
ask patients for, and how to display an authorization
screen to patients.</p>
<p>BB+ apps register with providers using <a href=
"http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg">OAuth2
Dynamic Client Registration</a>. This guide walks
through the process of registering a client using open
registration, as well as an example of using trusted
registration which leverages BB+ Registries.</p>
<h2 id="client-types">Client Types</h2>
<p>BlueButton+ allows for several different types of clients and use cases that are differentiated along two axes: whether or not a client can reasonably guard its <code>client_secret</code> at runtime, and whether or not it can guard its <code>registration_jwt</code> at runtime (if it has one). The OAuth 2 specification defines the former class distinction as "confidential" and "public" clients, but there is not existing terminology for the latter classification. This combination leads us to a matrix of six possible application styles:</p>
<small>
<table class="table table-bordered table-hover">
<tr>
<td></td>
<th> Can guard <code>client_secret</code></th>
<th> Can <strong>NOT</strong> guard <code>client_secret</code></th>
</tr>
<tr>
<th> Can guard <code>registration_jwt</code></th>
<td><a href="#clients-trusted-confidential"> Trusted Confidential App</a></td>
<td><a href="#clients-trusted-public"> Trusted Public App</a></td>
</tr>
<tr>
<th> Can <strong>NOT</strong> guard <code>registration_jwt</code></th>
<td><a href="#clients-semitrusted-confidential"> Semi-Trusted Confidential App</a></td>
<td><a href="#clients-semitrusted-public"> Semi-Trusted Public App</a></td>
</tr>
<tr>
<th> No <code>registration_jwt</code></th>
<td><a href="#clients-experimental-confidential"> Experimental Confidential App</a></td>
<td><a href="#clients-experimental-public"> Experimental Public App</a></td>
</tr>
</table>
</small>
<p>When deciding whether and how to register with a Registry Service, a client application developer MUST determine which of the above categories are appropriate for their application. Application developers must take care to select the appropriate category for their application based on its runtime capabilites as well as policies around the data. A Registry should help enable these distinctions by explicitly asking application develoeprs about the capabilities of their applications in order to determine which policies to apply.</p>
<h3 id="clients-trusted-confidential"> Trusted Confidential Application</h3>
<h5>Examples:</h5>
<ul>
<li>Web application where all API interactions between client and provider happen in the back channel ("server-side, away from the end-user"). This is the recommended mode for web-server based applications.</li>
<li>Native applications that can be issued a per-instance <code>registration_jwt</code> (using mechanisms outside the scope of this specification)</li>
</ul>
<h5>Policies:</h5>
<ul>
<li>Uses trusted registration</li>
<li>This is the setup with the highest assurance. Therefore authorization server can present the user with its least-scary authorization screen.</li>
<li>If the <code>registration_jwt</code> or <code>client_secret</code> are exposed, it should be considered a major security breach and system-wide invalidation of the application's instances (and re-provisioning of its <code>registration_jwt</code>) are reasonable and expected countermeasures.</li>
</ul>
<h3 id="clients-trusted-public" > Trusted Public Application</h3>
<h5>Examples:</h5>
<ul>
<li>Split server-side/in-browser application that handles dynamic registration in the back-end (server-side) but performs authorization in the browser (likely using implicit flow)</li>
</ul>
<h5>Policies:</h5>
<ul>
<li>Uses trusted registration</li>
<li>An application MUST pre-register its <code>redirect_uri</code>s at the Registry Service and the authorization server MUST enforce them.</li>
<li>On the authorization page, the authorization server should disclose the name and URI of the application for users to confirm that it matches what they think they're using</li>
<li>If the <code>registration_jwt</code> is exposed, it should be considered a major security breach and system-wide invalidation of the application's instances (and re-provisioning of its <code>registration_jwt</code>) are reasonable and expected countermeasures.</li>
</ul>
<h3 id="clients-semitrusted-confidential" > Semi-Trusted Confidential Application</h3>
<h5>Examples:</h5>
<ul>
<li>Self-sufficient native applications that register themselves separately per installation instance based on their pre-registered parameters.</li>
</ul>
<h5>Policies:</h5>
<ul>
<li>Uses trusted registration</li>
<li>The <code>registration_jwt</code> is packaged in with the application and is therefore available to all end-users. This means that any holder of this JWT could try to register with this application's parameters and it must not be trusted for access without a user's explicit consent.</li>
<li>Authorizations servers MUST present users with the name and URI of the application that is being authorized and appropriately caution users.</li>
<li>An application MUST pre-register its <code>redirect_uri</code>s at the Registry Service and the authorization server MUST enforce them.</li>
<li>An application SHOULD pre-register as many parameters as possible at the Registry Service and the authorization server MUST enforce them.</li>
</ul>
<h3 id="clients-semitrusted-public" > Semi-Trusted Public Application</h3>
<h5>Examples:</h5>
<ul>
<li>In-browser javascript applications that handle dynamic registration and authorization (using the implicit flow) on their own</li>
</ul>
<h5>Policies:</h5>
<ul>
<li>Uses trusted registration</li>
<li>The <code>registration_jwt</code> is packaged in with the application and is therefore available to all end-users. This means that any holder of this JWT could try to register with this application's parameters and it must not be trusted for access without a user's explicit consent.</li>
<li>Authorizations servers MUST present users with the name and URI of the application that is being authorized and appropriately caution users.</li>
<li>An application SHOULD pre-register as many parameters as possible at the Registry Service and the authorization server MUST enforce them.</li>
<li>This is likely to be a rare case in BB+.</li>
</ul>
<h3 id="clients-experimental-confidential" > Experimental Confidential Application</h3>
<h5>Examples:</h5>
<ul>
<li>Weekend project / prototype of a web or native client to be used by app developers, their friends, and family</li>
</ul>
<h5>Policies:</h5>
<ul>
<li>Uses open registration</li>
<li>Authorization page MUST display a warning to users that the identity of the application is unverified and MUST state that users should proceed only if they trust the app's presented <code>redirect_uri</code></li>
<li>An authorization server MAY display statistics such as how many other users have authorized this application in order to help the user make their decision.</li>
</ul>
<h3 id="clients-experimental-public" > Experimental Public Application</h3>
<h5>Examples:</h5>
<ul>
<li>Weekend project / prototype of an in-browser or native client to be used by app developers, their friends, and family</li>
</ul>
<h5>Policies:</h5>
<ul>
<li>Uses open registration</li>
<li>Authorization page MUST display a warning to users that the identity of the application is unverified and MUST state that users should proceed only if they trust the app's presented <code>redirect_uri</code></li>
<li>An authorization server MAY display statistics such as how many other users have authorized this application in order to help the user make their decision.</li>
</ul>
<h2 id="registration-open">Open
Registration</h2>BlueButton+ providers <strong>must offer</strong> an open
registration option. To register, an app issues an
<code>https POST</code> to the registration endpoint,
supplying registration parameters as a JSON object.
<div class="well alert-info">
<strong>Note</strong>: Open registration is
appropriate for new and experimental apps, but
patient-facing authorization screens should display a
warning indicating that an app's identity has not
been verified. To provide a higher level of
assurance, apps can perform a Trusted Registration
(described below).
</div>
<div class="wsd" wsd_style="napkin"><pre>
Title: BlueButton+ Open Registration Process
participant App
participant Provider
App->Provider: Registration Request (no JWT)
Provider->App: client_id + secret + registration token
</pre></div>
<h3 id="registration-parameters">Registration
Parameters</h3>
<table class="table table-striped">
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
<tr>
<td><code>client_name</code></td>
<td><code>string</code></td>
<td>Human-readable name of the Client to be
presented to the user.</td>
</tr>
<tr>
<td><code>client_uri</code></td>
<td><code>string</code></td>
<td>URL of the homepage of the Client.</td>
</tr>
<tr>
<td><code>logo_uri</code></td>
<td><code>string</code></td>
<td>URL that references a logo for the Client. If
present, the server SHOULD display this image to
the end user during approval</td>
</tr>
<tr>
<td><code>tos_uri</code></td>
<td><code>string</code></td>
<td>URL that points to a human-readable Terms of
Service for the Client. The Authorization Server
SHOULD display this URL to the End-User if it is
given.</td>
</tr>
<tr>
<td><code>redirect_uris</code></td>
<td><code>array</code></td>
<td>Array of redirect URIs for use in the
Authorization Code and Implicit grant types. An
Authorization Server SHOULD require registration of
valid redirect URIs for all clients that use these
grant types in order to protect against token and
credential theft attacks.</td>
</tr>
<tr>
<td><code>response_types</code></td>
<td><code>array</code></td>
<td>
Array of the OAuth 2.0 response types that the
Client may use.
<ul>
<li>public clients: <code>"token"</code> or
<code>"code"</code></li>
<li>confidential clients:
<code>"code"</code></li>
</ul>
</td>
</tr>
<tr>
<td><code>token_endpoint_auth_method</code></td>
<td><code>string</code></td>
<td>
The requested authentication type for the Token
Endpoint.
<ul>
<li>public clients: <code>"none"</code></li>
<li>confidential clients:
<code>"client_secret_basic"</code></li>
</ul>
</td>
</tr>
<tr>
<td><code>grant_types</code></td>
<td><code>array</code></td>
<td>
Array of OAuth 2.0 grant types that the Client
may use.
<ul>
<li>public clients: <code>["implicit"]</code>
or <code>["authorization_code"]</code></li>
<li>confidential clients:
<code>["authorization_code"]</code></li>
</ul>
</td>
</tr>
<tr>
<td><code>scope</code></td>
<td><code>string</code></td>
<td>Space separated list of scope values (as
described in OAuth 2.0 Section 3.3 [RFC6749]) that
the client is declaring that it may use when
requesting access tokens. A valid BB+ scope must
include one or both of:
<code>search</code>
and
<code>summary</code></td>
</tr>
<tr>
<td><code>contacts</code></td>
<td><code>array</code></td>
<td>Array of email addresses for people responsible
for this Client. The Authorization Server MAY make
these addresses available to end users for support
requests for the Client. An Authorization Server
MAY use these email addresses as identifiers for an
administrative page for this client.</td>
</tr>
</table>
<h3>Example Registration for a Public Client</h3>
<pre class="prettyprint">
POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: bbplus-provider.org
{
"client_name": "Blood Pressure Grapher",
"client_uri": "https://bpgrapher.org",
"logo_uri": "http://bpgrapher.org/images/logo.png",
"contacts": [
],
"tos_uri": "https://bpgrapher.org/tos",
"redirect_uris": [
"https://bpgrapher.org/after-auth"
],
"response_types": ["token"],
"grant_types": ["implicit"],
"token_endpoint_auth_method": "none",
"scope": "summary"
}
</pre>
<h3>Example Registration for a Confidential Client</h3>
<pre class="prettyprint">
POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: bbplus-provider.org
{
"client_name": "Blood Pressure Grapher",
"client_uri": "https://bpgrapher.org",
"logo_uri": "http://bpgrapher.org/images/logo.png",
"contacts": [
],
"tos_uri": "https://bpgrapher.org/tos",
"redirect_uris": [
"https://bpgrapher.org/after-auth"
],
"response_types": ["code"],
"grant_types": ["authorization_code"],
"token_endpoint_auth_method": "client_secret_basic",
"scope": "summary"
}
</pre>
<p>The client will receive a unique
<code>client_id</code> for that service provider,
a <code>client_secret</code> that it can use to authorize at
the token endpoint, as well as a
<code>registration_access_token</code> that it can use
to maintain its registration at the registration endpoint, as described in
OAuth Dynamic Client Registration.</p>
<h2 id="registration-trusted">Trusted Registration</h2>
<p>In addition to open registration, BlueButton+
providers support a Trusted Registration option. When
performing a Trusted Registration, apps follow the
protocol described above, with the addition of a bearer
token from a BB+ Registry that the provder trusts. This
trusted bearer token is a <a href=
"http://tools.ietf.org/html/draft-ietf-oauth-json-web-token">
JSON Web Token</a> signed with <a href=
"http://tools.ietf.org/html/draft-jones-json-web-signature">
JSON Web Signature</a> and is verifiable by the service
provider.</p>
<div class="well alert-info">
<h4>Background: Client Classes and Client
Instances</h4>
<p>BB+ expects that most apps will connect to
<em>multiple BB+ providers</em>, and many apps will
run directly from <em>multiple end-user devices</em>.
This specification balances a desire for fine-grained
app registration (e.g. auditing each device's access
history independently) with a need for
coarser-grained permissions (e.g. disabling a rogue
app across all providers, or all devices). We achieve
this balance by enabling two points of control:
<em>Client Classes</em> and <em>Client
Instances</em>.</p>
<p>As an example to illustrate this distinction,
let's consider an iOS-based Blood Pressure Grapher.
This app is considered a "Client Class" because it's
associated with a single author, homepage, logo,
Terms of Service agreement, etc. As we'll describe
below, this class has instances for each BB+ Provider
the Blood Pressure Grapher registers with, and
possibly for each device it runs on.</p>
<p><strong>Client Instances per-Provider</strong> In
the OAuth sense, the BP Grapher app has a separate
"instance" for each (app, provider) pair it
participates in. For example, it will likely use a distinct
<code>client_id</code> to communicate with each BB+
provider. (Since <code>client_id</code> is assigned
by each provider as part of the normal OAuth Dynamic
Registration process, apps generally <em>will</em>
have have distinct identifiers for each provider.)
Still, since these instances all represent "the same
app", they belong to the same <strong>Client
Class</strong>.</p>
<p><strong>Client Instances per-Device</strong>
Similarly, if the Blood Pressure Grapher is installed
on multiple iOS devices, it will be assigned a
separate <code>client_id</code> for each
(app-on-device, provider) pair it participates in.
(Since <code>client_id</code> is assigned by each
provider as part of the normal OAuth Dynamic
Registration process, apps <em>MUST be assigned</em>
distinct identifiers per-device by each provider.)
Again, since these instances all represent "the same
app," they belong to the same <strong>Client
Class</strong>.</p>
<p><strong>Instance- and Class-level
Controls</strong> In this way, BB+ Providers MUST assign
each instance of a Client Class a different
<code>client_id</code>, as stated in <a href="http://tools.ietf.org/html/draft-ietf-oauth-dyn-reg">OAuth 2 Dynamic Registration section 5.1</a>. Apps
MUST simply use the identifiers assigned. No matter which instance
identifiers are assigned, BB+ Providers maintain the
ability to make decisions at the Class level, so if
the Blood Pressure Grapher loses trust, all of its
instances can be disabled in one fell swoop.</p>
</div>
<h3>Process overview:</h3>
<div class="wsd" wsd_style="napkin"><pre>
Title: BlueButton+ Trusted Registration Process
participant App
participant Provider
participant "BB+ Registry"
note over App,"BB+ Registry": Manual pre-registration
App-->BB+ Registry: Register for membership
BB+ Registry-->BB+ Registry: Verify app claims
BB+ Registry-->BB+ Registry: Store app claims,\nmake available for discovery
BB+ Registry-->App: Signed Registration JWT
note over App: Time passes... time to register
App->BB+ Registry: Lookup provider
BB+ Registry->App: Provider information
App->Provider: Registration Request + JWT
Provider->Provider: Validate issuer
Provider->BB+ Registry: Get Registry discovery information
BB+ Registry->Provider: Registry discovery information
Provider->BB+ Registry: Lookup signing key
BB+ Registry->Provider: JWK Set
Provider->Provider: Validate signature
Provider->BB+ Registry: Lookup app claims
BB+ Registry->Provider: Pre-registered app claims
Provider->Provider: Verify reg matches claims
Provider->App: client_id, secret, registration token
</pre></div>
<ol>
<li>Client Class is manually pre-registered with a
BB+ Registry.
<ul>
<li>BB+ Registry collects any fixed app
<a href="#registration-parameters">registration
parameters</a> including, at a minimum,
<code>client_name</code> and
<code>client_uri</code>
</li>
<li>BB+ Registry verifies these parameters
(according to registry-specific policy)</li>
<li>BB+ Registry makes these parameters
discoverable via <a href="#discovery-apps">BB+
App Discovery</a>
</li>
<li>BB+ Registry supplies the Client Class with a
pre-registration token (signed JWT) for
subsequent dynamic registration operations</li>
</ul>
</li>
<li>Client Instance presents the pre-registration
token (using an Authorization header or any valid
mechanism from RFC6750) to the registration endpoint
of the service provider (which is discoverable via
the <a href="#discovery-providers">BB+ Provider
Discovery</a>.
</li>
<li>Service provider validates the pre-registration
token by checking the signature against the public
key of the BB+ Registry indicated by the
<code>iss</code> field of the token (and/or doing
token introspection from the <code>iss</code>).</li>
<li>Service provider does application discovery based
on the <code>iss</code> and <code>sub</code> fields
of the token to find the apps.json entry for this
application</li>
<li>Service provider compares any dynamically registered client
metadata fields to any fixed value fields discovered in apps.json
</li>
<li>Client Instance receives a <code>client_id</code>
and <code>client_secret</code> as well as a
<code>registration_access_token</code></li>
<li>Client Instance requests user authorization and
tokens</li>
<li>Client Instance accesses protected services at
service provider</li>
</ol>
<p>
<h3>Pre-registration</h3>
<p>First, the Client class is manually pre-registered
with a BB+ Registry. This process may fix any of the
client parameters listed above, such as the
<code>client_name</code> and
<code>redirect_uris</code>. At a minimum,
<code>client_name</code> and <code>client_uri</code>
must be fixed at pre-registration time. All classes of
a client will share any fixed parameters.</p>
<p>The pre-registered client class will receive:</p>
<ul>
<li>a "subject" identifier unique within the scope of
the BB+ Registry. This "subject" identifer
<strong>should</strong> be the same as the app's
homepage (<code>client_uri</code>).</li>
<li>a signed registration token with the following
properties:</li>
<li style="list-style: none; display: inline">
<ul>
<li><code>iss</code>: issuer is the URL of the
BB+ Registry</li>
<li><code>sub</code>: subject is an identifier
from the BB+ Registry (as described above)</li>
<li><code>iat</code>: timestamp of when this
pre-registration information was last updated
(and this token was issued)</li>
<li><code>exp</code>: OPTIONAL timestamp of when
this pre-registration token is no longer
valid</li>
<li><code>kid</code>: identifier for which key was
used to sign this token at the BB+ Registray</li>
<li><em>these claims are combined in a JWT
asymmetrically signed by the BB+ Registry.</em></li>
</ul>
</li>
</ul>
<h3>Registration</h3>
<p>The registration JWT from the previous step is
used by instances of the client during the initial call
to the registration endpoint for each service provider.
The service provider now needs to validate the registration
JWT, compare the client's pre-registered attributes to
the ones requested dynamically, and proceed with the registration.</p>
<p>For example, a client may send:</p>
<pre class="prettyprint">
POST /register HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: ey...{JWT token omitted for brevity}...q48d
Host: bbplus-provider.org
{
"client_name": "Blood Pressure Grapher",
"contacts": [
],
"tos_uri": "https://bpgrapher.org/tos",
"response_types": ["code"],
"grant_types": ["authorization_code"],
"token_endpoint_auth_method": "client_secret_basic",
"scope": "summary"
}
</pre>
<h4>Validating the JWT</h4>
<p>All service providers within a BB+ Registry must be
able to validate the signature and validity of any
registration tokens. First, the provdier must parse
the JWT and extract its <code>iss</code> (issuer) field
and determine if the issuer is trusted. This trust decision
will generally be a configuration option on the provider, which
will have a list of Registry Services that it trusts (identified
by their issuer URLs).</p>
<p>If the <code>iss</code> is from a trusted source, the provider
then does <a href="#discovery-registry">discovery against the registry</a>
and finds the <code>jwks_uri</code> of the registry. The provider
downloads the key set from this URL (using an HTTPS GET request)
and extracts the key with the <code>kid</code> that is named in the
JWT. Using that key, the provider can then validate the signature
of the JWT as described in JSON Web Signatures.</p>
<p class="alert alert-info">It's recommended that
BB+ Registries publish a <a href=
"http://tools.ietf.org/html/draft-richer-oauth-introspection">
token introspection endpoint</a> to facilitate token
validation by service providers. In addition to being able to check
the validity of the signature on a JWT, an introspection
endpoint can let a service provider determine if a JWT
is still valid (or has been revoked).
</p>
<h4>Validating the Registration</h4>
<p>The service provider does <a href="#discovery-apps">BB+
App Discovery</a> based on the <code>sub</code> (subject) and <code>iss</code> (issuer) in
the registration token to determine which client
metadata fields have been set ahead of time by the
pre-registration process. The provider
MUST abide by and enforce all pre-registered client values.
The Service provider will
compare these pre-registered fields with any
dynamically provided fields and determine the validity
of the registration. It is RECOMMENDED that providers
perform a direct string comparison between pre-registered
values and the values provided by the client. If there is a
mismatch in any field, the provider MUST either return
an <code>invalid_client_metadata</code> error (as described
in OAuth 2 Dynamic Registration) or replace the dynamically
requested value with the pre-registered value.
</p>
<h4>Completing the Registration</h4>
<p>Once the provider has determined that the client registration
request is valid, it will generate and issue a unique <code>client_id</code>
and <code>registration_access_token</code>, and if applicable, a unique <code>client_secret</code>.
The provider MUST NOT re-use the same <code>client_id</code>, <code>registration_access_token</code>,
or <code>client_secret</code> for different client instances, even
if these instances are part of the same client class.</p>
<p>The provider MAY link together different client instances that
are part of the same Client Class to facilitate logging, auditing,
and emergency deprovisioning of compromised applications. The
method for the provider doing this is out of scope of this
specification.</p>
<h3>Notes</h3>
<div class="well alert alert-info">
<strong>Notes:</strong>
<ul>
<li>The application owner/developer is responsible
for pre-registering with the BB+ Registry.</li>
<li>The service provider is responsible for
matching dynamic registration claims with the
pre-registered claims.</li>
<li>Client Instances present the token that comes
from the pre-registration process as part of a
normal dynamic registration with a particular
service provider.</li>
<li>This technique allows service providers to link
together multiple instances of a client based on
the tokens used during registration. Service
providers are responsible for linking thse client
instances together if they so desire. A service
provider MUST assign a unique <code>client_id</code>
for each registered instance and MUST NOT re-use
the same <code>client_id</code> for
other instances in the class.</li>
<li>Clients are responsible (in all registration
cases) for accepting and using the <code>client_id</code> issued
to them by each service provider when talking to
that service provider.</li>
<li>Even a web-server style client is going to need
to get different <code>client_id</code>'s from every service
provider, which means that even a single
installation of a client could have multiple
"instances" as far as the network is
concerned.</li>
</ul>
</div>
</section>
<section id="discovery">
<div class="page-header">
<h1>Provider and App Discovery <small>via BB+ Registries</small>
<span class=
"label label-success">Common</span></h1></div>
<p>BlueButton+ Pull uses <strong>BB+ Registry
Servers</strong> to enable discovery of BB+ Providers
and BB+ Apps. Each BB+ Registry Server exposes a set of
trusted providers and a set of trusted apps at
well-known <code>https</code> URLs, using simple
<a href="http://json-ld.org/">JSON-LD</a> arrays. In
the BB+ ecosystem, apps and providers must be
pre-configured with a BB+ Registry Server (or Servers).
All discovery endpoints are organized beneath
<code>.well-known/bb/</code> at the server's root.</p>
<h5>Why JSON-LD?</h5>
<div class="well alert-info">
<p><strong>JSON-LD</strong> provides a nice balance
between idiomatic JSON and well-structured data
representations. By combining a JSON payload with a
JSON-LD context, properties can be expanded to full
URIs so that data can be mixed and matched with other
services. For example, the BB+ Provider element below
can automatically be:</p>
<ul>
<li>
<a href="http://tinyurl.com/bpz5xsx" target=
"_blank">Expanded to full property URIs</a>
</li>
<li>
<a href="http://tinyurl.com/cp9vmum" target=
"_blank">Normalized in RDF</a>
</li>
</ul>
</div>
<h2 id="discovery-registry">BB+ Registry
Discovery</h2>
<p>A BB+ Registry Server exposes a BB+ Registry
discovery endpoint at:
<code>/.well-known/bb/registry.json</code></p>
<h3>registry.json</h3>
<p><code>registry.json</code> is a single
Registry element expressed as JSON-LD with a default
<code>@vocab</code> from <a href=
"http://schema.org">http://schema.org</a> and
additional properties defined in the <a href=
"context-json-ld.js">BB+ JSON-LD Context</a></p>
<p>While any vocabulary from schema.org may be used in
describing a BB+ Registry, the <strong>following fields
are required:</strong></p>
<table class="table table-striped">
<tr>
<th>Property</th>
<th>Description</th>
</tr>
<tr>
<td><code>name</code></td>
<td>Human-readable Name of the BB+ Registry</td>
</tr>
<tr>
<td><code>url</code></td>
<td>Root URL of the BB+ Registry (to which <code>.well-known/bb/registry.json</code> can be appended)</td>
</tr>
<tr>
<td><code>jwks_uri</code></td>
<td>URL of the JSON Web Key (JWK) set for this BB+ Registry. This URL MUST be protected by HTTPS or equivalent.</td>
</tr>
<tr>
<td><code>trust_bundle_uri</code></td>
<td>URL of the BB+ Push Trust Bundle (<code>.p7b</code>, <code>.p7c</code>, or <code>.p7m</code> file).
Only used for BB+ Registries that also act as BB+ Push Trust Bundles.
</td>
</tr>
<tr>
<td><code>oauth2</code></td>
<td>Collection of OAuth2 endpoints</td>
</tr>
<tr>
<td class="subproperty">