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
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
|
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This file is generated from xml source: DO NOT EDIT
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-->
<title>mod_webkdc - Apache HTTP Server Version 2.5</title>
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
<script src="../style/scripts/prettify.min.js" type="text/javascript">
</script>
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
<body>
<div id="page-header">
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
<p class="apache">Apache HTTP Server Version 2.5</p>
<img alt="" src="../images/feather.gif" /></div>
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
<div id="path">
<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">Modules</a></div>
<div id="page-content">
<div id="preamble"><h1>Apache Module mod_webkdc</h1>
<div class="toplang">
<p><span>Available Languages: </span><a href="../en/mod/mod_webkdc.html" title="English"> en </a></p>
</div>
<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>WebAuth WebKDC module</td></tr>
<tr><th><a href="module-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>webkdc_module</td></tr>
<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_webkdc.c</td></tr>
<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Apache 2.0 and higher</td></tr></table>
<h3>Summary</h3>
<p>
This module implements the central authentication server for the
WebAuth protocol, also known as the WebKDC.
</p>
<p>
The WebKDC authenticates the user based on information passed by the
WebLogin service (which should generally run on the same system) and
generates authentication tokens both for the user's cookie cache to
support single sign-on and to send to application servers to
authenticate the user. It is designed to store as little state as
possible, using the browser cookie cache as the repository for
(encrypted) authentication tokens and ticket caches.
</p>
<p>
Further details are provided in the
<a href="http://webauth.stanford.edu/">WebAuth documentation</a>.
</p>
</div>
<div id="quickview"><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#webkdcdebug">WebKdcDebug</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdcfastarmorcache">WebKdcFastArmorCache</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdcidentityacl">WebKdcIdentityAcl</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdckerberosfactors">WebKdcKerberosFactors</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdckeyring">WebKdcKeyring</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdckeyringautoupdate">WebKdcKeyringAutoUpdate</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdckeyringkeylifetime">WebKdcKeyringKeyLifetime</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdckeytab">WebKdcKeytab</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdclocalrealms">WebKdcLocalRealms</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdclogintimelimit">WebKdcLoginTimeLimit</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdcpermittedrealms">WebKdcPermittedRealms</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdcproxytokenlifetime">WebKdcProxyTokenLifetime</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdcservicetokenlifetime">WebKdcServiceTokenLifetime</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdctokenacl">WebKdcTokenAcl</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdctokenmaxttl">WebkdcTokenMaxTTL</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdcuserinfoignorefail">WebKdcUserInfoIgnoreFail</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdcuserinfoprincipal">WebKdcUserInfoPrincipal</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdcuserinfotimeout">WebKdcUserInfoTimeout</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#webkdcuserinfourl">WebKdcUserInfoURL</a></li>
</ul>
<h3>Topics</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#setup">Setting up the WebKDC</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#config">Minimal Config File</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#logging">WebKDC Logging</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#multiple">Setting up Multiple WebKDCs</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#license">Manual License</a></li>
</ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="setup" id="setup">Setting up the WebKDC</a></h2>
<p>
The minimal configuration for the WebKDC requires two things: a
keytab for the Kerberos principal used by the WebKDC to authenticate
requests from application servers, and the <code>token.acl</code>
file that specifies what tokens application servers are permitted to
request.
</p>
<p>
The keytab must be a Kerberos keytab for the principal referenced in
the <code class="directive">WebAuthWebKdcPrincipal</code> configuration
directive on the application servers. How to obtain a keytab will
depend on one's local Kerberos infrastructure; it may be via
<code>kadmin</code> or via some other local interface.
</p>
<p>
For information about the <code>token.acl</code> file, see the
<a href="#webkdctokenacl"><code class="directive">WebKdcTokenAcl</code></a>
documentation below.
</p>
<p>
Finally, the one piece of state that the WebKDC must maintain is its
local keyring, which holds the AES keys that it uses to encrypt and
decrypt tokens. This keyring can either be generated and updated
automatically (the default) or managed externally using
<code>wa_keyring</code>. See
<a href="#webkdckeyringautoupdate"><code class="directive">WebKdcKeyringAutoUpdate</code></a>
for more information.
</p>
<p>
The WebKDC must get a URL to itself on the host where it is running.
By convention, <code>/webkdc-service</code> is used. This URL must
be only accessible via SSL, for security reasons.
</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="config" id="config">Minimal Config File</a></h2>
<p>
The following example shows the minimum config file required to
configure and use <code class="module"><a href="../mod/mod_webkdc.html">mod_webkdc</a></code>.
</p>
<div class="example"><h3>Example</h3><pre>LoadModule webkdc_module modules/mod_webkdc.so
WebKdcServiceTokenLifetime 30d
WebKdcKeyring conf/webkdc/keyring
WebKdcKeytab conf/webkdc/keytab
WebKdcTokenAcl conf/webkdc/token.acl
<VirtualHost _default_:443>
<Location /webkdc-service>
SetHandler webkdc
</Location>
</VirtualHost></pre></div>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="logging" id="logging">WebKDC Logging</a></h2>
<p>
All commands received by the WebKDC and their results are logged to
the Apache error log with a log level of "notice". These log
messages always begin with the string "mod_webkdc: event="
followed by the event, which is one of the following:
</p>
<dl>
<dt>getTokens</dt>
<dd>
<p>
A request for a service, id, proxy, or cred token. You will see
this action most frequently from WebAuth web servers acquiring
new service tokens for use later when redirecting users to the
WebLogin server and decoding the response. When delegating user
credentials to WebAuth application servers, those servers will
send a <code>getTokens</code> request to the WebKDC to obtain
those delegated credentials.
</p>
</dd>
<dt>requestToken</dt>
<dd>
<p>
A request for an id or proxy token for a user. A proxy token
for the WebKDC itself will also be returned for use with future
requests by the same user. This call will normally only be done
by the WebLogin component of the WebKDC service; while the call
is available to any client, clients wishing to bootstrap WebAuth
cookies on their own should use the much simpler
webkdcProxyToken call instead.
</p>
</dd>
<dt>webkdcProxyToken</dt>
<dd>
<p>
A request for a WebKDC proxy token (the token contained in the
WebAuth single sign-on cookie) given a Kerberos authenticator.
This can be used by clients to bootstrap a WebAuth single
sign-on cookie without having to visit the WebLogin server in a
browser.
</p>
</dd>
<dt>webkdcProxyTokenInfo</dt>
<dd>
<p>
Given a WebKDC proxy token, returns various metadata about it,
such as its expiration time.
</p>
</dd>
</dl>
<p>
Those who are familiar with the WebAuth protocol will recognize that
the four events logged are the four XML elements that the WebKDC
protocol permits. (Other errors, such as unknown commands, are of
course also logged.)
</p>
<p>
Following the event will be additional key/value pairs in the form
key=value. Values containing whitespace or double quotes will be
enclosed in double quotes. Any double quotes in the value will be
doubled; in other words, the character " in the value will be
represented as "" inside a double-quoted string. The possible keys
are:
</p>
<dl>
<dt>authz</dt>
<dd>
<p>
Only for <code>requestToken</code> requests, this indicates that
the user is asserting an authorization identity to this WAS.
The value of this key will be the authorization identity that
was asserted. The authorization identity was validated against
the identity ACL file. See
<a href="#webkdcidentityacl"><code class="directive">WebKdcIdentityAcl</code></a>
for more information.
</p>
</dd>
<dt>clientIp</dt>
<dd>
<p>
Only for <code>requestToken</code> requests, this contains the
client IP address as indicated by the WebLogin server. If the
WebLogin server didn't include the client IP address in the
request, the value will be empty. Please note that the WebKDC
does not authenticate this information, only records whatever
was passed in by the WebLogin server, which means that if
<code>from</code> is not 127.0.0.1 (meaning that the
<code>requestToken</code> request didn't come from the WebLogin
server), the value of this key should not be trusted.
</p>
</dd>
<dt>errorCode</dt>
<dd>
<p>
The error code for a protocol-level error. The presence of this
key means that some failure occurred in the course of parsing
the XML document and therefore no action was taken in the
WebKDC.
</p>
</dd>
<dt>errorMessage</dt>
<dd>
<p>
The error message corresponding to the error code from a
<code>errorCode</code> key.
</p>
</dd>
<dt>from</dt>
<dd>
<p>
The IP address from which the request came. For
<code>requestToken</code> in the recommended configuration of
running WebLogin servers on the same host as the WebKDC, this
will normally always be 127.0.0.1, but will be more interesting
for the other events.
</p>
</dd>
<dt>ifactors</dt>
<dd>
<p>
The initial authentication factors of this successful
authentication.
</p>
</dd>
<dt>lec</dt>
<dd>
<p>
The login error code, only included for
<code>requestToken</code>. If this is 0, the call was
successful. Otherwise, it contains the error code.
</p>
</dd>
<dt>lem</dt>
<dd>
<p>
If <code>lec</code> is non-zero in <code>requestToken</code>,
this contains the error message corresponding to that error
code.
</p>
</dd>
<dt>loa</dt>
<dd>
<p>
The Level of Assurance of this successful authentication.
</p>
</dd>
<dt>login</dt>
<dd>
<p>
If this request represents an initial user login (as opposed to
an authentication using single sign-on credentials), this key is
present and the value will indicate the type of authentication
(password or otp, or both if both are provided at the same time.
</p>
</dd>
<dt>pt</dt>
<dd>
<p>
For tokens of type <code>proxy</code>, this will contain the
proxy token type. Currently, the only supported proxy token
type is <code>krb5</code>, which can be used by the WebAuth
Application Server to request Kerberos credentials on behalf of
the user from the WebKDC.
</p>
</dd>
<dt>ro</dt>
<dd>
<p>
Any request options set by the WebAuth server. The most common
value here is "fa", indicating that the WebAuth server requested
forced password authentication even if the user already had
single sign-on credentials. For more details on the possible
values, see the WebAuth protocol specification.
</p>
</dd>
<dt>rtt</dt>
<dd>
<p>
The returned token type from a <code>requestToken</code>
request. Normally this will be "id" for an id token, but may be
another token type depending on what the WebAuth server asked
for.
</p>
</dd>
<dt>sa</dt>
<dd>
<p>
The requested subject authenticator type for a
<code>requestToken</code> operation. If the WebAuth Application
Server requests an id token, this will indicate the type of id
token it is requesting. Possible values are
<code>webkdc</code>, which provides the user's identity but no
additional information, or <code>krb5</code>, which provides a
Kerberos authenticator for the user that can be verified by the
WebAuth Application Server's Kerberos key.
</p>
</dd>
<dt>server</dt>
<dd>
<p>
For <code>getTokens</code> and <code>requestToken</code>, this
will contain the identifier of the requesting server (in the
case of <code>requestToken</code>, this is the server that sent
the user to WebLogin).
</p>
</dd>
<dt>sfactors</dt>
<dd>
<p>
The session authentication factors of this successful
authentication.
</p>
</dd>
<dt>type</dt>
<dd>
<p>
The type of token acquired by a <code>getTokens</code> call.
</p>
</dd>
<dt>url</dt>
<dd>
<p>
For <code>requestToken</code>, this will contain the return URL
to which the browser will be sent after authentication.
</p>
</dd>
<dt>user</dt>
<dd>
<p>
The user being authenticated. This will normally be the
username portion of a Kerberos identity, if it is known, for
<code>requestToken</code>. For protocol-level errors, it often
will be unknown (because the protocol failed before the username
was established) and will instead be the string
"<unknown>". For <code>getTokens</code>, it will be the
user the tokens are for (the same as <code>server</code> in the
most common case of acquiring service tokens).
</p>
</dd>
<dt>wifactors</dt>
<dd>
<p>
The initial authentication factors required by the WebAuth
Application Server.
</p>
</dd>
<dt>wloa</dt>
<dd>
<p>
The Level of Assurance required by the WebAuth Application
Server.
</p>
</dd>
<dt>wsfactors</dt>
<dd>
<p>
The session authentication factors required by the WebAuth
Application Server.
</p>
</dd>
</dl>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="multiple" id="multiple">Setting up Multiple WebKDCs</a></h2>
<p>
WebAuth was designed so that it would be fairly easy to setup
multiple WebKDCs for load balancing and redundancy. There are three
pieces of information that need to be shared between WebKDC servers
in order to achieve this:
</p>
<ol>
<li>Token ACL file</li>
<li>Kerberos keytab file</li>
<li>WebKDC keyring file</li>
</ol>
<div class="note">
<h3>Note</h3>
<p>
All the files should be securely transferred from the master to
the slave or slaves using a program like <code>scp</code> that
encrypts the file contents during the transfer.
</p>
</div>
<p>
By convention, one of the WebKDC's should be designated as the
"master" and other WebKDC's should be designated as "slaves." These
files should only be updated on the master and pushed manually or
automatically to the slaves.
</p>
<p>
The token ACL file is specified using the
<a href="#webkdctokenacl"><code class="directive">WebKdcTokenAcl</code></a>
directive. This file should be maintained on the "master" WebKDC,
and copied to other WebKDCs.
</p>
<p>
The Kerberos keytab file is specified using the
<a href="$kwebkdckeytab"><code class="directive">WebKdcKeytab</code></a>
directive. This is a standard Kerberos keytab file containing the
principal used by WebAuth servers to initially communicate with the
WebKDC. This is a binary file that should be kept consistent across
all the WebKDC servers. Normally this means that you will need to
download it once and then copy it between systems, since Kerberos
generally changes the key of a principal when downloading a new
keytab for it.
</p>
<p>
The WebKDC keyring file is specified using the
<a href="#webkdckeyring"><code class="directive">WebKdcKeyring</code></a>
directive. This file contains the WebKDCs private AES keys. If you
are running multiple WebKDCs, you must turn off automatic updating
of the WebKDCs keyring file on restarts. This is done using the
<a href="#webkdckeyringautoupdate"><code class="directive">WebKdcKeyringAutoUpdate</code></a>
directive:
</p>
<div class="example"><h3>Turning off auto update</h3><p><code>
WebKdcKeyringAutoUpdate off
</code></p></div>
<p>
Once auto update is turned off, the keyring file will not be
automatically updated, and can be manually updated and then copied
between the servers. The keys in the keyring file still need to be
changed periodically using the <code>wa_keyring</code> command.
This command would be run on the keyring file on the master, and
then the new keyring should be copied to the slaves. For example,
to generate a new post-dated key in the file called "keyring" you
should do the following:
</p>
<div class="example"><h3>Generating a post-dated key</h3><p><code>
wa_keyring -f ./keyring add 2d
</code></p></div>
<p>
That example generates a new key that will be valid in seven days.
Any existing keys in the keyring file are left as-is so outstanding
tokens continue to work. The new keyring file can then safely be
distributed to the slave WebKDCs. Then, the WebKDC must be
restarted to pick up the new key.
</p>
<p>
Old keys in the keyring file should also periodically be removed.
This should be done using <code>wa_keyring</code> and the
<code>gc</code> command:
</p>
<div class="example"><h3>Automatically removing old keys</h3><p><code>
wa_keyring -f ./keyring gc -60d
</code></p></div>
<p>
This command would remove any key older than 90 days. The time
interval that you pass to the <code>gc</code> command must be older
than the service token lifetime as specified with
<a href="#webkdcservicetokenlifetime"><code class="directive">WebKdcServiceTokenLifetime</code></a>.
The recommendation is to make it about twice as long.
</p>
<p>
To summarize, for each WebKDC (master and slaves), you'd want the
following directives:
</p>
<div class="example"><h3>Example</h3><pre>LoadModule webkdc_module modules/mod_webkdc.so
WebKdcServiceTokenLifetime 30d
WebKdcKeyring conf/webkdc/keyring
WebKdcKeytab conf/webkdc/keytab
WebKdcTokenAcl conf/webkdc/token.acl
WebKdcKeyringAutoUpdate off
<VirtualHost _default_:443>
<Location /webkdc-service>
SetHandler webkdc
</Location>
</VirtualHost></pre></div>
<p>
Periodically (once a month should be reasonable, but there's no
drawback to doing it daily so that you'll more quickly notice
problems in the process), you'd want to generate a new key, remove
old keys, and then update the keyring file on the slaves using a
script like this:
</p>
<div class="example"><h3>Monthly Key maintenance</h3><pre>wa_keyring -f conf/webkdc/keyring add 2d
wa_keyring -f conf/webkdc/keyring gc -60d
apache2ctl graceful
for host in slave1 slave2 ; do
scp conf/webkdc/keyring $host:/path/to/conf/webkdc/keyring
ssh $host apache2ctl graceful
done</pre></div>
<p>
If the servers are restarted regularly (such as for nightly log
rotation), you can omit the <code>apache2ctl graceful</code> restart
and just let that restart pick up the new keys. The reason for
post-dating the key is to make sure that all of the servers pick it
up before it becomes valid and is used in service tokens.
</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="license" id="license">Manual License</a></h2>
<p>
Copyright 2002, 2003, 2005, 2006, 2008, 2009, 2011, 2012, 2014 The
Board of Trustees of the Leland Stanford Junior University
</p>
<p>
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved. This file is offered as-is,
without any warranty.
</p>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcDebug" id="WebKdcDebug">WebKdcDebug</a> <a name="webkdcdebug" id="webkdcdebug">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Turn on extra debugging in the Apache error log</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcDebug on|off</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>WebKdcDebug off</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
Whether or not to log additional debugging messages to the Apache
server log.
</p>
<div class="example"><h3>Example</h3><p><code>
WebKdcDebug on
</code></p></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcFastArmorCache" id="WebKdcFastArmorCache">WebKdcFastArmorCache</a> <a name="webkdcfastarmorcache" id="webkdcfastarmorcache">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Path to crednetial cache for FAST armor tickets</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcFastArmorCache <em>path</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>(none)</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
FAST (Flexible Authentication Secure Tunneling) is a way of
protecting the initial Kerberos AS-REQ exchange for a password
authentication with armor based on stronger keys, such as
randomly-generated keys in a keytab. This directive specifies a
Kerberos ticket cache to use with FAST to protect any password
authentications done by the KDC.
</p>
<p>
The <em>path</em> argument must point to an existing Kerberos
ticket cache, not a keytab or other source of Kerberos keys. To
maintain a Kerberos ticket cache from a keytab, use a program such
as <a href="http://www.eyrie.org/~eagle/software/kstart/">k5start</a>.
The <em>path</em> argument can be a path to a ticket cache on
disk, or any other Kerberos ticket cache specification that can be
read by the Apache server.
</p>
<p>
If this directive is set, FAST will be used and required for all
password authentications, and if FAST setup fails, the
authentication will fail. If this directive is set and the
Kerberos KDC does not support FAST, all password authentications
will fail.
</p>
<div class="example"><h3>Example</h3><p><code>
WebKdcFastArmorCache /var/run/webkdc/krb5cc_armor
</code></p></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcIdentityAcl" id="WebKdcIdentityAcl">WebKdcIdentityAcl</a> <a name="webkdcidentityacl" id="webkdcidentityacl">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>
Path to the ACL file for authorization identities
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcIdentityAcl <em>path</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>(none)</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
This directive, if set, points to an ACL file that controls
whether a user can assert an authorization identity to a
particular WebAuth Application Server that is different than their
authenticated identity. By default, it is not set, which disables
all authorization identity support in the WebKDC.
</p>
<p>
An authorization identity is an alternate identity, different than
the identity as which the user authenticated, that should be used
for identification and access control in the WebAuth Application
Server. When an authorization identity is provided, both it and
the authentication identity are passed to the WAS, and the WAS can
choose which to honor. By default, even if this directive is
enabled on the WebKDC and the user asserts an authorization
identity, that identity is ignored by the WAS. Support for
authorization identities must also be explicitly enabled on the
WAS.
</p>
<p>
Each line in the identity ACL file is a space-separated grant of
permission for a particular user to assert a particular
authorization identity to a particular site. Each line has three
fields:
</p>
<ol>
<li>
<p>
The authenticated identity of the user to which this
permission is granted. This is the identity after any
normalization or realm stripping and should match the identity
that would be passed to the WebAuth Application Server, put in
REMOTE_USER, and so forth.
</p>
</li>
<li>
<p>
The identity of the WAS to which that user can assert an
authorization identity. This is an identity, not a URL, and
is the same value that is matched against the token ACL file
(see <a href="#webkdctokenacl"><code class="directive">WebKdcTokenAcl</code></a>).
At present, just as with the token ACL file, it is always a
Kerberos principal preceded by <code>krb5:</code>.
</p>
</li>
<li>
<p>
The authorization identity that the user is permitted to
assert. This must be exactly the value that will be passed to
the WebAuth Application Server.
</p>
</li>
</ol>
<p>
No wildcards are supported. Multiple lines for the same user and
same WAS are allowed, representing multiple different
authorization identities that user is allowed to assert to that
WAS. Blank lines and lines beginning with <code>#</code> are
ignored.
</p>
<div class="example"><h3>Example ACL File</h3><pre># Allow alice to assert an identity of bob to foo.example.org.
alice krb5:webauth/foo.example.org@EXAMPLE.ORG bob
# Allow alice to assert a cross-realm identity to foo.example.org.
alice krb5:webauth/foo.example.org@EXAMPLE.ORG alice@EXAMPLE.COM
# Allow joe to assert an identity of testuser on foo-test.example.org.
joe krb5:webauth/foo-test.example.org@EXAMPLE.ORG testuser</pre></div>
<p>
If the path is not absolute, it will be considered relative to
<code class="directive">ServerRoot</code>.
</p>
<div class="example"><h3>Example</h3><p><code>
WebKdcIdentityAcl conf/webkdc/id.acl
</code></p></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcKerberosFactors" id="WebKdcKerberosFactors">WebKdcKerberosFactors</a> <a name="webkdckerberosfactors" id="webkdckerberosfactors">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>
Initial factor information for directly-obtained webkdc-proxy tokens
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcKerberosFactors <em>factor</em> ...</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>WebKdcKerberosFactors u</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
This directive sets the initial factor information for the
webkdc-proxy tokens obtained by clients by direct Kerberos
authentication (rather than by WebLogin). If left unset, the
default factor will be set to 'unknown'.
</p>
<div class="example"><h3>Example</h3><p><code>
WebKdcKerberosFactors p
</code></p></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcKeyring" id="WebKdcKeyring">WebKdcKeyring</a> <a name="webkdckeyring" id="webkdckeyring">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>
Name of the file containing the WebKDC's keyring
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcKeyring <em>path</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>(none)</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
This is the name of the file containing the WebKDC's keyring,
which stores the server's private AES keys. It must be readable
by the Apache user.
</p>
<p>
The keyring file is read when the first request for a virtual host
is received. Each child maintains an in-memory cached keyring for
each virtual host. These keyrings are only reloaded from disk
when Apache refreshes its configuration. If the keyring is
changed by an external process (<code>wa_keyring</code>, for
instance), Apache must be told to reload configuration files in
order to pick up the change.
</p>
<p>
When using the ITK Apache MPM, there should be a separate keyring
for each unique virtual host user that will be serving as a
WebKDC. This maintains proper privilege separation by assigning
each user a separate keyring.
</p>
<p>
If the path is not absolute, it will considered relative to
<code class="directive">ServerRoot</code>.
</p>
<div class="note">
<h3>Note</h3>
<p>This directive must be set.</p>
</div>
<div class="example"><h3>Example</h3><p><code>
WebKdcKeyring conf/webkdc/keyring
</code></p></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcKeyringAutoUpdate" id="WebKdcKeyringAutoUpdate">WebKdcKeyringAutoUpdate</a> <a name="webkdckeyringautoupdate" id="webkdckeyringautoupdate">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Whether or not to auto-update the keyring file</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcKeyringAutoUpdate on|off</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>WebKdcKeyringAutoUpdate on</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
This directive controls whether or not we auto-update the keyring
file. This includes creating it if it doesn't exist, generating a
new key before the old key expires, and periodically
garbage-collecting old keys. Updating only occurs on server
startup and restarts.
</p>
<p>
If auto-update is enabled, Apache must have write access to the
directory containing the keyring, since keyrings are updated by
writing out the new file to a separate name and then atomically
replacing the file.
</p>
<p>
Ownership (user and group) of the existing keyring file will be
preserved if possible without overwriting the existing file.
Permissions will also be preserved, with the exception that
permissions will not be copied to the new file if the old file was
group-readable or group-writable and setting the group ownership
failed.
</p>
<div class="note">
<h3>Note</h3>
<p>
This directive should be turned off if multiple servers are
sharing the same keyring file, so that the keyring file can be
manually updated. That too may eventually be automated.
</p>
</div>
<div class="example"><h3>Example</h3><p><code>
WebKdcKeyringAutoUpdate off
</code></p></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcKeyringKeyLifetime" id="WebKdcKeyringKeyLifetime">WebKdcKeyringKeyLifetime</a> <a name="webkdckeyringkeylifetime" id="webkdckeyringkeylifetime">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>
Lifetime of keys in the keyring if we auto-update
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcKeyringKeyLifetime <em>nnnn[s|m|h|d|w]</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>WebKdcKeyringKeyLifetime 30d</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
This directive controls how long keys we automatically create for
the keyring are valid. Keys will be valid from the time they are
created until the lifetime is reached. It is equivalent to the
time specified to <code>wa_keyring gc</code>, except that the
latter expects a negative time. Note that key lifetime is only
checked on server startup and restarts.
</p>
<p>
This directive is only consulted if
<a href="#webkdckeyringautoupdate"><code class="directive">WebKdcKeyringAutoUpdate</code></a>
is enabled.
</p>
<p>
The units for the time are specified by appending a single letter.
This letter may be one of <code>s</code>, <code>m</code>,
<code>h</code>, <code>d</code>, or <code>w</code>, which
correspond to seconds, minutes, hours, days, and weeks,
respectively.
</p>
<div class="example"><h3>Example</h3><p><code>
WebKdcKeyringKeyLifetime 60d
</code></p></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcKeytab" id="WebKdcKeytab">WebKdcKeytab</a> <a name="webkdckeytab" id="webkdckeytab">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Name of the Kerberos keytab file</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcKeytab <em>path</em> [<em>principal</em>]</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>(none)</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
This is the name of the Kerberos keytab file, used by the WebKDC
to authenticate initial requests from application servers. The
principal is optional and can be used to specify a particular
principal in a keytab file that contains several. If it is not
specified, then the first principal in the keytab file be used.
</p>
<p>
If the path is not absolute, it will considered relative to
<code class="directive">ServerRoot</code>.
</p>
<div class="note">
<h3>Note</h3>
<p>This directive must be set.</p>
</div>
<div class="example"><h3>Example</h3><p><code>
WebKdcKeytab conf/webkdc/keytab service/webkdc
</code></p></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcLocalRealms" id="WebKdcLocalRealms">WebKdcLocalRealms</a> <a name="webkdclocalrealms" id="webkdclocalrealms">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>
Realms to be stripped from authenticated identities
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcLocalRealms none|local|<em>realm</em> ...</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>WebKdcLocalRealms local</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
This directive controls stripping realm qualifications from the
authenticated identity of a WebAuth user. The realm is defined as
the portion of the authenticated identity following the first
unescaped <code>@</code> in the identity.
</p>
<p>
If set to <code>none</code>, no transformations are done and the
authenticated identity is always passed in its fully-qualified
form. This is probably the best option for sites that use
multiple local Kerberos realms where none is the logical default
realm.
</p>
<p>
If set to <code>local</code> (the default), the authenticated
identity will be passed to the krb5_aname_to_localname function on
the WebKDC. Normally, this will strip off the realm if it matches
the default Kerberos realm of the WebKDC (not the requesting
WebAuth Application Server) and otherwise leave it; however, more
complex canonicalization rules may be specified in the
<code>/etc/krb5.conf</code> file on the WebKDC.
</p>
<p>
Otherwise, the space-separated arguments to this directive are
taken to be realms that should be stripped from the authenticated
identity.
</p>
<div class="note">
<h3>Note</h3>
<p>
The canonicalization done is that specified on the WebKDC, not
in the WebAuth Application Server. There is no way to perform
different authenticated identity canonicalization on different
WebAuth Application Servers using the same WebKDC.
</p>
</div>
<div class="example"><h3>Example</h3><pre># Strip stanford.edu and WIN.STANFORD.EDU but leave other realms
WebKdcLocalRealms stanford.edu WIN.STANFORD.EDU</pre></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcLoginTimeLimit" id="WebKdcLoginTimeLimit">WebKdcLoginTimeLimit</a> <a name="webkdclogintimelimit" id="webkdclogintimelimit">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>
Time limit for completing login process and for considering a login
to be recent
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcLoginTimeLimit <em>nnnn[s|m|h|d|w]</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>WebKdcLoginTimeLimit 5m</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
This directive controls how long a user is permitted to take to
complete the login process, and, related, how long before a user's
login is not considered to have "just happened."
</p>
<p>
In some cases, particularly when multifactor authentication is in
use or the user is permitted to assert an authorization identity,
the interaction with WebLogin can involve multiple independent
steps. This directive sets a time limit within which each of
those actions is considered to be part of the same session. If
the user takes longer than this time limit to complete the login
process, their first actions will expire and they are likely to
have to begin again.
</p>
<p>
This is also the time limit within which the authentication
factors presented by the user will be considered session factors
as well as initial factors. This affects restrictions on session
factors set by the WebAuth Application Server (using <a href="http://webauth.stanford.edu/manual/mod/mod_webauth.html#webauthrequiresessionfactor"><code class="directive">WebAuthRequireSessionFactor</code></a>,
for example). If the user has authenticated within this time
limit, they will not be forced to reauthenticate, even when going
to a different WebAuth Application Server than the one that
prompted their original authentication.
</p>
<p>
The units for the time are specified by appending a single letter.
This letter may be one of <code>s</code>, <code>m</code>,
<code>h</code>, <code>d</code>, or <code>w</code>, which
correspond to seconds, minutes, hours, days, and weeks,
respectively.
</p>
<p>
This directive may be set to <code>0s</code> to disable this grace
period entirely. This will mean that any session factor
requirement in a required reauthentication, at the cost of making
multistage multifactor authentication impossible. It will also
prevent asserting an authorization identity while satisfying a
session factor requirement impossible unless the user is prompted
for an authorization identity at the time of login.
</p>
<div class="example"><h3>Examples</h3><pre># The user must complete the login process in 90 seconds
WebKdcLoginTimeLimit 90s
# Disable the grace period entirely.
WebKdcLoginTimeLimit 0s</pre></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcPermittedRealms" id="WebKdcPermittedRealms">WebKdcPermittedRealms</a> <a name="webkdcpermittedrealms" id="webkdcpermittedrealms">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>List of permitted authentication realms</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcPermittedRealms <em>realm</em> ...</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>(none)</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
By default, the WebKDC allows authentication via any realm with
which there is cross-realm trust. If this directive is given, it
restricts authentication to principals in one of the realms listed
in this directive.
</p>
<div class="example"><h3>Example</h3><p><code>
WebKdcPermittedRealms stanford.edu WIN.STANFORD.EDU
</code></p></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcProxyTokenLifetime" id="WebKdcProxyTokenLifetime">WebKdcProxyTokenLifetime</a> <a name="webkdcproxytokenlifetime" id="webkdcproxytokenlifetime">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Lifetime of webkdc-proxy tokens we create</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcProxyTokenLifetime <em>nnnn[s|m|h|d|w]</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>(lifetime of underlying proxied-credential)</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
This directive controls the lifetime of the webkdc-proxy token
(the main single-sign-on cookie containing the user's proxied
credentials). If not specified, the lifetime time used is the
expiration time of the underlying credential (i.e., the lifetime
of the Kerberos TGT for example).
</p>
<p>
Tokens created with a webkdc-proxy token (id, proxy, cred) will
have the same expiration time as the webkdc-proxy token, so this
directive also controls the lifetime of those tokens as well.
</p>
<p>
The units for the time are specified by appending a single letter.
This letter may be one of <code>s</code>, <code>m</code>,
<code>h</code>, <code>d</code>, or <code>w</code>, which
correspond to seconds, minutes, hours, days, and weeks,
respectively.
</p>
<div class="note">
<h3>Note</h3>
<p>
The upper bound of the webkdc-proxy token is always bounded by
the expiration time of the underlying proxied credential. For
example, if the Kerberos TGT expires in 25 hours, then the
WebKDC will not create a webkdc-proxy token with a lifetime
greater then 25 hours, even if this directive is set higher then
25 hours.
</p>
</div>
<div class="example"><h3>Example</h3><pre># create a webkdc-proxy token valid for 2 hours
WebKdcProxyTokenLifetime 2h</pre></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcServiceTokenLifetime" id="WebKdcServiceTokenLifetime">WebKdcServiceTokenLifetime</a> <a name="webkdcservicetokenlifetime" id="webkdcservicetokenlifetime">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Lifetime of webkdc-service tokens we create</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcServiceTokenLifetime <em>nnnn[s|m|h|d|w]</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>(none)</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
This directive controls the lifetime of the webkdc-service token
we create. This controls how often a WebAuth application server
needs to re-authenticate with the WebKDC to get a new service
token. The lifetime of the service token (and the
webkdc-proxy-token) control how often the WebKDC can change its
private key, and how long it should retain the previous key
for.
</p>
<p>
A reasonable setting for this directive is 30 days, with the
private key of the WebKDC being changed every 60 days or so,
keeping the previous WebKDC private key around for 30 days after
it expires.
</p>
<p>
The units for the time are specified by appending a single letter.
This letter may be one of <code>s</code>, <code>m</code>,
<code>h</code>, <code>d</code>, or <code>w</code>, which
correspond to seconds, minutes, hours, days, and weeks,
respectively.
</p>
<div class="note">
<h3>Note</h3>
<p>This directive must be set.</p>
</div>
<div class="example"><h3>Example</h3><pre># create a webkdc-service token valid for 30 days
WebKdcServiceTokenLifetime 30d</pre></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcTokenAcl" id="WebKdcTokenAcl">WebKdcTokenAcl</a> <a name="webkdctokenacl" id="webkdctokenacl">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Path to file containing the token ACL</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcTokenAcl <em>path</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>(none)</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
This is the name of the file containing the ACL that controls
access to who can request tokens. Each line that isn't blank or
starting with <code>#</code> specifies a type of token that the
given Kerberos principal may request.
</p>
<p>
The first space-separated field of each line is an identifier (at
present, always a Kerberos principal) which may contain
<code>*</code> as a wildcard. The second field is either
<code>id</code>, saying that this Kerberos principal may request
id tokens (giving the authenticated identity of the user), or
<code>cred</code>, saying that this principal may request
credentials allowing it to act as the user. For type
<code>cred</code>, there are two more fields, one giving the type
(always <code>krb5</code> for now) and the other giving the
Kerberos service ticket that may be requested.
</p>
<div class="example"><h3>Example ACL File</h3><pre># allow anyone with a webauth keytab to request id tokens
krb5:webauth/*@EXAMPLE.ORG id
# allow shred to request a service/foobar credential
krb5:webauth/shred.example.org@EXAMPLE.ORG cred krb5 service/foobar@EXAMPLE.ORG</pre></div>
<p>
The <code>krb5:</code> prefix on the subject is used to signify
that the named principal was authenticated using Kerberos.
Currently, krb5 is the only supported mechanism for WebAuth
servers to initially authenticate with the WebKDC. Other types of
authentication maybe supported in the future.
</p>
<p>
If the path is not absolute, it will be considered relative to
<code class="directive">ServerRoot</code>.
</p>
<div class="note">
<h3>Note</h3>
<p>
This directive must be set.
</p>
<p>
The ACL file is cached in memory, but will be re-read
automatically if the modification timestamp on the file
changes.
</p>
</div>
<div class="example"><h3>Example</h3><p><code>
WebKdcTokenAcl conf/webkdc/token.acl
</code></p></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebkdcTokenMaxTTL" id="WebkdcTokenMaxTTL">WebkdcTokenMaxTTL</a> <a name="webkdctokenmaxttl" id="webkdctokenmaxttl">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>
How request old tokens may be before they're considered stale
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcTokenMaxTTL <em>nnnn[s|m|h|d|w]</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>WebKdcTokenMaxTTL 300s</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
This directive controls how old request tokens may be before
they're considered stale. This establishes the limit on how long
a user may take while logging in via WebLogin. It also sets a
limit on how old the request token used by the WAS to request
other tokens via getTokensRequest, but since this is generated
with each request and sent in combination with other tokens or
authenticators that have their own expirations, this second limit
is generally not important.
</p>
<p>
It is important to keep the clocks of the web application servers
and the WebKDC synchronized; if they aren't, all tokens from that
application server may be considered stale. This directive should
be set to at least as long as the amount of clock skew between the
WAS and the WebKDC that should be tolerated.
</p>
<p>
The units for the TTL are specified by appending a single letter.
This letter may be one of <code>s</code>, <code>m</code>,
<code>h</code>, <code>d</code>, or <code>w</code>, which
correspond to seconds, minutes, hours, days, and weeks,
respectively.
</p>
<div class="example"><h3>Example</h3><pre># two hour TTL
WebKdcTokenMaxTTL 2h</pre></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcUserInfoIgnoreFail" id="WebKdcUserInfoIgnoreFail">WebKdcUserInfoIgnoreFail</a> <a name="webkdcuserinfoignorefail" id="webkdcuserinfoignorefail">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>
Whether to allow password authentication despite user information
service failure
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcUserInfoIgnoreFail on|off</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>WebKdcUserInfoIgnoreFail off</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
By default, if a user information service is configured but either
doesn't respond or returns an error, mod_webkdc returns an error
and no authentication is permitted. This is the safest action
from a security perspective since the system fails closed, but it
can create a single point of failure in the user information
service that can bring down all web authentication.
</p>
<p>
If this option is turned on, users will still be able to do basic
password authentication (equivalent to what is possible without
configuring a user information service) if the user information
service doesn't respond or returns an error. Only a password
factor will be permitted, and the user will not be able to
establish a level of assurance. If the WAS requested any
additional factors or a level of assurance, the behavior will be
the same as if the user doesn't have those factors or LoA
configured.
</p>
<p>
This directive is only useful in combination with
<a href="#webkdcuserinfourl"><code class="directive">WebKdcUserInfoURL</code></a>.
</p>
<div class="example"><h3>Example</h3><p><code>
WebKdcUserInfoIgnoreFail on
</code></p></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcUserInfoPrincipal" id="WebKdcUserInfoPrincipal">WebKdcUserInfoPrincipal</a> <a name="webkdcuserinfoprincipal" id="webkdcuserinfoprincipal">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>
Remote principal for user information and multifactor queries
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcUserInfoPrincipal <em>principal</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>(none)</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
This directive sets the principal of the remote user information
and multifactor authentication service. This is the target
principal of the WebKDC's authentication if using a user
information protocol that uses Kerberos authentication (such as
remctl). It is not the principal used by the WebKDC; that's set
with
<a href="#webkdckeytab"><code class="directive">WebKdcKeytab</code></a>.
Rather, it's the principal of the remote service, required if the
host principal of the system on which it's running is not used.
</p>
<p>
This directive is only useful in combination with
<a href="#webkdcuserinfourl"><code class="directive">WebKdcUserInfoURL</code></a>.
</p>
<div class="example"><h3>Example</h3><p><code>
WebKdcUserInfoPrincipal remctl/userdb.example.com@EXAMPLE.COM
</code></p></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcUserInfoTimeout" id="WebKdcUserInfoTimeout">WebKdcUserInfoTimeout</a> <a name="webkdcuserinfotimeout" id="webkdcuserinfotimeout">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>
Timeout for user information and multifactor queries
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcUserInfoTimeout <em>nnnn[s|m|h|d|w]</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>WebKdcUserInfoTimeout 30s</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
Sets the timeout for user information service queries and for
multifactor authentication. The timeout is enforced on each
network exchange with the remote service, not on the total elapsed
time for the query, so be aware that a query to a
slowly-responding remote service that hands back small bits of
data at a time could still take substantially longer in total than
the timeout.
</p>
<p>
The timeout can be set to 0s to disable timeouts. With this
setting, mod_webkdc will wait for the remote service for as long
as it takes to respond or for the underlying TCP session to time
out.
</p>
<p>
Logins through the WebLogin server will block while the remote
service is queried, and this will block the Apache thread or
process that's attempting to handle that login. Setting too long
of a timeout may therefore allow the WebLogin server to be
overwhelmed if a remote server is down or not responding. The
default timeout is fairly generous.
</p>
<p>
For the remctl user information protocol method, setting a timeout
requires remctl 3.1 or later. If WebAuth is built against an
earlier version, the timeout will be ignored.
</p>
<p>
The units for the time are specified by appending a single letter.
This letter may be one of <code>s</code>, <code>m</code>,
<code>h</code>, <code>d</code>, or <code>w</code>, which
correspond to seconds, minutes, hours, days, and weeks,
respectively (although the longer intervals are probably not
useful).
</p>
<p>
This directive is only useful in combination with
<a href="#webkdcuserinfourl"><code class="directive">WebKdcUserInfoURL</code></a>.
</p>
<div class="example"><h3>Example</h3><p><code>
WebKdcUserInfoTimeout 5s
</code></p></div>
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="WebKdcUserInfoURL" id="WebKdcUserInfoURL">WebKdcUserInfoURL</a> <a name="webkdcuserinfourl" id="webkdcuserinfourl">Directive</a></h2>
<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>
URL for user information and multifactor queries
</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>WebKdcUserInfoURL <em>url</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>(none)</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>External</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_webkdc</td></tr>
</table>
<p>
The WebKDC supports a user information and multifactor
authentication service which, if configured, is checked for the
user's configured authentication factors, level of assurance, and
password expiration time. If this service is available and the
user's list of configured factors indicate that they are capable
of authenticating with a second factor (besides password), the
WebKDC will also trigger multifactor authentication for sites that
require it or if the user information service says it's required.
This service is also used to determine whether an account
requiring random multifactor should have that requirement trigger
for this site visit.
</p>
<p>
This directive configures the URL of the service. Currently, the
only supported protocol method is <a href="http://www.eyrie.org/~eagle/software/remctl/">remctl</a>.
The server and port are specified with the normal URL syntax, and
the port defaults to the normal remctl port. The path portion of
the URL must contain only one component and must be the command
portion of the remctl command. By default, remctl will assume
that the host principal of the provided host name should be used
as the authentication target. To change this, see <a href="#webkdcuserinfoprincipal"><code class="directive">WebKdcUserInfoPrincipal</code></a>.
</p>
<p>
The subcommand sent to the remctl server will be
<code>webkdc-userinfo</code> for the user information query during
login and <code>webkdc-validate</code> to validate a one-time
password authentication.
</p>
<p>
For specific details of the protocol used to talk to the user
information and multifactor authentication service, see the
additional protocol documentation that comes with the WebAuth
source distribution.
</p>
<div class="example"><h3>Example</h3><pre># Contact host userdb.example.com and send user webkdc-userinfo
WebKdcUserInfoURL remctl://userdb.example.com/user</pre></div>
</div>
</div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="../en/mod/mod_webkdc.html" title="English"> en </a></p>
</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div>
<div id="footer">
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
if (typeof(prettyPrint) !== 'undefined') {
prettyPrint();
}
//--><!]]></script>
</body></html>
|
