-
Notifications
You must be signed in to change notification settings - Fork 3
/
index-annost.html
2176 lines (1670 loc) · 97.8 KB
/
index-annost.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 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="robots" content="index,follow" />
<meta name="creator" content="rfchandler version 0.2" />
<meta name="citation_author" content="P. Jones"/>
<meta name="citation_author" content="G. Salgueiro"/>
<meta name="citation_author" content="M. Jones"/>
<meta name="citation_author" content="J. Smarr"/>
<meta name="citation_publication_date" content="September, 2013"/>
<meta name="citation_title" content="WebFinger"/>
<meta name="citation_doi" content="10.17487/RFC7033"/>
<meta name="citation_issn" content="2070-1721"/>
<meta name="citation_technical_report_number" content="rfc7033"/>
<meta name="citation_pdf_url" content="https://www.rfc-editor.org/rfc/pdfrfc/rfc7033.txt.pdf"/>
<title>RFC 7033: WebFinger</title>
<style type="text/css">
@media only screen
and (min-width: 992px)
and (max-width: 1199px) {
body { font-size: 14pt; }
div.content { width: 96ex; margin: 0 auto; }
}
@media only screen
and (min-width: 768px)
and (max-width: 991px) {
body { font-size: 14pt; }
div.content { width: 96ex; margin: 0 auto; }
}
@media only screen
and (min-width: 480px)
and (max-width: 767px) {
body { font-size: 11pt; }
div.content { width: 96ex; margin: 0 auto; }
}
@media only screen
and (max-width: 479px) {
body { font-size: 8pt; }
div.content { width: 96ex; margin: 0 auto; }
}
@media only screen
and (min-device-width : 375px)
and (max-device-width : 667px) {
body { font-size: 9.5pt; }
div.content { width: 96ex; margin: 0; }
}
@media only screen
and (min-device-width: 1200px) {
body { font-size: 10pt; margin: 0 4em; }
div.content { width: 96ex; margin: 0; }
}
h1, h2, h3, h4, h5, h6, .h1, .h2, .h3, .h4, .h5, .h6 {
font-weight: bold;
/* line-height: 0pt; */
display: inline;
white-space: pre;
font-family: monospace;
font-size: 1em;
font-weight: bold;
}
pre {
font-size: 1em;
margin-top: 0px;
margin-bottom: 0px;
}
.pre {
white-space: pre;
font-family: monospace;
}
.header{
font-weight: bold;
}
.newpage {
page-break-before: always;
}
.invisible {
text-decoration: none;
color: white;
}
a.selflink {
color: black;
text-decoration: none;
}
@media print {
body {
font-family: monospace;
font-size: 10.5pt;
}
h1, h2, h3, h4, h5, h6 {
font-size: 1em;
}
a:link, a:visited {
color: inherit;
text-decoration: none;
}
.noprint {
display: none;
}
}
@media screen {
.grey, .grey a:link, .grey a:visited {
color: #777;
}
.docinfo {
background-color: #EEE;
}
.top {
border-top: 7px solid #EEE;
}
.bgwhite { background-color: white; }
.bgred { background-color: #F44; }
.bggrey { background-color: #666; }
.bgbrown { background-color: #840; }
.bgorange { background-color: #FA0; }
.bgyellow { background-color: #EE0; }
.bgmagenta{ background-color: #F4F; }
.bgblue { background-color: #66F; }
.bgcyan { background-color: #4DD; }
.bggreen { background-color: #4F4; }
.legend { font-size: 90%; }
.cplate { font-size: 70%; border: solid grey 1px; }
}
</style>
<!--[if IE]>
<style>
body {
font-size: 13px;
margin: 10px 10px;
}
</style>
<![endif]--> <script type="text/javascript"><!--
function addHeaderTags() {
var spans = document.getElementsByTagName("span");
for (var i=0; i < spans.length; i++) {
var elem = spans[i];
if (elem) {
var level = elem.getAttribute("class");
if (level == "h1" || level == "h2" || level == "h3" || level == "h4" || level == "h5" || level == "h6") {
elem.innerHTML = "<"+level+">"+elem.innerHTML+"</"+level+">";
}
}
}
}
var legend_html = "Colour legend:<br /> <table> <tr><td>Unknown:</td> <td><span class='cplate bgwhite'> </span></td></tr> <tr><td>Draft:</td> <td><span class='cplate bgred'> </span></td></tr> <tr><td>Informational:</td> <td><span class='cplate bgorange'> </span></td></tr> <tr><td>Experimental:</td> <td><span class='cplate bgyellow'> </span></td></tr> <tr><td>Best Common Practice:</td> <td><span class='cplate bgmagenta'> </span></td></tr> <tr><td>Proposed Standard:</td> <td><span class='cplate bgblue'> </span></td></tr> <tr><td>Draft Standard (old designation):</td> <td><span class='cplate bgcyan'> </span></td></tr> <tr><td>Internet Standard:</td> <td><span class='cplate bggreen'> </span></td></tr> <tr><td>Historic:</td> <td><span class='cplate bggrey'> </span></td></tr> <tr><td>Obsolete:</td> <td><span class='cplate bgbrown'> </span></td></tr> </table>";
function showElem(id) {
var elem = document.getElementById(id);
elem.innerHTML = eval(id+"_html");
elem.style.visibility='visible';
}
function hideElem(id) {
var elem = document.getElementById(id);
elem.style.visibility='hidden';
elem.innerHTML = "";
}
// -->
</script>
<script src="annost.js">
</script></head>
<body>
<annost-note>
<h1 id='annost-title' style='display: block; text-align: left; color: #c04040; padding: 20px; border: 1px solid #c04040; font-family: Arial'>
Annotated by AnnoST. Experimental :-)
</h1>
<p>The AnnoST annotations use the following roles (see also sections on Conformance, and on Specification Profiles below):</p>
<dl>
<dt>Client</dt>
<dd>The client role in a WebFinger interaction</dd>
<dt>Server</dt>
<dd>The server role in a WebFinger interaction</dd>
</dl>
</annost-note>
<span class="pre noprint docinfo">[<a href="https://www.rfc-editor.org" title="RFC Editor">RFC Home</a>] [<a href="/rfc/rfc7033.txt">TEXT</a>|<a href="/rfc/pdfrfc/rfc7033.txt.pdf">PDF</a>|<a href="/rfc/rfc7033.html">HTML</a>] [<a href='https://datatracker.ietf.org/doc/rfc7033' title='IETF Datatracker information for this document'>Tracker</a>] [<a href="https://datatracker.ietf.org/ipr/search/?rfc=7033&submit=rfc" title="IPR disclosures related to this document">IPR</a>] [<a href='https://www.rfc-editor.org/info/rfc7033' title='Info page'>Info page</a>] </span><br/><span class="pre noprint docinfo"> </span><br /><span class="pre noprint docinfo"> PROPOSED STANDARD</span><br /><span class="pre noprint docinfo"> </span><pre>Internet Engineering Task Force (IETF) P. Jones
Request for Comments: 7033 G. Salgueiro
Category: Standards Track Cisco Systems
ISSN: 2070-1721 M. Jones
Microsoft
J. Smarr
Google
September 2013
<span class="h1">WebFinger</span>
Abstract
This specification defines the WebFinger protocol, which can be used
to discover information about people or other entities on the
Internet using standard HTTP methods. WebFinger discovers
information for a URI that might not be usable as a locator
otherwise, such as account or email URIs.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in <a href="./rfc5741#section-2">Section 2 of RFC 5741</a>.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
<a href="https://www.rfc-editor.org/info/rfc7033">http://www.rfc-editor.org/info/rfc7033</a>.
Copyright Notice
Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to <a href="https://www.rfc-editor.org/bcp/bcp78">BCP 78</a> and the IETF Trust's Legal
Provisions Relating to IETF Documents
(<a href="http://trustee.ietf.org/license-info">http://trustee.ietf.org/license-info</a>) 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.
<span class="grey">Jones, et al. Standards Track [Page 1]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-2" ></span>
<span class="grey"><a href="./rfc7033">RFC 7033</a> WebFinger September 2013</span>
Table of Contents
<a href="#section-1">1</a>. Introduction ....................................................<a href="#page-3">3</a>
<a href="#section-2">2</a>. Terminology .....................................................<a href="#page-3">3</a>
<a href="#section-3">3</a>. Example Uses of WebFinger .......................................<a href="#page-4">4</a>
<a href="#section-3.1">3.1</a>. Identity Provider Discovery for OpenID Connect .............<a href="#page-4">4</a>
<a href="#section-3.2">3.2</a>. Getting Author and Copyright Information for a Web Page ....<a href="#page-5">5</a>
<a href="#section-4">4</a>. WebFinger Protocol ..............................................<a href="#page-7">7</a>
<a href="#section-4.1">4.1</a>. Constructing the Query Component of the Request URI.......<a href="#page-7">7</a>
<a href="#section-4.2">4.2</a>. Performing a WebFinger Query..............................<a href="#page-8">8</a>
<a href="#section-4.3">4.3</a>. The "rel" Parameter.......................................<a href="#page-9">9</a>
<a href="#section-4.4">4.4</a>. The JSON Resource Descriptor (JRD).......................<a href="#page-11">11</a>
<a href="#section-4.4.1">4.4.1</a>. subject.............................................<a href="#page-11">11</a>
<a href="#section-4.4.2">4.4.2</a>. aliases.............................................<a href="#page-11">11</a>
<a href="#section-4.4.3">4.4.3</a>. properties..........................................<a href="#page-12">12</a>
<a href="#section-4.4.4">4.4.4</a>. links...............................................<a href="#page-12">12</a>
<a href="#section-4.5">4.5</a>. WebFinger and URIs.......................................<a href="#page-14">14</a>
<a href="#section-5">5</a>. Cross-Origin Resource Sharing (CORS) ...........................<a href="#page-14">14</a>
<a href="#section-6">6</a>. Access Control .................................................<a href="#page-15">15</a>
<a href="#section-7">7</a>. Hosted WebFinger Services ......................................<a href="#page-15">15</a>
<a href="#section-8">8</a>. Definition of WebFinger Applications ...........................<a href="#page-16">16</a>
<a href="#section-8.1">8.1</a>. Specification of the URI Scheme and URI ...................<a href="#page-17">17</a>
<a href="#section-8.2">8.2</a>. Host Resolution ...........................................<a href="#page-17">17</a>
<a href="#section-8.3">8.3</a>. Specification of Properties ...............................<a href="#page-17">17</a>
<a href="#section-8.4">8.4</a>. Specification of Links ....................................<a href="#page-18">18</a>
<a href="#section-8.5">8.5</a>. One URI, Multiple Applications ............................<a href="#page-18">18</a>
<a href="#section-8.6">8.6</a>. Registration of Link Relation Types and Properties ........<a href="#page-19">19</a>
<a href="#section-9">9</a>. Security Considerations ........................................<a href="#page-19">19</a>
<a href="#section-9.1">9.1</a>. Transport-Related Issues ..................................<a href="#page-19">19</a>
<a href="#section-9.2">9.2</a>. User Privacy Considerations ...............................<a href="#page-19">19</a>
<a href="#section-9.3">9.3</a>. Abuse Potential ...........................................<a href="#page-21">21</a>
<a href="#section-9.4">9.4</a>. Information Reliability ...................................<a href="#page-21">21</a>
<a href="#section-10">10</a>. IANA Considerations ...........................................<a href="#page-22">22</a>
<a href="#section-10.1">10.1</a>. Well-Known URI ...........................................<a href="#page-22">22</a>
<a href="#section-10.2">10.2</a>. JSON Resource Descriptor (JRD) Media Type ................<a href="#page-22">22</a>
<a href="#section-10.3">10.3</a>. Registering Link Relation Types ..........................<a href="#page-24">24</a>
<a href="#section-10.4">10.4</a>. Establishment of the "WebFinger Properties" Registry .....<a href="#page-24">24</a>
<a href="#section-10.4.1">10.4.1</a>. The Registration Template .........................<a href="#page-24">24</a>
<a href="#section-10.4.2">10.4.2</a>. The Registration Procedures .......................<a href="#page-25">25</a>
<a href="#section-11">11</a>. Acknowledgments ...............................................<a href="#page-26">26</a>
<a href="#section-12">12</a>. References ....................................................<a href="#page-26">26</a>
<a href="#section-12.1">12.1</a>. Normative References .....................................<a href="#page-26">26</a>
<a href="#section-12.2">12.2</a>. Informative References ...................................<a href="#page-27">27</a>
<span class="grey">Jones, et al. Standards Track [Page 2]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-3" ></span>
<span class="grey"><a href="./rfc7033">RFC 7033</a> WebFinger September 2013</span>
<span class="h2"><a class="selflink" id="section-1" href="#section-1">1</a>. Introduction</span>
WebFinger is used to discover information about people or other
entities on the Internet that are identified by a URI [<a href="#ref-6" title=""Uniform Resource Identifier (URI): Generic Syntax"">6</a>] using
standard Hypertext Transfer Protocol (HTTP) [<a href="#ref-2" title=""Hypertext Transfer Protocol -- HTTP/1.1"">2</a>] methods over a secure
transport [<a href="#ref-12" title=""HTTP Over TLS"">12</a>]. A WebFinger resource returns a JavaScript Object
Notation (JSON) [<a href="#ref-5" title=""The application/json Media Type for JavaScript Object Notation (JSON)"">5</a>] object describing the entity that is queried.
The JSON object is referred to as the JSON Resource Descriptor (JRD).
For a person, the type of information that might be discoverable via
WebFinger includes a personal profile address, identity service,
telephone number, or preferred avatar. For other entities on the
Internet, a WebFinger resource might return JRDs containing link
relations [<a href="#ref-8" title=""Link Relations"">8</a>] that enable a client to discover, for example, that a
printer can print in color on A4 paper, the physical location of a
server, or other static information.
Information returned via WebFinger might be for direct human
consumption (e.g., looking up someone's phone number), or it might be
used by systems to help carry out some operation (e.g., facilitating,
with additional security mechanisms, logging into a web site by
determining a user's identity service). The information is intended
to be static in nature, and, as such, WebFinger is not intended to be
used to return dynamic information like the temperature of a CPU or
the current toner level in a laser printer.
The WebFinger protocol is designed to be used across many
applications. Applications that wish to utilize WebFinger will need
to specify properties, titles, and link relation types that are
appropriate for the application. Further, applications will need to
define the appropriate URI scheme to utilize for the query target.
Use of WebFinger is illustrated in the examples in <a href="#section-3">Section 3</a> and
described more formally in <a href="#section-4">Section 4</a>. <a href="#section-8">Section 8</a> describes how
applications of WebFinger may be defined.
<span class="h2"><a class="selflink" id="section-2" href="#section-2">2</a>. Terminology</span>
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">RFC 2119</a> [<a href="#ref-1" title=""Key words for use in RFCs to Indicate Requirement Levels"">1</a>].
WebFinger makes heavy use of "link relations". A link relation is an
attribute-value pair in which the attribute identifies the type of
relationship between the linked entity or resource and the
information specified in the value. In Web Linking [<a href="#ref-4" title=""Web Linking"">4</a>], the link
relation is represented using an HTTP entity-header of "Link", where
the "rel" attribute specifies the type of relationship and the "href"
<span class="grey">Jones, et al. Standards Track [Page 3]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-4" ></span>
<span class="grey"><a href="./rfc7033">RFC 7033</a> WebFinger September 2013</span>
attribute specifies the information that is linked to the entity or
resource. In WebFinger, the same concept is represented using a JSON
array of "links" objects, where each member named "rel" specifies the
type of relationship and each member named "href" specifies the
information that is linked to the entity or resource. Note that
WebFinger narrows the scope of a link relation beyond what is defined
for Web Linking by stipulating that the value of the "rel" member
needs to be either a single IANA-registered link relation type [<a href="#ref-8" title=""Link Relations"">8</a>] or
a URI [<a href="#ref-6" title=""Uniform Resource Identifier (URI): Generic Syntax"">6</a>].
</pre>
<annost-xref target="4.4.4.1/1">
Link relation types.
</annost-xref>
<pre>
The use of URIs throughout this document refers to URIs following the
syntax specified in <a href="./rfc3986#section-3">Section 3 of RFC 3986</a> [<a href="#ref-6" title=""Uniform Resource Identifier (URI): Generic Syntax"">6</a>]. Relative URIs, having
syntax following that of <a href="./rfc3986#section-4.2">Section 4.2 of RFC 3986</a>, are not used with
WebFinger.
</pre>
<annost-note>
All tests that process URIs MUST check that the URIs are absolute.
</annost-note>
<pre>
<span class="h2"><a class="selflink" id="section-3" href="#section-3">3</a>. Example Uses of WebFinger</span>
This section shows a few sample uses of WebFinger. Any application
of WebFinger would be specified outside of this document, as
described in <a href="#section-8">Section 8</a>. The examples in this section should be
simple enough to understand without having seen the formal
specifications of the applications.
</pre>
<annost-note>
No tests derived from this example section 3.
</annost-note>
<pre>
<span class="h3"><a class="selflink" id="section-3.1" href="#section-3.1">3.1</a>. Identity Provider Discovery for OpenID Connect</span>
Suppose Carol wishes to authenticate with a web site she visits using
OpenID Connect [<a href="#ref-15" title=""OpenID Connect Messages 1.0"">15</a>]. She would provide the web site with her OpenID
Connect identifier, say carol@example.com. The visited web site
would perform a WebFinger query looking for the OpenID Connect
provider. Since the site is interested in only one particular link
relation, the WebFinger resource might utilize the "rel" parameter as
described in <a href="#section-4.3">Section 4.3</a>:
GET /.well-known/webfinger?
resource=acct%3Acarol%40example.com&
rel=http%3A%2F%2Fopenid.net%2Fspecs%2Fconnect%2F1.0%2Fissuer
HTTP/1.1
Host: example.com
</pre>
<span class="grey">Jones, et al. Standards Track [Page 4]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-5" ></span>
<span class="grey"><a href="./rfc7033">RFC 7033</a> WebFinger September 2013</span>
The server might respond like this:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/jrd+json
{
"subject" : "acct:carol@example.com",
"links" :
[
{
"rel" : "<a href="http://openid.net/specs/connect/1.0/issuer">http://openid.net/specs/connect/1.0/issuer</a>",
"href" : "https://openid.example.com"
}
]
}
Since the "rel" parameter only serves to filter the link relations
returned by the resource, other name/value pairs in the response,
including any aliases or properties, would be returned. Also, since
support for the "rel" parameter is not guaranteed, the client must
not assume the "links" array will contain only the requested link
relation.
</pre>
<pre>
<span class="h3"><a class="selflink" id="section-3.2" href="#section-3.2">3.2</a>. Getting Author and Copyright Information for a Web Page</span>
Suppose an application is defined to retrieve metadata information
about a web page URL, such as author and copyright information. To
retrieve that information, the client can utilize WebFinger to issue
a query for the specific URL. Suppose the URL of interest is
http://blog.example.com/article/id/314. The client would issue a
query similar to the following:
GET /.well-known/webfinger?
resource=http%3A%2F%2Fblog.example.com%2Farticle%2Fid%2F314
HTTP/1.1
Host: blog.example.com
<span class="grey">Jones, et al. Standards Track [Page 5]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-6" ></span>
<span class="grey"><a href="./rfc7033">RFC 7033</a> WebFinger September 2013</span>
The server might then reply in this way:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/jrd+json
{
"subject" : "http://blog.example.com/article/id/314",
"aliases" :
[
"http://blog.example.com/cool_new_thing",
"http://blog.example.com/steve/article/7"
],
"properties" :
{
"http://blgx.example.net/ns/version" : "1.3",
"http://blgx.example.net/ns/ext" : null
},
"links" :
[
{
"rel" : "copyright",
"href" : "http://www.example.com/copyright"
},
{
"rel" : "author",
"href" : "http://blog.example.com/author/steve",
"titles" :
{
"en-us" : "The Magical World of Steve",
"fr" : "Le Monde Magique de Steve"
},
"properties" :
{
"http://example.com/role" : "editor"
}
}
]
}
In the above example, we see that the server returned a list of
aliases, properties, and links related to the subject URL. The links
contain references to information for each link relation type. For
the author link, the server provided a reference to the author's
blog, along with a title for the blog in two languages. The server
also returned a single property related to the author, indicating the
author's role as editor of the blog.
<span class="grey">Jones, et al. Standards Track [Page 6]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-7" ></span>
<span class="grey"><a href="./rfc7033">RFC 7033</a> WebFinger September 2013</span>
It is worth noting that, while the server returned just two links in
the "links" array in this example, a server might return any number
of links when queried.
<span class="h2"><a class="selflink" id="section-4" href="#section-4">4</a>. WebFinger Protocol</span>
The WebFinger protocol is used to request information about an entity
identified by a query target (a URI). The client can optionally
specify one or more link relation types for which it would like to
receive information.
</pre>
<annost-test testid="4/1" name="Server accepts all link rels in the query" role="Server" level="MUST">
A server must accept all link rels in the query, even if it does not understand them.
To test, send a variety of variations on the same query, and make sure the server never
emits an error.
</annost-test>
<pre>
A WebFinger request is an HTTPS request to a WebFinger resource. A
WebFinger resource is a well-known URI [<a href="#ref-3" title=""Defining Well-Known Uniform Resource Identifiers (URIs)"">3</a>] using the HTTPS scheme
constructed along with the required query target and optional link
relation types. WebFinger resources MUST NOT be served with any
other URI scheme (such as HTTP).
</pre>
<annost-test testid="4/2" name="Client only performs https requests" role="Client" level="MUST">
A client must only perform Webfinger requests over https.
</annost-test>
<annost-test testid="4/3" name="Server only returns JRD in response to https requests" role="Server" level="MUST">
A server must only respond with a JRD document when the request was
made over https. If it was not, the behavior is undefined other than not returning a JRD
document.
</annost-test>
<pre>
A WebFinger resource is always given a query target, which is another
URI that identifies the entity whose information is sought. GET
requests to a WebFinger resource convey the query target in the
"resource" parameter of the WebFinger URI's query string; see <a href="#section-4.1">Section</a>
<a href="#section-4.1">4.1</a> for details.
</pre>
<annost-xref target="4/2">
A client must always specify a resource as a parameter. The value must be a
valid URI that is validly %-encoded.
Already tested there.
</annost-xref>
<annost-xref target="4.2/3">
Server response to invalid resource URI
</annost-xref>
<pre>
The host to which a WebFinger query is issued is significant. If the
query target contains a "host" portion (<a href="./rfc3986#section-3.2.2">Section 3.2.2 of RFC 3986</a>),
then the host to which the WebFinger query is issued SHOULD be the
same as the "host" portion of the query target, unless the client
receives instructions through some out-of-band mechanism to send the
query to another host. If the query target does not contain a "host"
portion, then the client chooses a host to which it directs the query
using additional information it has.
The path component of a WebFinger URI MUST be the well-known path
"/.well-known/webfinger". A WebFinger URI MUST contain a query
component that encodes the query target and optional link relation
types as specified in <a href="#section-4.1">Section 4.1</a>.
</pre>
<annost-xref target="4/4">
Resource parameter.
</annost-xref>
<annost-xref target="4.2/3">
Server response to invalid resource URI
</annost-xref>
<pre>
The WebFinger resource returns a JSON Resource Descriptor (JRD) as
the resource representation to convey information about an entity on
the Internet. Also, the Cross-Origin Resource Sharing (CORS) [<a href="#ref-7" title=""Cross-Origin Resource Sharing"">7</a>]
specification is utilized to facilitate queries made via a web
browser.
</pre>
<annost-xref target="5/1">
Server must provide valid CORS header.
</annost-xref>
<pre>
<span class="h3"><a class="selflink" id="section-4.1" href="#section-4.1">4.1</a>. Constructing the Query Component of the Request URI</span>
A WebFinger URI MUST contain a query component (see <a href="./rfc3986#section-3.4">Section 3.4 of
RFC 3986</a>). The query component MUST contain a "resource" parameter
and MAY contain one or more "rel" parameters. The "resource"
<span class="grey">Jones, et al. Standards Track [Page 7]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-8" ></span>
<span class="grey"><a href="./rfc7033">RFC 7033</a> WebFinger September 2013</span>
parameter MUST contain the query target (URI), and the "rel"
parameters MUST contain encoded link relation types according to the
encoding described in this section.
</pre>
<annost-xref target="4/4">
Resource parameter.
</annost-xref>
<pre>
To construct the query component, the client performs the following
steps. First, each parameter value is percent-encoded, as per
<a href="./rfc3986#section-2.1">Section 2.1 of RFC 3986</a>. The encoding is done to conform to the
query production in <a href="#section-3.4">Section 3.4</a> of that specification, with the
addition that any instances of the "=" and "&" characters within the
parameter values are also percent-encoded. Next, the client
constructs a string to be placed in the query component by
concatenating the name of the first parameter together with an equal
sign ("=") and the percent-encoded parameter value. For any
subsequent parameters, the client appends an ampersand ("&") to the
string, the name of the next parameter, an equal sign, and the
parameter value. The client MUST NOT insert any spaces while
constructing the string. The order in which the client places each
attribute-value pair within the query component does not matter in
the interpretation of the query component.
</pre>
<annost-xref target="4/2">
Client encodes the URI correctly, following the algorithm specified.
Already tested there
</annost-xref>
<annost-test testid="4.1/2" name="Parameter ordering is not significant" role="Server" level="MUST">
Server produces the same response regardless of parameter ordering.
</annost-test>
<pre>
<span class="h3"><a class="selflink" id="section-4.2" href="#section-4.2">4.2</a>. Performing a WebFinger Query</span>
A WebFinger client issues a query using the GET method to the well-
known [<a href="#ref-3" title=""Defining Well-Known Uniform Resource Identifiers (URIs)"">3</a>] resource identified by the URI whose path component is
"/.well-known/webfinger" and whose query component MUST include the
"resource" parameter exactly once and set to the value of the URI for
which information is being sought.
</pre>
<annost-xref target="4/2">
The client issues the query to the right URI.
Tested there already.
</annost-xref>
<annost-test testid="4.2/2" name="Perform a normal query" role="Server" level="MUST">
</annost-test>
<annost-xref target="4/4">
Resource parameter (client)
</annost-xref>
<pre>
If the "resource" parameter is absent or malformed, the WebFinger
resource MUST indicate that the request is bad as per <a href="./rfc2616#section-10.4.1">Section 10.4.1
of RFC 2616</a> [<a href="#ref-2" title=""Hypertext Transfer Protocol -- HTTP/1.1"">2</a>].
</pre>
<annost-note>
In all tests that test absent or malformed resource parameters, test for HTTP status "<code>400 Bad Request</code>"
per Section 10.4.1 in RFC 2616.
</annost-note>
<annost-test testid="4.2/3" name="Do not accept requests with missing resource parameter" role="Server" level="MUST">
The server responds with "400 Bad Request" when the resource parameter is missing.
See section 4.2 Note on 400 Bad Request.
</annost-test>
<annost-test testid="4.2/4" name="Do not accept malformed resource parameters" role="Server" level="MUST">
The server responds with "400 Bad Request" when the resource parameter is malformed.
# See section 4.2 Note on 400 Bad Request.
</annost-test>
<pre>
If the "resource" parameter is a value for which the server has no
information, the server MUST indicate that it was unable to match the
request as per <a href="./rfc2616#section-10.4.5">Section 10.4.5 of RFC 2616</a>.
</pre>
<annost-note>
In all tests that valid resource parameters that have no account behind them, test for HTTP
status "<code>404 Not found</code>" per Section 10.4.5 in RFC 2616.
</annost-note>
<annost-test testid="4.2/5" name="404 for non-existing resources" role="Server" level="MUST">
The server responds with "404 Not Found" when the resource parameter identifies a
non-existent resource.
</annost-test>
<pre>
A client MUST query the WebFinger resource using HTTPS only.
</pre>
<annost-xref target="4/2">
The client must use HTTPS.
Already tested there.
</annost-xref>
<pre>
If the
client determines that the resource has an invalid certificate, the
resource returns a 4xx or 5xx status code, or if the HTTPS connection
cannot be established for any reason, then the client MUST accept
that the WebFinger query has failed and MUST NOT attempt to reissue
the WebFinger request using HTTP over a non-secure connection.
</pre>
<annost-test testid="4.2/7" name="Client must accept failure" role="Client" level="MUST">
The client must not use any result it may have obtained under the preceding
conditions.
</annost-test>
<annost-note>
FIXME: not sure how to test this. How do we know whether a client **uses** the result
of a query when it shouldn't?
</annost-note>
<pre>
A WebFinger resource MUST return a JRD as the representation for the
resource if the client requests no other supported format explicitly
via the HTTP "Accept" header. The client MAY include the "Accept"
header to indicate a desired representation; representations other
than JRD might be defined in future specifications. The WebFinger
<span class="grey">Jones, et al. Standards Track [Page 8]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-9" ></span>
<span class="grey"><a href="./rfc7033">RFC 7033</a> WebFinger September 2013</span>
resource MUST silently ignore any requested representations that it
does not understand or support.
</pre>
<annost-note>
Not sure we can create test 4.2/8: Server must provide JRD unless requested otherwise.
How would we do that?
We are not testing a client-provided format at all, not even the JRD format.
</annost-note>
<pre>
The media type used for the JSON
Resource Descriptor (JRD) is "application/jrd+json" (see <a href="#section-10.2">Section</a>
<a href="#section-10.2">10.2</a>).
</pre>
<annost-test testid="4.2/9" name="Server must return JRD content type" role="Server" level="MUST">
A server must return the <code>application/jrd+json</code> content type.
</annost-test>
<pre>
The properties, titles, and link relation types returned by the
server in a JRD might be varied and numerous. For example, the
server might return information about a person's blog, vCard [<a href="#ref-14" title=""vCard Format Specification"">14</a>],
avatar, OpenID Connect provider, RSS or ATOM feed, and so forth in a
reply. Likewise, if a server has no information to provide, it might
return a JRD with an empty "links" array or no "links" array.
</pre>
<annost-xref target="4/2">
The client must accept that the XRD document may not contain a links array.
Already tested there.
</annost-xref>
<annost-xref target="4/2">
The client must accept that the XRD document may contain an empty links array.
Already tested there.
</annost-xref>
<pre>
A WebFinger resource MAY redirect the client; if it does, the
redirection MUST only be to an "https" URI and the client MUST
perform certificate validation again when redirected.
</pre>
<annost-test testid="4.2/12" name="Client must follow redirects" role="Client" level="MUST">
The client must follow a redirect, if it leads to an HTTPS URI, and fail if it does not.
</annost-test>
<annost-test testid="4.2/13" name="Client must check certificates on the redirect target" role="Client" level="MUST">
If the client is redirected, it must check the certificate of the new URI and not accept
any obtained JRD if not valid.
</annost-test>
<annost-note>
Not sure what constitutes a valid certificate for the purposes of our tests. FIXME?
</annost-note>
<annost-test testid="4.2/14" name="Server must only redirect to https" role="Server" level="MUST">
The server must only redirect to https.
</annost-test>
<pre>
A WebFinger resource can include cache validators in a response to
enable conditional requests by the client and/or expiration times as
per <a href="./rfc2616#section-13">Section 13 of RFC 2616</a>.
<span class="h3"><a class="selflink" id="section-4.3" href="#section-4.3">4.3</a>. The "rel" Parameter</span>
When issuing a request to a WebFinger resource, the client MAY
utilize the "rel" parameter to request only a subset of the
information that would otherwise be returned without the "rel"
parameter. When the "rel" parameter is used and accepted, only the
link relation types that match the link relation type provided via
the "rel" parameter are included in the array of links returned in
the JRD. If there are no matching link relation types defined for
the resource, the "links" array in the JRD will be either absent or
empty. All other information present in a resource descriptor
remains present, even when "rel" is employed.
</pre>
<annost-test testid="4.3/1" name="Subset or all when query asks for specific rels" role="Server" level="MUST">
If a request includes one or more rels, the resulting set of links in the JRD must be a subset,
the same as in the response to a request that does not include any rel parameter.
All other parts of the JRD must be the same.
</annost-test>
<annost-xref target="4.2/10">
Non-existing links.
</annost-xref>
<annost-xref target="4.2/11">
Empty links.
</annost-xref>
<pre>
The "rel" parameter MAY be included multiple times in order to
request multiple link relation types.
</pre>
<annost-xref target="4/1">
A server must accept requests that have multiple rel parameters. Already tested there.
</annost-xref>
<pre>
The purpose of the "rel" parameter is to return a subset of "link
relation objects" (see <a href="#section-4.4.4">Section 4.4.4</a>) that would otherwise be
returned in the resource descriptor. Use of the parameter might
reduce processing requirements on either the client or server, and it
might also reduce the bandwidth required to convey the partial
resource descriptor, especially if there are numerous link relation
values to convey for a given "resource" value. Note that if a client
requests a particular link relation type for which the server has no
information, the server MAY return a JRD with an empty "links" array
or no "links" array.
</pre>
<annost-xref target="4.2/10">
Non-existing links.
</annost-xref>
<annost-xref target="4.2/11">
Empty links.
</annost-xref>
<pre>
<span class="grey">Jones, et al. Standards Track [Page 9]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-10" ></span>
<span class="grey"><a href="./rfc7033">RFC 7033</a> WebFinger September 2013</span>
WebFinger resources SHOULD support the "rel" parameter. If the
resource does not support the "rel" parameter, it MUST ignore the
parameter and process the request as if no "rel" parameter values
were present.
</pre>
<annost-xref target="4/1">
A server must accept requests with any rel parameters, even if it does not understand them.
Already tested there.
</annost-xref>
<pre>
The following example uses the "rel" parameter to request links for
two link relation types:
GET /.well-known/webfinger?
resource=acct%3Abob%40example.com&
rel=http%3A%2F%2Fwebfinger.example%2Frel%2Fprofile-page&
rel=http%3A%2F%2Fwebfinger.example%2Frel%2Fbusinesscard HTTP/1.1
Host: example.com
</pre>
<annost-xref target="4/1">
A server must accept the preceding query (adjusted with an identifier that the
server can resolve) as valid.
Already tested there.
</annost-xref>
<annost-xref target="4/1">
A server must return the same JRD, or the same JRD with a shorter links array if the rel parameters
are specified. The removed elements must correspond to the rels.
Already tested there.
</annost-xref>
<annost-note>
The spec talks about a "subset", which, as a set, is commonly interpreted to be unordered. However,
they allow that the ordering of links is meaningful (see 4.4.4). So I think they probably don't mean
subset, but sub-sequence.
</annost-note>
<pre>
In this example, the client requests the link relations of type
"http://webfinger.example/rel/profile-page" and
"http://webfinger.example/rel/businesscard". The server then
responds with a message like this:
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/jrd+json
{
"subject" : "acct:bob@example.com",
"aliases" :
[
"https://www.example.com/~bob/"
],
"properties" :
{
"http://example.com/ns/role" : "employee"
},
"links" :
[
{
"rel" : "http://webfinger.example/rel/profile-page",
"href" : "https://www.example.com/~bob/"
},
{
"rel" : "http://webfinger.example/rel/businesscard",
"href" : "https://www.example.com/~bob/bob.vcf"
}
]
}
</pre>
<annost-test testid="4.3/6" name="Client accepts example response" role="Client" level="MUST">
A client must accept the preceding example response as valid.
</annost-test>
<pre>
<span class="grey">Jones, et al. Standards Track [Page 10]</span></pre>
<hr class='noprint'/><!--NewPage--><pre class='newpage'><span id="page-11" ></span>
<span class="grey"><a href="./rfc7033">RFC 7033</a> WebFinger September 2013</span>
As you can see in the response, the resource representation contains
only the links of the types requested by the client and for which the
server had information, but the other parts of the JRD are still
present. Note also in the above example that the links returned in
the "links" array all use HTTPS, which is important if the data
indirectly obtained via WebFinger needs to be returned securely.
<span class="h3"><a class="selflink" id="section-4.4" href="#section-4.4">4.4</a>. The JSON Resource Descriptor (JRD)</span>
The JSON Resource Descriptor (JRD), originally introduced in <a href="./rfc6415">RFC 6415</a>
[<a href="#ref-16" title=""Web Host Metadata"">16</a>] and based on the Extensible Resource Descriptor (XRD) format
[<a href="#ref-17" title=""Extensible Resource Descriptor (XRD) Version 1.0"">17</a>], is a JSON object that comprises the following name/value pairs:
o subject
o aliases
o properties
o links
</pre>
<annost-note>
All content provided by a server with a successful status code must be valid JSON.
</annost-note>
<annost-test testid="4.4/1" name="Client rejects invalid JSON" role="Client" level="MUST">
A client must reject any received content that is not valid JSON.
</annost-test>
<pre>
The member "subject" is a name/value pair whose value is a string,
"aliases" is an array of strings, "properties" is an object
comprising name/value pairs whose values are strings, and "links" is
an array of objects that contain link relation information.