projects / GitHub / WoltLab / woltlab.github.io.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Copied 5.4 to latest with mike 0.5.5
[GitHub/WoltLab/woltlab.github.io.git] / latest / migration / wsc53 / session / index.html
CommitLineData
0c5338dd
TD		 1
2<!doctype html>
3<html lang="en" class="no-js">
4 <head>
5
6 <meta charset="utf-8">
7 <meta name="viewport" content="width=device-width,initial-scale=1">
8
9
10
11
12 <link rel="shortcut icon" href="../../../assets/default.favicon.ico">
13 <meta name="generator" content="mkdocs-1.1.2, mkdocs-material-7.0.3">
14
15
16
17 <title>Session Handling and Authentication - WoltLab Suite Documentation</title>
18
19
20
21 <link rel="stylesheet" href="../../../assets/stylesheets/main.1655a90d.min.css">
22
23
24 <link rel="stylesheet" href="../../../assets/stylesheets/palette.7fa14f5b.min.css">
25
26
27
28 <meta name="theme-color" content="#009485">
29
30
31
32
33
34
35
36
37 <link rel="stylesheet" href="../../../stylesheets/extra.css">
38
39
40
41
42
43 </head>
44
45
46
47
48
49
50
51 <body dir="ltr" data-md-color-scheme="" data-md-color-primary="teal" data-md-color-accent="">
52
53
54
55 <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
56 <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
57 <label class="md-overlay" for="__drawer"></label>
58 <div data-md-component="skip">
59
60
61 <a href="#migrating-from-wsc-53-session-handling-and-authentication" class="md-skip">
62 Skip to content
63 </a>
64
65 </div>
66 <div data-md-component="announce">
67
68 <aside class="md-announce">
69 <div class="md-announce__inner md-grid md-typeset">
70
71 <a href="https://www.woltlab.com">Back to <strong>woltlab.com</strong></a>
72
73 </div>
74 </aside>
75
76 </div>
77
78
79
80<header class="md-header" data-md-component="header">
81 <nav class="md-header__inner md-grid" aria-label="Header">
82 <a href="../../.." title="WoltLab Suite Documentation" class="md-header__button md-logo" aria-label="WoltLab Suite Documentation">
83
84 <img src="../../../assets/logo.png" alt="logo">
85
86 </a>
87 <label class="md-header__button md-icon" for="__drawer">
88 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2z"/></svg>
89 </label>
90 <div class="md-header__title" data-md-component="header-title">
91 <div class="md-header__ellipsis">
92 <div class="md-header__topic">
93 <span class="md-ellipsis">
94 WoltLab Suite Documentation
95 </span>
96 </div>
97 <div class="md-header__topic" data-md-component="header-topic">
98 <span class="md-ellipsis">
99
100 Session Handling and Authentication
101
102 </span>
103 </div>
104 </div>
105 </div>
106 <div class="md-header__options">
107
108 </div>
109
110 <label class="md-header__button md-icon" for="__search">
111 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg>
112 </label>
113
114<div class="md-search" data-md-component="search" role="dialog">
115 <label class="md-search__overlay" for="__search"></label>
116 <div class="md-search__inner" role="search">
117 <form class="md-search__form" name="search">
118 <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" data-md-state="active" required>
119 <label class="md-search__icon md-icon" for="__search">
120 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5z"/></svg>
121 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg>
122 </label>
123 <button type="reset" class="md-search__icon md-icon" aria-label="Clear" tabindex="-1">
124 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41z"/></svg>
125 </button>
126 </form>
127 <div class="md-search__output">
128 <div class="md-search__scrollwrap" data-md-scrollfix>
129 <div class="md-search-result" data-md-component="search-result">
130 <div class="md-search-result__meta">
131 Initializing search
132 </div>
133 <ol class="md-search-result__list"></ol>
134 </div>
135 </div>
136 </div>
137 </div>
138</div>
139
140
141 </nav>
142</header>
143
144 <div class="md-container" data-md-component="container">
145
146
147
148
149 <main class="md-main" data-md-component="main">
150 <div class="md-main__inner md-grid">
151
152
153
154 <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
155 <div class="md-sidebar__scrollwrap">
156 <div class="md-sidebar__inner">
157
158
159
160
161
162<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
163 <label class="md-nav__title" for="__drawer">
164 <a href="../../.." title="WoltLab Suite Documentation" class="md-nav__button md-logo" aria-label="WoltLab Suite Documentation">
165
166 <img src="../../../assets/logo.png" alt="logo">
167
168 </a>
169 WoltLab Suite Documentation
170 </label>
171
172 <ul class="md-nav__list" data-md-scrollfix>
173
174
175
176
177
178
179
180
181 <li class="md-nav__item">
182 <a href="../../../getting-started/" class="md-nav__link">
183 Getting Started
184 </a>
185 </li>
186
187
188
189
190
191
192
193
194
195
196
197 <li class="md-nav__item md-nav__item--nested">
198
199
200 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2" type="checkbox" id="__nav_2" >
201
202 <label class="md-nav__link" for="__nav_2">
203 PHP API
204 <span class="md-nav__icon md-icon"></span>
205 </label>
206 <nav class="md-nav" aria-label="PHP API" data-md-level="1">
207 <label class="md-nav__title" for="__nav_2">
208 <span class="md-nav__icon md-icon"></span>
209 PHP API
210 </label>
211 <ul class="md-nav__list" data-md-scrollfix>
212
213
214
215
216
217 <li class="md-nav__item">
218 <a href="../../../php/pages/" class="md-nav__link">
219 Pages
220 </a>
221 </li>
222
223
224
225
226
227
228
229 <li class="md-nav__item">
230 <a href="../../../php/database-objects/" class="md-nav__link">
231 Database Objects
232 </a>
233 </li>
234
235
236
237
238
239
240
241 <li class="md-nav__item">
242 <a href="../../../php/database-access/" class="md-nav__link">
243 Database Access
244 </a>
245 </li>
246
247
248
249
250
251
252
253 <li class="md-nav__item">
254 <a href="../../../php/exceptions/" class="md-nav__link">
255 Exceptions
256 </a>
257 </li>
258
259
260
261
262
263
264
265
266 <li class="md-nav__item md-nav__item--nested">
267
268
269 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2_5" type="checkbox" id="__nav_2_5" >
270
271 <label class="md-nav__link" for="__nav_2_5">
272 API
273 <span class="md-nav__icon md-icon"></span>
274 </label>
275 <nav class="md-nav" aria-label="API" data-md-level="2">
276 <label class="md-nav__title" for="__nav_2_5">
277 <span class="md-nav__icon md-icon"></span>
278 API
279 </label>
280 <ul class="md-nav__list" data-md-scrollfix>
281
282
283
284
285
286 <li class="md-nav__item">
287 <a href="../../../php/api/caches/" class="md-nav__link">
288 Caches
289 </a>
290 </li>
291
292
293
294
295
296
297
298 <li class="md-nav__item">
299 <a href="../../../php/api/comments/" class="md-nav__link">
300 Comments
301 </a>
302 </li>
303
304
305
306
307
308
309
310 <li class="md-nav__item">
311 <a href="../../../php/api/cronjobs/" class="md-nav__link">
312 Cronjobs
313 </a>
314 </li>
315
316
317
318
319
320
321
322 <li class="md-nav__item">
323 <a href="../../../php/api/events/" class="md-nav__link">
324 Events
325 </a>
326 </li>
327
328
329
330
331
332
333
334
335 <li class="md-nav__item md-nav__item--nested">
336
337
338 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_2_5_5" type="checkbox" id="__nav_2_5_5" >
339
340 <label class="md-nav__link" for="__nav_2_5_5">
341 Form Builder
342 <span class="md-nav__icon md-icon"></span>
343 </label>
344 <nav class="md-nav" aria-label="Form Builder" data-md-level="3">
345 <label class="md-nav__title" for="__nav_2_5_5">
346 <span class="md-nav__icon md-icon"></span>
347 Form Builder
348 </label>
349 <ul class="md-nav__list" data-md-scrollfix>
350
351
352
353
354
355 <li class="md-nav__item">
356 <a href="../../../php/api/form_builder/overview/" class="md-nav__link">
357 Overview
358 </a>
359 </li>
360
361
362
363
364
365
366
367 <li class="md-nav__item">
368 <a href="../../../php/api/form_builder/structure/" class="md-nav__link">
369 Structure
370 </a>
371 </li>
372
373
374
375
376
377
378
379 <li class="md-nav__item">
380 <a href="../../../php/api/form_builder/form_fields/" class="md-nav__link">
381 Fields
382 </a>
383 </li>
384
385
386
387
388
389
390
391 <li class="md-nav__item">
392 <a href="../../../php/api/form_builder/validation_data/" class="md-nav__link">
393 Validation and Data
394 </a>
395 </li>
396
397
398
399
400
401
402
403 <li class="md-nav__item">
404 <a href="../../../php/api/form_builder/dependencies/" class="md-nav__link">
405 Dependencies
406 </a>
407 </li>
408
409
410
411 </ul>
412 </nav>
413 </li>
414
415
416
417
418
419
420
421 <li class="md-nav__item">
422 <a href="../../../php/api/package_installation_plugins/" class="md-nav__link">
423 Package Installation Plugins
424 </a>
425 </li>
426
427
428
429
430
431
432
433 <li class="md-nav__item">
434 <a href="../../../php/api/user_activity_points/" class="md-nav__link">
435 User Activity Points
436 </a>
437 </li>
438
439
440
441
442
443
444
445 <li class="md-nav__item">
446 <a href="../../../php/api/user_notifications/" class="md-nav__link">
447 User Notifications
448 </a>
449 </li>
450
451
452
453
454
455
456
457 <li class="md-nav__item">
458 <a href="../../../php/api/sitemaps/" class="md-nav__link">
459 Sitemaps
460 </a>
461 </li>
462
463
464
465 </ul>
466 </nav>
467 </li>
468
469
470
471
472
473
474
475 <li class="md-nav__item">
476 <a href="../../../php/code-style/" class="md-nav__link">
477 Code Style
478 </a>
479 </li>
480
481
482
483
484
485
486
487 <li class="md-nav__item">
488 <a href="../../../php/apps/" class="md-nav__link">
489 Apps
490 </a>
491 </li>
492
493
494
495
496
497
498
499 <li class="md-nav__item">
500 <a href="../../../php/gdpr/" class="md-nav__link">
501 GDPR
502 </a>
503 </li>
504
505
506
507 </ul>
508 </nav>
509 </li>
510
511
512
513
514
515
516
517
518
519
520
521 <li class="md-nav__item md-nav__item--nested">
522
523
524 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_3" type="checkbox" id="__nav_3" >
525
526 <label class="md-nav__link" for="__nav_3">
527 Languages, Templates & CSS
528 <span class="md-nav__icon md-icon"></span>
529 </label>
530 <nav class="md-nav" aria-label="Languages, Templates & CSS" data-md-level="1">
531 <label class="md-nav__title" for="__nav_3">
532 <span class="md-nav__icon md-icon"></span>
533 Languages, Templates & CSS
534 </label>
535 <ul class="md-nav__list" data-md-scrollfix>
536
537
538
539
540
541 <li class="md-nav__item">
542 <a href="../../../view/languages/" class="md-nav__link">
543 Languages
544 </a>
545 </li>
546
547
548
549
550
551
552
553 <li class="md-nav__item">
554 <a href="../../../view/templates/" class="md-nav__link">
555 Templates
556 </a>
557 </li>
558
559
560
561
562
563
564
565 <li class="md-nav__item">
566 <a href="../../../view/css/" class="md-nav__link">
567 CSS
568 </a>
569 </li>
570
571
572
573 </ul>
574 </nav>
575 </li>
576
577
578
579
580
581
582
583
584
585
586
587 <li class="md-nav__item md-nav__item--nested">
588
589
590 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4" type="checkbox" id="__nav_4" >
591
592 <label class="md-nav__link" for="__nav_4">
593 JavaScript API
594 <span class="md-nav__icon md-icon"></span>
595 </label>
596 <nav class="md-nav" aria-label="JavaScript API" data-md-level="1">
597 <label class="md-nav__title" for="__nav_4">
598 <span class="md-nav__icon md-icon"></span>
599 JavaScript API
600 </label>
601 <ul class="md-nav__list" data-md-scrollfix>
602
603
604
605
606
607 <li class="md-nav__item">
608 <a href="../../../javascript/general-usage/" class="md-nav__link">
609 General Usage
610 </a>
611 </li>
612
613
614
615
616
617
618
619
620 <li class="md-nav__item md-nav__item--nested">
621
622
623 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_4_2" type="checkbox" id="__nav_4_2" >
624
625 <label class="md-nav__link" for="__nav_4_2">
626 New API
627 <span class="md-nav__icon md-icon"></span>
628 </label>
629 <nav class="md-nav" aria-label="New API" data-md-level="2">
630 <label class="md-nav__title" for="__nav_4_2">
631 <span class="md-nav__icon md-icon"></span>
632 New API
633 </label>
634 <ul class="md-nav__list" data-md-scrollfix>
635
636
637
638
639
640 <li class="md-nav__item">
641 <a href="../../../javascript/new-api_writing-a-module/" class="md-nav__link">
642 Writing a module
643 </a>
644 </li>
645
646
647
648
649
650
651
652 <li class="md-nav__item">
653 <a href="../../../javascript/new-api_data-structures/" class="md-nav__link">
654 Data Structures
655 </a>
656 </li>
657
658
659
660
661
662
663
664 <li class="md-nav__item">
665 <a href="../../../javascript/new-api_core/" class="md-nav__link">
666 Core Functions
667 </a>
668 </li>
669
670
671
672
673
674
675
676 <li class="md-nav__item">
677 <a href="../../../javascript/new-api_dom/" class="md-nav__link">
678 DOM
679 </a>
680 </li>
681
682
683
684
685
686
687
688 <li class="md-nav__item">
689 <a href="../../../javascript/new-api_events/" class="md-nav__link">
690 Event Handling
691 </a>
692 </li>
693
694
695
696
697
698
699
700 <li class="md-nav__item">
701 <a href="../../../javascript/new-api_ajax/" class="md-nav__link">
702 Ajax
703 </a>
704 </li>
705
706
707
708
709
710
711
712 <li class="md-nav__item">
713 <a href="../../../javascript/new-api_dialogs/" class="md-nav__link">
714 Dialogs
715 </a>
716 </li>
717
718
719
720
721
722
723
724 <li class="md-nav__item">
725 <a href="../../../javascript/new-api_browser/" class="md-nav__link">
726 Browser and Screen Sizes
727 </a>
728 </li>
729
730
731
732
733
734
735
736 <li class="md-nav__item">
737 <a href="../../../javascript/new-api_ui/" class="md-nav__link">
738 User Interface
739 </a>
740 </li>
741
742
743
744 </ul>
745 </nav>
746 </li>
747
748
749
750
751
752
753
754 <li class="md-nav__item">
755 <a href="../../../javascript/legacy-api/" class="md-nav__link">
756 Legacy API
757 </a>
758 </li>
759
760
761
762
763
764
765
766 <li class="md-nav__item">
767 <a href="../../../javascript/helper-functions/" class="md-nav__link">
768 Helper Functions
769 </a>
770 </li>
771
772
773
774
775
776
777
778 <li class="md-nav__item">
779 <a href="../../../javascript/code-snippets/" class="md-nav__link">
780 Code Snippets
781 </a>
782 </li>
783
784
785
786 </ul>
787 </nav>
788 </li>
789
790
791
792
793
794
795
796
797
798
799
800 <li class="md-nav__item md-nav__item--nested">
801
802
803 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5" type="checkbox" id="__nav_5" >
804
805 <label class="md-nav__link" for="__nav_5">
806 Package Components
807 <span class="md-nav__icon md-icon"></span>
808 </label>
809 <nav class="md-nav" aria-label="Package Components" data-md-level="1">
810 <label class="md-nav__title" for="__nav_5">
811 <span class="md-nav__icon md-icon"></span>
812 Package Components
813 </label>
814 <ul class="md-nav__list" data-md-scrollfix>
815
816
817
818
819
820 <li class="md-nav__item">
821 <a href="../../../package/package-xml/" class="md-nav__link">
822 package.xml
823 </a>
824 </li>
825
826
827
828
829
830
831
832
833 <li class="md-nav__item md-nav__item--nested">
834
835
836 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_5_2" type="checkbox" id="__nav_5_2" >
837
838 <label class="md-nav__link" for="__nav_5_2">
839 PIPs
840 <span class="md-nav__icon md-icon"></span>
841 </label>
842 <nav class="md-nav" aria-label="PIPs" data-md-level="2">
843 <label class="md-nav__title" for="__nav_5_2">
844 <span class="md-nav__icon md-icon"></span>
845 PIPs
846 </label>
847 <ul class="md-nav__list" data-md-scrollfix>
848
849
850
851
852
853 <li class="md-nav__item">
854 <a href="../../../package/pip/" class="md-nav__link">
855 Overview
856 </a>
857 </li>
858
859
860
861
862
863
864
865 <li class="md-nav__item">
866 <a href="../../../package/pip/acl-option/" class="md-nav__link">
867 aclOption
868 </a>
869 </li>
870
871
872
873
874
875
876
877 <li class="md-nav__item">
878 <a href="../../../package/pip/acp-menu/" class="md-nav__link">
879 acpMenu
880 </a>
881 </li>
882
883
884
885
886
887
888
889 <li class="md-nav__item">
890 <a href="../../../package/pip/acp-search-provider/" class="md-nav__link">
891 acpSearchProvider
892 </a>
893 </li>
894
895
896
897
898
899
900
901 <li class="md-nav__item">
902 <a href="../../../package/pip/acp-template/" class="md-nav__link">
903 acpTemplate
904 </a>
905 </li>
906
907
908
909
910
911
912
913 <li class="md-nav__item">
914 <a href="../../../package/pip/bbcode/" class="md-nav__link">
915 bbcode
916 </a>
917 </li>
918
919
920
921
922
923
924
925 <li class="md-nav__item">
926 <a href="../../../package/pip/box/" class="md-nav__link">
927 box
928 </a>
929 </li>
930
931
932
933
934
935
936
937 <li class="md-nav__item">
938 <a href="../../../package/pip/clipboard-action/" class="md-nav__link">
939 clipboardAction
940 </a>
941 </li>
942
943
944
945
946
947
948
949 <li class="md-nav__item">
950 <a href="../../../package/pip/core-object/" class="md-nav__link">
951 coreObject
952 </a>
953 </li>
954
955
956
957
958
959
960
961 <li class="md-nav__item">
962 <a href="../../../package/pip/cronjob/" class="md-nav__link">
963 cronjob
964 </a>
965 </li>
966
967
968
969
970
971
972
973 <li class="md-nav__item">
974 <a href="../../../package/pip/event-listener/" class="md-nav__link">
975 eventListener
976 </a>
977 </li>
978
979
980
981
982
983
984
985 <li class="md-nav__item">
986 <a href="../../../package/pip/file/" class="md-nav__link">
987 file
988 </a>
989 </li>
990
991
992
993
994
995
996
997 <li class="md-nav__item">
998 <a href="../../../package/pip/language/" class="md-nav__link">
999 language
1000 </a>
1001 </li>
1002
1003
1004
1005
1006
1007
1008
1009 <li class="md-nav__item">
1010 <a href="../../../package/pip/media-provider/" class="md-nav__link">
1011 mediaProvider
1012 </a>
1013 </li>
1014
1015
1016
1017
1018
1019
1020
1021 <li class="md-nav__item">
1022 <a href="../../../package/pip/menu/" class="md-nav__link">
1023 menu
1024 </a>
1025 </li>
1026
1027
1028
1029
1030
1031
1032
1033 <li class="md-nav__item">
1034 <a href="../../../package/pip/menu-item/" class="md-nav__link">
1035 menuItem
1036 </a>
1037 </li>
1038
1039
1040
1041
1042
1043
1044
1045 <li class="md-nav__item">
1046 <a href="../../../package/pip/object-type/" class="md-nav__link">
1047 objectType
1048 </a>
1049 </li>
1050
1051
1052
1053
1054
1055
1056
1057 <li class="md-nav__item">
1058 <a href="../../../package/pip/object-type-definition/" class="md-nav__link">
1059 objectTypeDefinition
1060 </a>
1061 </li>
1062
1063
1064
1065
1066
1067
1068
1069 <li class="md-nav__item">
1070 <a href="../../../package/pip/option/" class="md-nav__link">
1071 option
1072 </a>
1073 </li>
1074
1075
1076
1077
1078
1079
1080
1081 <li class="md-nav__item">
1082 <a href="../../../package/pip/page/" class="md-nav__link">
1083 page
1084 </a>
1085 </li>
1086
1087
1088
1089
1090
1091
1092
1093 <li class="md-nav__item">
1094 <a href="../../../package/pip/pip/" class="md-nav__link">
1095 pip
1096 </a>
1097 </li>
1098
1099
1100
1101
1102
1103
1104
1105 <li class="md-nav__item">
1106 <a href="../../../package/pip/script/" class="md-nav__link">
1107 script
1108 </a>
1109 </li>
1110
1111
1112
1113
1114
1115
1116
1117 <li class="md-nav__item">
1118 <a href="../../../package/pip/smiley/" class="md-nav__link">
1119 smiley
1120 </a>
1121 </li>
1122
1123
1124
1125
1126
1127
1128
1129 <li class="md-nav__item">
1130 <a href="../../../package/pip/sql/" class="md-nav__link">
1131 sql
1132 </a>
1133 </li>
1134
1135
1136
1137
1138
1139
1140
1141 <li class="md-nav__item">
1142 <a href="../../../package/pip/style/" class="md-nav__link">
1143 style
1144 </a>
1145 </li>
1146
1147
1148
1149
1150
1151
1152
1153 <li class="md-nav__item">
1154 <a href="../../../package/pip/template/" class="md-nav__link">
1155 template
1156 </a>
1157 </li>
1158
1159
1160
1161
1162
1163
1164
1165 <li class="md-nav__item">
1166 <a href="../../../package/pip/template-listener/" class="md-nav__link">
1167 templateListener
1168 </a>
1169 </li>
1170
1171
1172
1173
1174
1175
1176
1177 <li class="md-nav__item">
1178 <a href="../../../package/pip/user-group-option/" class="md-nav__link">
1179 userGroupOption
1180 </a>
1181 </li>
1182
1183
1184
1185
1186
1187
1188
1189 <li class="md-nav__item">
1190 <a href="../../../package/pip/user-menu/" class="md-nav__link">
1191 userMenu
1192 </a>
1193 </li>
1194
1195
1196
1197
1198
1199
1200
1201 <li class="md-nav__item">
1202 <a href="../../../package/pip/user-notification-event/" class="md-nav__link">
1203 userNotificationEvent
1204 </a>
1205 </li>
1206
1207
1208
1209
1210
1211
1212
1213 <li class="md-nav__item">
1214 <a href="../../../package/pip/user-option/" class="md-nav__link">
1215 userOption
1216 </a>
1217 </li>
1218
1219
1220
1221
1222
1223
1224
1225 <li class="md-nav__item">
1226 <a href="../../../package/pip/user-profile-menu/" class="md-nav__link">
1227 userProfileMenu
1228 </a>
1229 </li>
1230
1231
1232
1233 </ul>
1234 </nav>
1235 </li>
1236
1237
1238
1239
1240
1241
1242
1243 <li class="md-nav__item">
1244 <a href="../../../package/database-php-api/" class="md-nav__link">
1245 Database PHP API
1246 </a>
1247 </li>
1248
1249
1250
1251 </ul>
1252 </nav>
1253 </li>
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267 <li class="md-nav__item md-nav__item--active md-nav__item--nested">
1268
1269
1270 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6" type="checkbox" id="__nav_6" checked>
1271
1272 <label class="md-nav__link" for="__nav_6">
1273 Migration
1274 <span class="md-nav__icon md-icon"></span>
1275 </label>
1276 <nav class="md-nav" aria-label="Migration" data-md-level="1">
1277 <label class="md-nav__title" for="__nav_6">
1278 <span class="md-nav__icon md-icon"></span>
1279 Migration
1280 </label>
1281 <ul class="md-nav__list" data-md-scrollfix>
1282
1283
1284
1285
1286
1287
1288
1289
1290 <li class="md-nav__item md-nav__item--active md-nav__item--nested">
1291
1292
1293 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_1" type="checkbox" id="__nav_6_1" checked>
1294
1295 <label class="md-nav__link" for="__nav_6_1">
1296 Migrating from WSC 5.3
1297 <span class="md-nav__icon md-icon"></span>
1298 </label>
1299 <nav class="md-nav" aria-label="Migrating from WSC 5.3" data-md-level="2">
1300 <label class="md-nav__title" for="__nav_6_1">
1301 <span class="md-nav__icon md-icon"></span>
1302 Migrating from WSC 5.3
1303 </label>
1304 <ul class="md-nav__list" data-md-scrollfix>
1305
1306
1307
1308
1309
1310 <li class="md-nav__item">
1311 <a href="../php/" class="md-nav__link">
1312 PHP API
1313 </a>
1314 </li>
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324 <li class="md-nav__item md-nav__item--active">
1325
1326 <input class="md-nav__toggle md-toggle" data-md-toggle="toc" type="checkbox" id="__toc">
1327
1328
1329
1330
1331 <label class="md-nav__link md-nav__link--active" for="__toc">
1332 Session Handling and Authentication
1333 <span class="md-nav__icon md-icon"></span>
1334 </label>
1335
1336 <a href="./" class="md-nav__link md-nav__link--active">
1337 Session Handling and Authentication
1338 </a>
1339
1340
1341<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
1342
1343
1344
1345
1346
1347 <label class="md-nav__title" for="__toc">
1348 <span class="md-nav__icon md-icon"></span>
1349 Table of contents
1350 </label>
1351 <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
1352
1353 <li class="md-nav__item">
1354 <a href="#summary-and-concepts" class="md-nav__link">
1355 Summary and Concepts
1356 </a>
1357
1358 <nav class="md-nav" aria-label="Summary and Concepts">
1359 <ul class="md-nav__list">
1360
1361 <li class="md-nav__item">
1362 <a href="#legacy-persistent-login" class="md-nav__link">
1363 Legacy Persistent Login
1364 </a>
1365
1366</li>
1367
1368 <li class="md-nav__item">
1369 <a href="#multiple-sessions" class="md-nav__link">
1370 Multiple Sessions
1371 </a>
1372
1373</li>
1374
1375 <li class="md-nav__item">
1376 <a href="#merged-acp-and-frontend-sessions" class="md-nav__link">
1377 Merged ACP and Frontend Sessions
1378 </a>
1379
1380</li>
1381
1382 <li class="md-nav__item">
1383 <a href="#improved-authentication-and-reauthentication" class="md-nav__link">
1384 Improved Authentication and Reauthentication
1385 </a>
1386
1387</li>
1388
1389 </ul>
1390 </nav>
1391
1392</li>
1393
1394 <li class="md-nav__item">
1395 <a href="#additions-and-changes" class="md-nav__link">
1396 Additions and Changes
1397 </a>
1398
1399 <nav class="md-nav" aria-label="Additions and Changes">
1400 <ul class="md-nav__list">
1401
1402 <li class="md-nav__item">
1403 <a href="#password-hashing" class="md-nav__link">
1404 Password Hashing
1405 </a>
1406
1407</li>
1408
1409 <li class="md-nav__item">
1410 <a href="#session-storage" class="md-nav__link">
1411 Session Storage
1412 </a>
1413
1414</li>
1415
1416 <li class="md-nav__item">
1417 <a href="#reauthentication" class="md-nav__link">
1418 Reauthentication
1419 </a>
1420
1421</li>
1422
1423 <li class="md-nav__item">
1424 <a href="#multi-factor-authentication" class="md-nav__link">
1425 Multi-factor Authentication
1426 </a>
1427
1428 <nav class="md-nav" aria-label="Multi-factor Authentication">
1429 <ul class="md-nav__list">
1430
1431 <li class="md-nav__item">
1432 <a href="#adding-multi-factor-methods" class="md-nav__link">
1433 Adding Multi-factor Methods
1434 </a>
1435
1436</li>
1437
1438 </ul>
1439 </nav>
1440
1441</li>
1442
1443 </ul>
1444 </nav>
1445
1446</li>
1447
1448 <li class="md-nav__item">
1449 <a href="#deprecations-and-removals" class="md-nav__link">
1450 Deprecations and Removals
1451 </a>
1452
1453 <nav class="md-nav" aria-label="Deprecations and Removals">
1454 <ul class="md-nav__list">
1455
1456 <li class="md-nav__item">
1457 <a href="#sessionhandler" class="md-nav__link">
1458 SessionHandler
1459 </a>
1460
1461</li>
1462
1463 <li class="md-nav__item">
1464 <a href="#acp-sessions" class="md-nav__link">
1465 ACP Sessions
1466 </a>
1467
1468</li>
1469
1470 <li class="md-nav__item">
1471 <a href="#cookies" class="md-nav__link">
1472 Cookies
1473 </a>
1474
1475</li>
1476
1477 <li class="md-nav__item">
1478 <a href="#virtual-sessions" class="md-nav__link">
1479 Virtual Sessions
1480 </a>
1481
1482</li>
1483
1484 <li class="md-nav__item">
1485 <a href="#security-token-constants" class="md-nav__link">
1486 Security Token Constants
1487 </a>
1488
1489</li>
1490
1491 <li class="md-nav__item">
1492 <a href="#passwordutil-and-double-bcrypt-hashes" class="md-nav__link">
1493 PasswordUtil and Double BCrypt Hashes
1494 </a>
1495
1496</li>
1497
1498 </ul>
1499 </nav>
1500
1501</li>
1502
1503 </ul>
1504
1505</nav>
1506
1507 </li>
1508
1509
1510
1511
1512
1513
1514
1515 <li class="md-nav__item">
1516 <a href="../javascript/" class="md-nav__link">
1517 JavaScript
1518 </a>
1519 </li>
1520
1521
1522
1523
1524
1525
1526
1527 <li class="md-nav__item">
1528 <a href="../templates/" class="md-nav__link">
1529 Templates
1530 </a>
1531 </li>
1532
1533
1534
1535
1536
1537
1538
1539 <li class="md-nav__item">
1540 <a href="../libraries/" class="md-nav__link">
1541 Third Party Libraries
1542 </a>
1543 </li>
1544
1545
1546
1547 </ul>
1548 </nav>
1549 </li>
1550
1551
1552
1553
1554
1555
1556
1557
1558 <li class="md-nav__item md-nav__item--nested">
1559
1560
1561 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_2" type="checkbox" id="__nav_6_2" >
1562
1563 <label class="md-nav__link" for="__nav_6_2">
1564 Migrating from WSC 5.2
1565 <span class="md-nav__icon md-icon"></span>
1566 </label>
1567 <nav class="md-nav" aria-label="Migrating from WSC 5.2" data-md-level="2">
1568 <label class="md-nav__title" for="__nav_6_2">
1569 <span class="md-nav__icon md-icon"></span>
1570 Migrating from WSC 5.2
1571 </label>
1572 <ul class="md-nav__list" data-md-scrollfix>
1573
1574
1575
1576
1577
1578 <li class="md-nav__item">
1579 <a href="../../wsc52/php/" class="md-nav__link">
1580 PHP API
1581 </a>
1582 </li>
1583
1584
1585
1586
1587
1588
1589
1590 <li class="md-nav__item">
1591 <a href="../../wsc52/templates/" class="md-nav__link">
1592 Templates and Languages
1593 </a>
1594 </li>
1595
1596
1597
1598
1599
1600
1601
1602 <li class="md-nav__item">
1603 <a href="../../wsc52/libraries/" class="md-nav__link">
1604 Third Party Libraries
1605 </a>
1606 </li>
1607
1608
1609
1610 </ul>
1611 </nav>
1612 </li>
1613
1614
1615
1616
1617
1618
1619
1620
1621 <li class="md-nav__item md-nav__item--nested">
1622
1623
1624 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_3" type="checkbox" id="__nav_6_3" >
1625
1626 <label class="md-nav__link" for="__nav_6_3">
1627 Migrating from WSC 3.1
1628 <span class="md-nav__icon md-icon"></span>
1629 </label>
1630 <nav class="md-nav" aria-label="Migrating from WSC 3.1" data-md-level="2">
1631 <label class="md-nav__title" for="__nav_6_3">
1632 <span class="md-nav__icon md-icon"></span>
1633 Migrating from WSC 3.1
1634 </label>
1635 <ul class="md-nav__list" data-md-scrollfix>
1636
1637
1638
1639
1640
1641 <li class="md-nav__item">
1642 <a href="../../wsc31/php/" class="md-nav__link">
1643 PHP API
1644 </a>
1645 </li>
1646
1647
1648
1649 </ul>
1650 </nav>
1651 </li>
1652
1653
1654
1655
1656
1657
1658
1659
1660 <li class="md-nav__item md-nav__item--nested">
1661
1662
1663 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_4" type="checkbox" id="__nav_6_4" >
1664
1665 <label class="md-nav__link" for="__nav_6_4">
1666 Migrating from WSC 3.0
1667 <span class="md-nav__icon md-icon"></span>
1668 </label>
1669 <nav class="md-nav" aria-label="Migrating from WSC 3.0" data-md-level="2">
1670 <label class="md-nav__title" for="__nav_6_4">
1671 <span class="md-nav__icon md-icon"></span>
1672 Migrating from WSC 3.0
1673 </label>
1674 <ul class="md-nav__list" data-md-scrollfix>
1675
1676
1677
1678
1679
1680 <li class="md-nav__item">
1681 <a href="../../wsc30/php/" class="md-nav__link">
1682 PHP API
1683 </a>
1684 </li>
1685
1686
1687
1688
1689
1690
1691
1692 <li class="md-nav__item">
1693 <a href="../../wsc30/javascript/" class="md-nav__link">
1694 JavaScript API
1695 </a>
1696 </li>
1697
1698
1699
1700
1701
1702
1703
1704 <li class="md-nav__item">
1705 <a href="../../wsc30/templates/" class="md-nav__link">
1706 Templates
1707 </a>
1708 </li>
1709
1710
1711
1712
1713
1714
1715
1716 <li class="md-nav__item">
1717 <a href="../../wsc30/css/" class="md-nav__link">
1718 CSS
1719 </a>
1720 </li>
1721
1722
1723
1724
1725
1726
1727
1728 <li class="md-nav__item">
1729 <a href="../../wsc30/package/" class="md-nav__link">
1730 Package Components
1731 </a>
1732 </li>
1733
1734
1735
1736 </ul>
1737 </nav>
1738 </li>
1739
1740
1741
1742
1743
1744
1745
1746
1747 <li class="md-nav__item md-nav__item--nested">
1748
1749
1750 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_6_5" type="checkbox" id="__nav_6_5" >
1751
1752 <label class="md-nav__link" for="__nav_6_5">
1753 Migrating from WCF 2.1
1754 <span class="md-nav__icon md-icon"></span>
1755 </label>
1756 <nav class="md-nav" aria-label="Migrating from WCF 2.1" data-md-level="2">
1757 <label class="md-nav__title" for="__nav_6_5">
1758 <span class="md-nav__icon md-icon"></span>
1759 Migrating from WCF 2.1
1760 </label>
1761 <ul class="md-nav__list" data-md-scrollfix>
1762
1763
1764
1765
1766
1767 <li class="md-nav__item">
1768 <a href="../../wcf21/php/" class="md-nav__link">
1769 PHP API
1770 </a>
1771 </li>
1772
1773
1774
1775
1776
1777
1778
1779 <li class="md-nav__item">
1780 <a href="../../wcf21/templates/" class="md-nav__link">
1781 Templates
1782 </a>
1783 </li>
1784
1785
1786
1787
1788
1789
1790
1791 <li class="md-nav__item">
1792 <a href="../../wcf21/css/" class="md-nav__link">
1793 CSS
1794 </a>
1795 </li>
1796
1797
1798
1799
1800
1801
1802
1803 <li class="md-nav__item">
1804 <a href="../../wcf21/package/" class="md-nav__link">
1805 Package Components
1806 </a>
1807 </li>
1808
1809
1810
1811 </ul>
1812 </nav>
1813 </li>
1814
1815
1816
1817 </ul>
1818 </nav>
1819 </li>
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831 <li class="md-nav__item md-nav__item--nested">
1832
1833
1834 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7" type="checkbox" id="__nav_7" >
1835
1836 <label class="md-nav__link" for="__nav_7">
1837 Tutorials
1838 <span class="md-nav__icon md-icon"></span>
1839 </label>
1840 <nav class="md-nav" aria-label="Tutorials" data-md-level="1">
1841 <label class="md-nav__title" for="__nav_7">
1842 <span class="md-nav__icon md-icon"></span>
1843 Tutorials
1844 </label>
1845 <ul class="md-nav__list" data-md-scrollfix>
1846
1847
1848
1849
1850
1851
1852 <li class="md-nav__item md-nav__item--nested">
1853
1854
1855 <input class="md-nav__toggle md-toggle" data-md-toggle="__nav_7_1" type="checkbox" id="__nav_7_1" >
1856
1857 <label class="md-nav__link" for="__nav_7_1">
1858 Tutorial Series
1859 <span class="md-nav__icon md-icon"></span>
1860 </label>
1861 <nav class="md-nav" aria-label="Tutorial Series" data-md-level="2">
1862 <label class="md-nav__title" for="__nav_7_1">
1863 <span class="md-nav__icon md-icon"></span>
1864 Tutorial Series
1865 </label>
1866 <ul class="md-nav__list" data-md-scrollfix>
1867
1868
1869
1870
1871
1872 <li class="md-nav__item">
1873 <a href="../../../tutorial/series/overview/" class="md-nav__link">
1874 Overview
1875 </a>
1876 </li>
1877
1878
1879
1880
1881
1882
1883
1884 <li class="md-nav__item">
1885 <a href="../../../tutorial/series/part_1/" class="md-nav__link">
1886 Part 1
1887 </a>
1888 </li>
1889
1890
1891
1892
1893
1894
1895
1896 <li class="md-nav__item">
1897 <a href="../../../tutorial/series/part_2/" class="md-nav__link">
1898 Part 2
1899 </a>
1900 </li>
1901
1902
1903
1904
1905
1906
1907
1908 <li class="md-nav__item">
1909 <a href="../../../tutorial/series/part_3/" class="md-nav__link">
1910 Part 3
1911 </a>
1912 </li>
1913
1914
1915
1916 </ul>
1917 </nav>
1918 </li>
1919
1920
1921
1922 </ul>
1923 </nav>
1924 </li>
1925
1926
1927
1928 </ul>
1929</nav>
1930 </div>
1931 </div>
1932 </div>
1933
1934
1935
1936 <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
1937 <div class="md-sidebar__scrollwrap">
1938 <div class="md-sidebar__inner">
1939
1940<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
1941
1942
1943
1944
1945
1946 <label class="md-nav__title" for="__toc">
1947 <span class="md-nav__icon md-icon"></span>
1948 Table of contents
1949 </label>
1950 <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
1951
1952 <li class="md-nav__item">
1953 <a href="#summary-and-concepts" class="md-nav__link">
1954 Summary and Concepts
1955 </a>
1956
1957 <nav class="md-nav" aria-label="Summary and Concepts">
1958 <ul class="md-nav__list">
1959
1960 <li class="md-nav__item">
1961 <a href="#legacy-persistent-login" class="md-nav__link">
1962 Legacy Persistent Login
1963 </a>
1964
1965</li>
1966
1967 <li class="md-nav__item">
1968 <a href="#multiple-sessions" class="md-nav__link">
1969 Multiple Sessions
1970 </a>
1971
1972</li>
1973
1974 <li class="md-nav__item">
1975 <a href="#merged-acp-and-frontend-sessions" class="md-nav__link">
1976 Merged ACP and Frontend Sessions
1977 </a>
1978
1979</li>
1980
1981 <li class="md-nav__item">
1982 <a href="#improved-authentication-and-reauthentication" class="md-nav__link">
1983 Improved Authentication and Reauthentication
1984 </a>
1985
1986</li>
1987
1988 </ul>
1989 </nav>
1990
1991</li>
1992
1993 <li class="md-nav__item">
1994 <a href="#additions-and-changes" class="md-nav__link">
1995 Additions and Changes
1996 </a>
1997
1998 <nav class="md-nav" aria-label="Additions and Changes">
1999 <ul class="md-nav__list">
2000
2001 <li class="md-nav__item">
2002 <a href="#password-hashing" class="md-nav__link">
2003 Password Hashing
2004 </a>
2005
2006</li>
2007
2008 <li class="md-nav__item">
2009 <a href="#session-storage" class="md-nav__link">
2010 Session Storage
2011 </a>
2012
2013</li>
2014
2015 <li class="md-nav__item">
2016 <a href="#reauthentication" class="md-nav__link">
2017 Reauthentication
2018 </a>
2019
2020</li>
2021
2022 <li class="md-nav__item">
2023 <a href="#multi-factor-authentication" class="md-nav__link">
2024 Multi-factor Authentication
2025 </a>
2026
2027 <nav class="md-nav" aria-label="Multi-factor Authentication">
2028 <ul class="md-nav__list">
2029
2030 <li class="md-nav__item">
2031 <a href="#adding-multi-factor-methods" class="md-nav__link">
2032 Adding Multi-factor Methods
2033 </a>
2034
2035</li>
2036
2037 </ul>
2038 </nav>
2039
2040</li>
2041
2042 </ul>
2043 </nav>
2044
2045</li>
2046
2047 <li class="md-nav__item">
2048 <a href="#deprecations-and-removals" class="md-nav__link">
2049 Deprecations and Removals
2050 </a>
2051
2052 <nav class="md-nav" aria-label="Deprecations and Removals">
2053 <ul class="md-nav__list">
2054
2055 <li class="md-nav__item">
2056 <a href="#sessionhandler" class="md-nav__link">
2057 SessionHandler
2058 </a>
2059
2060</li>
2061
2062 <li class="md-nav__item">
2063 <a href="#acp-sessions" class="md-nav__link">
2064 ACP Sessions
2065 </a>
2066
2067</li>
2068
2069 <li class="md-nav__item">
2070 <a href="#cookies" class="md-nav__link">
2071 Cookies
2072 </a>
2073
2074</li>
2075
2076 <li class="md-nav__item">
2077 <a href="#virtual-sessions" class="md-nav__link">
2078 Virtual Sessions
2079 </a>
2080
2081</li>
2082
2083 <li class="md-nav__item">
2084 <a href="#security-token-constants" class="md-nav__link">
2085 Security Token Constants
2086 </a>
2087
2088</li>
2089
2090 <li class="md-nav__item">
2091 <a href="#passwordutil-and-double-bcrypt-hashes" class="md-nav__link">
2092 PasswordUtil and Double BCrypt Hashes
2093 </a>
2094
2095</li>
2096
2097 </ul>
2098 </nav>
2099
2100</li>
2101
2102 </ul>
2103
2104</nav>
2105 </div>
2106 </div>
2107 </div>
2108
2109
2110 <div class="md-content" data-md-component="content">
2111 <article class="md-content__inner md-typeset">
2112
2113
2114
2115 <h1 id="migrating-from-wsc-53-session-handling-and-authentication">Migrating from WSC 5.3 - Session Handling and Authentication<a class="headerlink" href="#migrating-from-wsc-53-session-handling-and-authentication" title="Permanent link">#</a></h1>
2116<p>WoltLab Suite 5.4 includes a completely refactored session handling.
2117As long as you only interact with sessions via <code>WCF::getSession()</code>, especially when you perform read-only accesses, you should not notice any breaking changes.</p>
2118<p>You might appreciate some of the new session methods if you process security sensitive data.</p>
2119<h2 id="summary-and-concepts">Summary and Concepts<a class="headerlink" href="#summary-and-concepts" title="Permanent link">#</a></h2>
2120<p>Most of the changes revolve around the removal of the legacy persistent login functionality and the assumption that every user has a single session only.
2121Both aspects are related to each other.</p>
2122<h3 id="legacy-persistent-login">Legacy Persistent Login<a class="headerlink" href="#legacy-persistent-login" title="Permanent link">#</a></h3>
2123<p>The legacy persistent login was rather an automated login.
2124Upon bootstrapping a session, it was checked whether the user had a cookie pair storing the user’s <code>userID</code> and (a single BCrypt hash of) the user’s password.
2125If such a cookie pair exists and the BCrypt hash within the cookie matches the user’s password hash when hashed again, the session would immediately <code>changeUser()</code> to the respective user.</p>
2126<p>This legacy persistent login was completely removed.
2127Instead, any sessions that belong to an authenticated user will automatically be long-lived.
2128These long-lived sessions expire no sooner than 14 days after the last activity, ensuring that the user continously stays logged in, provided that they visit the page at least once per fortnight.</p>
2129<h3 id="multiple-sessions">Multiple Sessions<a class="headerlink" href="#multiple-sessions" title="Permanent link">#</a></h3>
2130<p>To allow for a proper separation of these long-lived user sessions, WoltLab Suite now allows for multiple sessions per user.
2131These sessions are completely unrelated to each other.
2132Specifically, they do not share session variables and they expire independently.</p>
2133<p>As the existing <code>wcf1_session</code> table is also used for the online lists and location tracking, it will be maintained on a best effort basis.
2134It no longer stores any private session data.</p>
2135<p>The actual sessions storing security sensitive information are in an unrelated location.
2136They must only be accessed via the PHP API exposed by the <code>SessionHandler</code>.</p>
2137<h3 id="merged-acp-and-frontend-sessions">Merged ACP and Frontend Sessions<a class="headerlink" href="#merged-acp-and-frontend-sessions" title="Permanent link">#</a></h3>
2138<p>WoltLab Suite 5.4 shares a single session across both the frontend, as well as the ACP.
2139When a user logs in to the frontend, they will also be logged into the ACP and vice versa.</p>
2140<p>Actual access to the ACP is controlled via the new <a href="#reauthentication">reauthentication mechanism</a>.</p>
2141<p>The session variable store is scoped:
2142Session variables set within the frontend are not available within the ACP and vice versa.</p>
2143<h3 id="improved-authentication-and-reauthentication">Improved Authentication and Reauthentication<a class="headerlink" href="#improved-authentication-and-reauthentication" title="Permanent link">#</a></h3>
2144<p>WoltLab Suite 5.4 ships with multi-factor authentication support and a generic re-authentication implementation that can be used to verify the account owner’s presence.</p>
2145<h2 id="additions-and-changes">Additions and Changes<a class="headerlink" href="#additions-and-changes" title="Permanent link">#</a></h2>
2146<h3 id="password-hashing">Password Hashing<a class="headerlink" href="#password-hashing" title="Permanent link">#</a></h3>
2147<p>WoltLab Suite 5.4 includes a new object-oriented password hashing framework that is modeled after PHP’s <code>password_*</code> API.
2148Check <a href="https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/user/authentication/password/PasswordAlgorithmManager.class.php"><code>PasswordAlgorithmManager</code></a> and <a href="https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/user/authentication/password/IPasswordAlgorithm.class.php"><code>IPasswordAlgorithm</code></a> for details.</p>
2149<p>The new default password hash is a standard BCrypt hash.
2150All newly generated hashes in <code>wcf1_user.password</code> will now include a type prefix, instead of just passwords imported from other systems.</p>
2151<h3 id="session-storage">Session Storage<a class="headerlink" href="#session-storage" title="Permanent link">#</a></h3>
2152<p>The <code>wcf1_session</code> table will no longer be used for session storage.
2153Instead, it is maintained for compatibility with existing online lists.</p>
2154<p>The actual session storage is considered an implementation detail and you <em>must not</em> directly interact with the session tables.
2155Future versions might support alternative session backends, such as Redis.</p>
2156<div class="admonition warning">
2157<p class="admonition-title">Do not interact directly with the session database tables but only via the <code>SessionHandler</code> class!</p>
2158</div>
2159<h3 id="reauthentication">Reauthentication<a class="headerlink" href="#reauthentication" title="Permanent link">#</a></h3>
2160<p>For security sensitive processing, you might want to ensure that the account owner is actually present instead of a third party accessing a session that was accidentally left logged in.</p>
2161<p>WoltLab Suite 5.4 ships with a generic reauthentication framework.
2162To request reauthentication within your controller you need to:</p>
2163<ol>
2164<li>Use the <code>wcf\system\user\authentication\TReauthenticationCheck</code> trait.</li>
2165<li>Call:
2166 <div class="highlight"><pre><span></span><code><span class="nv">$this</span><span class="o">-&gt;</span><span class="na">requestReauthentication</span><span class="p">(</span><span class="nx">LinkHandler</span><span class="o">::</span><span class="na">getInstance</span><span class="p">()</span><span class="o">-&gt;</span><span class="na">getControllerLink</span><span class="p">(</span><span class="k">static</span><span class="o">::</span><span class="na">class</span><span class="p">,</span> <span class="p">[</span>
2167 <span class="cm">/* additional parameters */</span>
2168<span class="p">]));</span>
2169</code></pre></div></li>
2170</ol>
2171<p><code>requestReauthentication()</code> will check if the user has recently authenticated themselves.
2172If they did, the request proceeds as usual.
2173Otherwise, they will be asked to reauthenticate themselves.
2174After the successful authentication, they will be redirected to the URL that was passed as the first parameter (the current controller within the example).</p>
2175<p>Details can be found in <a href="https://github.com/WoltLab/WCF/pull/3775">WoltLab/WCF#3775</a>.</p>
2176<h3 id="multi-factor-authentication">Multi-factor Authentication<a class="headerlink" href="#multi-factor-authentication" title="Permanent link">#</a></h3>
2177<p>To implement multi-factor authentication securely, WoltLab Suite 5.4 implements the concept of a “pending user change”.
2178The user will not be logged in (i.e. <code>WCF::getUser()-&gt;userID</code> returns <code>null</code>) until they authenticate themselves with their second factor.</p>
2179<p>Requesting multi-factor authentication is done on an opt-in basis for compatibility reasons.
2180If you perform authentication yourself and do not trust the authentication source to perform multi-factor authentication itself, you will need to adjust your logic to request multi-factor authentication from WoltLab Suite:</p>
2181<p>Previously:</p>
2182<div class="highlight"><pre><span></span><code><span class="nx">WCF</span><span class="o">::</span><span class="na">getSession</span><span class="p">()</span><span class="o">-&gt;</span><span class="na">changeUser</span><span class="p">(</span><span class="nv">$targetUser</span><span class="p">);</span>
2183</code></pre></div>
2184
2185<p>Now:</p>
2186<div class="highlight"><pre><span></span><code><span class="nv">$isPending</span> <span class="o">=</span> <span class="nx">WCF</span><span class="o">::</span><span class="na">getSession</span><span class="p">()</span><span class="o">-&gt;</span><span class="na">changeUserAfterMultifactorAuthentication</span><span class="p">(</span><span class="nv">$targetUser</span><span class="p">);</span>
2187<span class="k">if</span> <span class="p">(</span><span class="nv">$isPending</span><span class="p">)</span> <span class="p">{</span>
2188 <span class="c1">// Redirect to the authentication form. The user will not be logged in.</span>
2189 <span class="c1">// Note: Do not use `getControllerLink` to support both the frontend as well as the ACP.</span>
2190 <span class="nx">HeaderUtil</span><span class="o">::</span><span class="na">redirect</span><span class="p">(</span><span class="nx">LinkHandler</span><span class="o">::</span><span class="na">getInstance</span><span class="p">()</span><span class="o">-&gt;</span><span class="na">getLink</span><span class="p">(</span><span class="s1">&#39;MultifactorAuthentication&#39;</span><span class="p">,</span> <span class="p">[</span>
2191 <span class="s1">&#39;url&#39;</span> <span class="o">=&gt;</span> <span class="cm">/* Return To */</span><span class="p">,</span>
2192 <span class="p">]));</span>
2193 <span class="k">exit</span><span class="p">;</span>
2194<span class="p">}</span>
2195<span class="c1">// Proceed as usual. The user will be logged in.</span>
2196</code></pre></div>
2197
2198<h4 id="adding-multi-factor-methods">Adding Multi-factor Methods<a class="headerlink" href="#adding-multi-factor-methods" title="Permanent link">#</a></h4>
2199<p>Adding your own multi-factor method requires the implementation of a single object type:</p>
2200<div class="highlight"><pre><span></span><code><span class="nt">&lt;type&gt;</span>
2201 <span class="nt">&lt;name&gt;</span>com.example.multifactor.foobar<span class="nt">&lt;/name&gt;</span>
2202 <span class="nt">&lt;definitionname&gt;</span>com.woltlab.wcf.multifactor<span class="nt">&lt;/definitionname&gt;</span>
2203 <span class="nt">&lt;icon&gt;</span><span class="c">&lt;!-- Font Awesome 4 Icon Name goes here. --&gt;</span><span class="nt">&lt;/icon&gt;</span>
2204 <span class="nt">&lt;priority&gt;</span><span class="c">&lt;!-- Determines the sort order, higher priority will be preferred for authentication. --&gt;</span><span class="nt">&lt;/priority&gt;</span>
2205 <span class="nt">&lt;classname&gt;</span>wcf\system\user\multifactor\FoobarMultifactorMethod<span class="nt">&lt;/classname&gt;</span>
2206<span class="nt">&lt;/type&gt;</span>
2207</code></pre></div>
2208
2209<p>The given classname must implement the <a href="https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/user/multifactor/IMultifactorMethod.class.php"><code>IMultifactorMethod</code></a> interface.</p>
2210<p>As a self-contained example, you can find the initial implementation of the email multi-factor method in <a href="https://github.com/WoltLab/WCF/pull/3729">WoltLab/WCF#3729</a>.
2211Please check <a href="https://github.com/WoltLab/WCF/commits/master/wcfsetup/install/files/lib/system/user/multifactor/EmailMultifactorMethod.class.php">the version history</a> of the PHP class to make sure you do not miss important changes that were added later.</p>
2212<div class="admonition warning">
2213<p class="admonition-title">Multi-factor authentication is security sensitive. Make sure to carefully read the remarks in <code>IMultifactorMethod</code> for possible issues. Also make sure to carefully test your implementation against all sorts of incorrect input and consider attack vectors such as race conditions. It is strongly recommended to generously check the current state by leveraging assertions and exceptions.</p>
2214</div>
2215<h2 id="deprecations-and-removals">Deprecations and Removals<a class="headerlink" href="#deprecations-and-removals" title="Permanent link">#</a></h2>
2216<h3 id="sessionhandler">SessionHandler<a class="headerlink" href="#sessionhandler" title="Permanent link">#</a></h3>
2217<p>Most of the changes with regard to the new session handling happened in <code>SessionHandler</code>.
2218Most notably, <code>SessionHandler</code> now is marked <code>final</code> to ensure proper encapsulation of data.</p>
2219<p>A number of methods in <code>SessionHandler</code> are now deprecated and result in a noop.
2220This change mostly affects methods that have been used to bootstrap the session, such as <code>setHasValidCookie()</code>.</p>
2221<p>Additionally, accessing the following keys on the session is deprecated.
2222They directly map to an existing method in another class and any uses can easily be updated:
2223- <code>ipAddress</code>
2224- <code>userAgent</code>
2225- <code>requestURI</code>
2226- <code>requestMethod</code>
2227- <code>lastActivityTime</code></p>
2228<p>Refer to <a href="https://github.com/WoltLab/WCF/blob/439de4963c947c3569a0c584f795245f693155b0/wcfsetup/install/files/lib/system/session/SessionHandler.class.php#L168-L178">the implementation</a> for details.</p>
2229<h3 id="acp-sessions">ACP Sessions<a class="headerlink" href="#acp-sessions" title="Permanent link">#</a></h3>
2230<p>The database tables related to ACP sessions have been removed.
2231The PHP classes have been preserved due to being used within the class hierarchy of the legacy sessions.</p>
2232<h3 id="cookies">Cookies<a class="headerlink" href="#cookies" title="Permanent link">#</a></h3>
2233<p>The <code>_userID</code>, <code>_password</code>, <code>_cookieHash</code> and <code>_cookieHash_acp</code> cookies will no longer be created nor consumed.</p>
2234<h3 id="virtual-sessions">Virtual Sessions<a class="headerlink" href="#virtual-sessions" title="Permanent link">#</a></h3>
2235<p>The virtual session logic existed to support multiple devices per single session in <code>wcf1_session</code>.
2236Virtual sessions are no longer required with the refactored session handling.</p>
2237<p>Anything related to virtual sessions has been completely removed as they are considered an implementation detail.
2238This removal includes PHP classes and database tables.</p>
2239<h3 id="security-token-constants">Security Token Constants<a class="headerlink" href="#security-token-constants" title="Permanent link">#</a></h3>
2240<p>The security token constants are deprecated.
2241Instead, the methods of <code>SessionHandler</code> should be used (e.g. <code>-&gt;getSecurityToken()</code>).
2242Within templates, you should migrate to the <code>{csrfToken}</code> tag in place of <code>{@SECURITY_TOKEN_INPUT_TAG}</code>.
2243The <code>{csrfToken}</code> tag is a drop-in replacement and was backported to WoltLab Suite 5.2+, allowing you to maintain compatibility across a broad range of versions.</p>
2244<h3 id="passwordutil-and-double-bcrypt-hashes">PasswordUtil and Double BCrypt Hashes<a class="headerlink" href="#passwordutil-and-double-bcrypt-hashes" title="Permanent link">#</a></h3>
2245<p>Most of the methods in PasswordUtil are deprecated in favor of the new password hashing framework.</p>
2246
2247
2248
2249
2250
2251
2252
2253 </article>
2254 </div>
2255 </div>
2256 </main>
2257
2258
2259<footer class="md-footer">
2260
2261 <nav class="md-footer__inner md-grid" aria-label="Footer">
2262
2263 <a href="../php/" class="md-footer__link md-footer__link--prev" rel="prev">
2264 <div class="md-footer__button md-icon">
2265 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12z"/></svg>
2266 </div>
2267 <div class="md-footer__title">
2268 <div class="md-ellipsis">
2269 <span class="md-footer__direction">
2270 Previous
2271 </span>
2272 PHP API
2273 </div>
2274 </div>
2275 </a>
2276
2277
2278 <a href="../javascript/" class="md-footer__link md-footer__link--next" rel="next">
2279 <div class="md-footer__title">
2280 <div class="md-ellipsis">
2281 <span class="md-footer__direction">
2282 Next
2283 </span>
2284 JavaScript
2285 </div>
2286 </div>
2287 <div class="md-footer__button md-icon">
2288 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11H4z"/></svg>
2289 </div>
2290 </a>
2291
2292 </nav>
2293
2294 <div class="md-footer-meta md-typeset">
2295 <div class="md-footer-meta__inner md-grid">
2296 <div class="md-footer-copyright">
2297
2298 <div class="md-footer-copyright__highlight">
2299 Copyright © 2020 WoltLab GmbH
2300 </div>
2301
2302 Made with
2303 <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
2304 Material for MkDocs
2305 </a>
2306 </div>
2307 <div class="md-footer-copyright">
2308 <a href="https://www.woltlab.com/legal-notice/">Legal Notice</a>
2309 <a href="https://www.woltlab.com/privacy-policy/">Privacy Policy</a>
2310</div>
2311 </div>
2312 </div>
2313</footer>
2314
2315 </div>
2316 <div class="md-dialog" data-md-component="dialog">
2317 <div class="md-dialog__inner md-typeset"></div>
2318 </div>
2319 <script id="__config" type="application/json">{"base": "../../..", "features": [], "translations": {"clipboard.copy": "Copy to clipboard", "clipboard.copied": "Copied to clipboard", "search.config.lang": "en", "search.config.pipeline": "trimmer, stopWordFilter", "search.config.separator": "[\\s\\-]+", "search.placeholder": "Search", "search.result.placeholder": "Type to start searching", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.term.missing": "Missing"}, "search": "../../../assets/javascripts/workers/search.fb4a9340.min.js", "version": {"provider": "mike"}}</script>
2320
2321
2322 <script src="../../../assets/javascripts/bundle.ca5457b8.min.js"></script>
2323
2324
2325 </body>
2326</html>