3 <html lang=
"en" class=
"no-js">
7 <meta name=
"viewport" content=
"width=device-width,initial-scale=1">
12 <link rel=
"icon" href=
"../../../assets/default.favicon.ico">
13 <meta name=
"generator" content=
"mkdocs-1.1.2, mkdocs-material-7.1.0">
17 <title>Session Handling and Authentication - WoltLab Suite Documentation
</title>
21 <link rel=
"stylesheet" href=
"../../../assets/stylesheets/main.33e2939f.min.css">
24 <link rel=
"stylesheet" href=
"../../../assets/stylesheets/palette.ef6f36e2.min.css">
28 <meta name=
"theme-color" content=
"#009485">
38 <link rel=
"stylesheet" href=
"../../../stylesheets/extra.css">
52 <body dir=
"ltr" data-md-color-scheme=
"" data-md-color-primary=
"teal" data-md-color-accent=
"">
55 <script>function __prefix(e){return new URL(
"../../..",location).pathname+
"."+e}function __get(e,t=localStorage){return JSON.parse(t.getItem(__prefix(e)))}
</script>
57 <input class=
"md-toggle" data-md-toggle=
"drawer" type=
"checkbox" id=
"__drawer" autocomplete=
"off">
58 <input class=
"md-toggle" data-md-toggle=
"search" type=
"checkbox" id=
"__search" autocomplete=
"off">
59 <label class=
"md-overlay" for=
"__drawer"></label>
60 <div data-md-component=
"skip">
63 <a href=
"#migrating-from-wsc-53-session-handling-and-authentication" class=
"md-skip">
68 <div data-md-component=
"announce">
70 <aside class=
"md-announce">
71 <div class=
"md-announce__inner md-grid md-typeset">
73 <a href=
"https://www.woltlab.com">Back to
<strong>woltlab.com
</strong></a>
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" data-md-component=
"logo">
84 <img src=
"../../../assets/logo.png" alt=
"logo">
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>
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
97 <div class=
"md-header__topic" data-md-component=
"header-topic">
98 <span class=
"md-ellipsis">
100 Session Handling and Authentication
109 <label class=
"md-header__button md-icon" for=
"__search">
110 <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>
113 <div class=
"md-search" data-md-component=
"search" role=
"dialog">
114 <label class=
"md-search__overlay" for=
"__search"></label>
115 <div class=
"md-search__inner" role=
"search">
116 <form class=
"md-search__form" name=
"search">
117 <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
>
118 <label class=
"md-search__icon md-icon" for=
"__search">
119 <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>
120 <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 <button type=
"reset" class=
"md-search__icon md-icon" aria-label=
"Clear" tabindex=
"-1">
123 <svg xmlns=
"http://www.w3.org/2000/svg" viewBox=
"0 0 24 24"><path d=
"M19 6.41 17.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>
126 <div class=
"md-search__output">
127 <div class=
"md-search__scrollwrap" data-md-scrollfix
>
128 <div class=
"md-search-result" data-md-component=
"search-result">
129 <div class=
"md-search-result__meta">
132 <ol class=
"md-search-result__list"></ol>
140 <div class=
"md-header__source">
142 <a href=
"https://github.com/WoltLab/docs.woltlab.com/" title=
"Go to repository" class=
"md-source" data-md-component=
"source">
143 <div class=
"md-source__icon md-icon">
145 <svg xmlns=
"http://www.w3.org/2000/svg" viewBox=
"0 0 448 512"><path d=
"M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg>
147 <div class=
"md-source__repository">
156 <div class=
"md-container" data-md-component=
"container">
161 <main class=
"md-main" data-md-component=
"main">
162 <div class=
"md-main__inner md-grid">
166 <div class=
"md-sidebar md-sidebar--primary" data-md-component=
"sidebar" data-md-type=
"navigation" >
167 <div class=
"md-sidebar__scrollwrap">
168 <div class=
"md-sidebar__inner">
172 <nav class=
"md-nav md-nav--primary" aria-label=
"Navigation" data-md-level=
"0">
173 <label class=
"md-nav__title" for=
"__drawer">
174 <a href=
"../../.." title=
"WoltLab Suite Documentation" class=
"md-nav__button md-logo" aria-label=
"WoltLab Suite Documentation" data-md-component=
"logo">
176 <img src=
"../../../assets/logo.png" alt=
"logo">
179 WoltLab Suite Documentation
182 <div class=
"md-nav__source">
184 <a href=
"https://github.com/WoltLab/docs.woltlab.com/" title=
"Go to repository" class=
"md-source" data-md-component=
"source">
185 <div class=
"md-source__icon md-icon">
187 <svg xmlns=
"http://www.w3.org/2000/svg" viewBox=
"0 0 448 512"><path d=
"M439.55 236.05 244 40.45a28.87 28.87 0 0 0-40.81 0l-40.66 40.63 51.52 51.52c27.06-9.14 52.68 16.77 43.39 43.68l49.66 49.66c34.23-11.8 61.18 31 35.47 56.69-26.49 26.49-70.21-2.87-56-37.34L240.22 199v121.85c25.3 12.54 22.26 41.85 9.08 55a34.34 34.34 0 0 1-48.55 0c-17.57-17.6-11.07-46.91 11.25-56v-123c-20.8-8.51-24.6-30.74-18.64-45L142.57 101 8.45 235.14a28.86 28.86 0 0 0 0 40.81l195.61 195.6a28.86 28.86 0 0 0 40.8 0l194.69-194.69a28.86 28.86 0 0 0 0-40.81z"/></svg>
189 <div class=
"md-source__repository">
195 <ul class=
"md-nav__list" data-md-scrollfix
>
204 <li class=
"md-nav__item">
205 <a href=
"../../../getting-started/" class=
"md-nav__link">
220 <li class=
"md-nav__item md-nav__item--nested">
223 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_2" type=
"checkbox" id=
"__nav_2" >
225 <label class=
"md-nav__link" for=
"__nav_2">
227 <span class=
"md-nav__icon md-icon"></span>
229 <nav class=
"md-nav" aria-label=
"PHP API" data-md-level=
"1">
230 <label class=
"md-nav__title" for=
"__nav_2">
231 <span class=
"md-nav__icon md-icon"></span>
234 <ul class=
"md-nav__list" data-md-scrollfix
>
240 <li class=
"md-nav__item">
241 <a href=
"../../../php/pages/" class=
"md-nav__link">
252 <li class=
"md-nav__item">
253 <a href=
"../../../php/database-objects/" class=
"md-nav__link">
264 <li class=
"md-nav__item">
265 <a href=
"../../../php/database-access/" class=
"md-nav__link">
276 <li class=
"md-nav__item">
277 <a href=
"../../../php/exceptions/" class=
"md-nav__link">
289 <li class=
"md-nav__item md-nav__item--nested">
292 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_2_5" type=
"checkbox" id=
"__nav_2_5" >
294 <label class=
"md-nav__link" for=
"__nav_2_5">
296 <span class=
"md-nav__icon md-icon"></span>
298 <nav class=
"md-nav" aria-label=
"API" data-md-level=
"2">
299 <label class=
"md-nav__title" for=
"__nav_2_5">
300 <span class=
"md-nav__icon md-icon"></span>
303 <ul class=
"md-nav__list" data-md-scrollfix
>
310 <li class=
"md-nav__item md-nav__item--nested">
313 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_2_5_1" type=
"checkbox" id=
"__nav_2_5_1" >
315 <label class=
"md-nav__link" for=
"__nav_2_5_1">
317 <span class=
"md-nav__icon md-icon"></span>
319 <nav class=
"md-nav" aria-label=
"Caches" data-md-level=
"3">
320 <label class=
"md-nav__title" for=
"__nav_2_5_1">
321 <span class=
"md-nav__icon md-icon"></span>
324 <ul class=
"md-nav__list" data-md-scrollfix
>
330 <li class=
"md-nav__item">
331 <a href=
"../../../php/api/caches/" class=
"md-nav__link">
342 <li class=
"md-nav__item">
343 <a href=
"../../../php/api/caches_persistent-caches/" class=
"md-nav__link">
354 <li class=
"md-nav__item">
355 <a href=
"../../../php/api/caches_runtime-caches/" class=
"md-nav__link">
372 <li class=
"md-nav__item">
373 <a href=
"../../../php/api/comments/" class=
"md-nav__link">
384 <li class=
"md-nav__item">
385 <a href=
"../../../php/api/cronjobs/" class=
"md-nav__link">
396 <li class=
"md-nav__item">
397 <a href=
"../../../php/api/events/" class=
"md-nav__link">
409 <li class=
"md-nav__item md-nav__item--nested">
412 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_2_5_5" type=
"checkbox" id=
"__nav_2_5_5" >
414 <label class=
"md-nav__link" for=
"__nav_2_5_5">
416 <span class=
"md-nav__icon md-icon"></span>
418 <nav class=
"md-nav" aria-label=
"Form Builder" data-md-level=
"3">
419 <label class=
"md-nav__title" for=
"__nav_2_5_5">
420 <span class=
"md-nav__icon md-icon"></span>
423 <ul class=
"md-nav__list" data-md-scrollfix
>
429 <li class=
"md-nav__item">
430 <a href=
"../../../php/api/form_builder/overview/" class=
"md-nav__link">
441 <li class=
"md-nav__item">
442 <a href=
"../../../php/api/form_builder/structure/" class=
"md-nav__link">
453 <li class=
"md-nav__item">
454 <a href=
"../../../php/api/form_builder/form_fields/" class=
"md-nav__link">
465 <li class=
"md-nav__item">
466 <a href=
"../../../php/api/form_builder/validation_data/" class=
"md-nav__link">
477 <li class=
"md-nav__item">
478 <a href=
"../../../php/api/form_builder/dependencies/" class=
"md-nav__link">
495 <li class=
"md-nav__item">
496 <a href=
"../../../php/api/package_installation_plugins/" class=
"md-nav__link">
497 Package Installation Plugins
507 <li class=
"md-nav__item">
508 <a href=
"../../../php/api/user_activity_points/" class=
"md-nav__link">
519 <li class=
"md-nav__item">
520 <a href=
"../../../php/api/user_notifications/" class=
"md-nav__link">
531 <li class=
"md-nav__item">
532 <a href=
"../../../php/api/sitemaps/" class=
"md-nav__link">
549 <li class=
"md-nav__item">
550 <a href=
"../../../php/code-style/" class=
"md-nav__link">
561 <li class=
"md-nav__item">
562 <a href=
"../../../php/apps/" class=
"md-nav__link">
573 <li class=
"md-nav__item">
574 <a href=
"../../../php/gdpr/" class=
"md-nav__link">
595 <li class=
"md-nav__item md-nav__item--nested">
598 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_3" type=
"checkbox" id=
"__nav_3" >
600 <label class=
"md-nav__link" for=
"__nav_3">
601 Languages, Templates & CSS
602 <span class=
"md-nav__icon md-icon"></span>
604 <nav class=
"md-nav" aria-label=
"Languages, Templates & CSS" data-md-level=
"1">
605 <label class=
"md-nav__title" for=
"__nav_3">
606 <span class=
"md-nav__icon md-icon"></span>
607 Languages, Templates & CSS
609 <ul class=
"md-nav__list" data-md-scrollfix
>
615 <li class=
"md-nav__item">
616 <a href=
"../../../view/languages/" class=
"md-nav__link">
627 <li class=
"md-nav__item">
628 <a href=
"../../../view/templates/" class=
"md-nav__link">
639 <li class=
"md-nav__item">
640 <a href=
"../../../view/template-plugins/" class=
"md-nav__link">
651 <li class=
"md-nav__item">
652 <a href=
"../../../view/css/" class=
"md-nav__link">
673 <li class=
"md-nav__item md-nav__item--nested">
676 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_4" type=
"checkbox" id=
"__nav_4" >
678 <label class=
"md-nav__link" for=
"__nav_4">
679 TypeScript and JavaScript API
680 <span class=
"md-nav__icon md-icon"></span>
682 <nav class=
"md-nav" aria-label=
"TypeScript and JavaScript API" data-md-level=
"1">
683 <label class=
"md-nav__title" for=
"__nav_4">
684 <span class=
"md-nav__icon md-icon"></span>
685 TypeScript and JavaScript API
687 <ul class=
"md-nav__list" data-md-scrollfix
>
693 <li class=
"md-nav__item">
694 <a href=
"../../../javascript/general-usage/" class=
"md-nav__link">
705 <li class=
"md-nav__item">
706 <a href=
"../../../javascript/typescript/" class=
"md-nav__link">
718 <li class=
"md-nav__item md-nav__item--nested">
721 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_4_3" type=
"checkbox" id=
"__nav_4_3" >
723 <label class=
"md-nav__link" for=
"__nav_4_3">
725 <span class=
"md-nav__icon md-icon"></span>
727 <nav class=
"md-nav" aria-label=
"New API" data-md-level=
"2">
728 <label class=
"md-nav__title" for=
"__nav_4_3">
729 <span class=
"md-nav__icon md-icon"></span>
732 <ul class=
"md-nav__list" data-md-scrollfix
>
738 <li class=
"md-nav__item">
739 <a href=
"../../../javascript/new-api_writing-a-module/" class=
"md-nav__link">
750 <li class=
"md-nav__item">
751 <a href=
"../../../javascript/new-api_data-structures/" class=
"md-nav__link">
762 <li class=
"md-nav__item">
763 <a href=
"../../../javascript/new-api_core/" class=
"md-nav__link">
774 <li class=
"md-nav__item">
775 <a href=
"../../../javascript/new-api_dom/" class=
"md-nav__link">
786 <li class=
"md-nav__item">
787 <a href=
"../../../javascript/new-api_events/" class=
"md-nav__link">
798 <li class=
"md-nav__item">
799 <a href=
"../../../javascript/new-api_ajax/" class=
"md-nav__link">
810 <li class=
"md-nav__item">
811 <a href=
"../../../javascript/new-api_dialogs/" class=
"md-nav__link">
822 <li class=
"md-nav__item">
823 <a href=
"../../../javascript/new-api_browser/" class=
"md-nav__link">
824 Browser and Screen Sizes
834 <li class=
"md-nav__item">
835 <a href=
"../../../javascript/new-api_ui/" class=
"md-nav__link">
852 <li class=
"md-nav__item">
853 <a href=
"../../../javascript/legacy-api/" class=
"md-nav__link">
864 <li class=
"md-nav__item">
865 <a href=
"../../../javascript/helper-functions/" class=
"md-nav__link">
876 <li class=
"md-nav__item">
877 <a href=
"../../../javascript/code-snippets/" class=
"md-nav__link">
898 <li class=
"md-nav__item md-nav__item--nested">
901 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_5" type=
"checkbox" id=
"__nav_5" >
903 <label class=
"md-nav__link" for=
"__nav_5">
905 <span class=
"md-nav__icon md-icon"></span>
907 <nav class=
"md-nav" aria-label=
"Package Components" data-md-level=
"1">
908 <label class=
"md-nav__title" for=
"__nav_5">
909 <span class=
"md-nav__icon md-icon"></span>
912 <ul class=
"md-nav__list" data-md-scrollfix
>
918 <li class=
"md-nav__item">
919 <a href=
"../../../package/package-xml/" class=
"md-nav__link">
931 <li class=
"md-nav__item md-nav__item--nested">
934 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_5_2" type=
"checkbox" id=
"__nav_5_2" >
936 <label class=
"md-nav__link" for=
"__nav_5_2">
938 <span class=
"md-nav__icon md-icon"></span>
940 <nav class=
"md-nav" aria-label=
"PIPs" data-md-level=
"2">
941 <label class=
"md-nav__title" for=
"__nav_5_2">
942 <span class=
"md-nav__icon md-icon"></span>
945 <ul class=
"md-nav__list" data-md-scrollfix
>
951 <li class=
"md-nav__item">
952 <a href=
"../../../package/pip/" class=
"md-nav__link">
963 <li class=
"md-nav__item">
964 <a href=
"../../../package/pip/acl-option/" class=
"md-nav__link">
975 <li class=
"md-nav__item">
976 <a href=
"../../../package/pip/acp-menu/" class=
"md-nav__link">
987 <li class=
"md-nav__item">
988 <a href=
"../../../package/pip/acp-search-provider/" class=
"md-nav__link">
999 <li class=
"md-nav__item">
1000 <a href=
"../../../package/pip/acp-template/" class=
"md-nav__link">
1011 <li class=
"md-nav__item">
1012 <a href=
"../../../package/pip/bbcode/" class=
"md-nav__link">
1023 <li class=
"md-nav__item">
1024 <a href=
"../../../package/pip/box/" class=
"md-nav__link">
1035 <li class=
"md-nav__item">
1036 <a href=
"../../../package/pip/clipboard-action/" class=
"md-nav__link">
1047 <li class=
"md-nav__item">
1048 <a href=
"../../../package/pip/core-object/" class=
"md-nav__link">
1059 <li class=
"md-nav__item">
1060 <a href=
"../../../package/pip/cronjob/" class=
"md-nav__link">
1071 <li class=
"md-nav__item">
1072 <a href=
"../../../package/pip/database/" class=
"md-nav__link">
1083 <li class=
"md-nav__item">
1084 <a href=
"../../../package/pip/event-listener/" class=
"md-nav__link">
1095 <li class=
"md-nav__item">
1096 <a href=
"../../../package/pip/file/" class=
"md-nav__link">
1107 <li class=
"md-nav__item">
1108 <a href=
"../../../package/pip/language/" class=
"md-nav__link">
1119 <li class=
"md-nav__item">
1120 <a href=
"../../../package/pip/media-provider/" class=
"md-nav__link">
1131 <li class=
"md-nav__item">
1132 <a href=
"../../../package/pip/menu/" class=
"md-nav__link">
1143 <li class=
"md-nav__item">
1144 <a href=
"../../../package/pip/menu-item/" class=
"md-nav__link">
1155 <li class=
"md-nav__item">
1156 <a href=
"../../../package/pip/object-type/" class=
"md-nav__link">
1167 <li class=
"md-nav__item">
1168 <a href=
"../../../package/pip/object-type-definition/" class=
"md-nav__link">
1169 objectTypeDefinition
1179 <li class=
"md-nav__item">
1180 <a href=
"../../../package/pip/option/" class=
"md-nav__link">
1191 <li class=
"md-nav__item">
1192 <a href=
"../../../package/pip/page/" class=
"md-nav__link">
1203 <li class=
"md-nav__item">
1204 <a href=
"../../../package/pip/pip/" class=
"md-nav__link">
1215 <li class=
"md-nav__item">
1216 <a href=
"../../../package/pip/script/" class=
"md-nav__link">
1227 <li class=
"md-nav__item">
1228 <a href=
"../../../package/pip/smiley/" class=
"md-nav__link">
1239 <li class=
"md-nav__item">
1240 <a href=
"../../../package/pip/sql/" class=
"md-nav__link">
1251 <li class=
"md-nav__item">
1252 <a href=
"../../../package/pip/style/" class=
"md-nav__link">
1263 <li class=
"md-nav__item">
1264 <a href=
"../../../package/pip/template/" class=
"md-nav__link">
1275 <li class=
"md-nav__item">
1276 <a href=
"../../../package/pip/template-listener/" class=
"md-nav__link">
1287 <li class=
"md-nav__item">
1288 <a href=
"../../../package/pip/user-group-option/" class=
"md-nav__link">
1299 <li class=
"md-nav__item">
1300 <a href=
"../../../package/pip/user-menu/" class=
"md-nav__link">
1311 <li class=
"md-nav__item">
1312 <a href=
"../../../package/pip/user-notification-event/" class=
"md-nav__link">
1313 userNotificationEvent
1323 <li class=
"md-nav__item">
1324 <a href=
"../../../package/pip/user-option/" class=
"md-nav__link">
1335 <li class=
"md-nav__item">
1336 <a href=
"../../../package/pip/user-profile-menu/" class=
"md-nav__link">
1353 <li class=
"md-nav__item">
1354 <a href=
"../../../package/database-php-api/" class=
"md-nav__link">
1377 <li class=
"md-nav__item md-nav__item--active md-nav__item--nested">
1380 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_6" type=
"checkbox" id=
"__nav_6" checked
>
1382 <label class=
"md-nav__link" for=
"__nav_6">
1384 <span class=
"md-nav__icon md-icon"></span>
1386 <nav class=
"md-nav" aria-label=
"Migration" data-md-level=
"1">
1387 <label class=
"md-nav__title" for=
"__nav_6">
1388 <span class=
"md-nav__icon md-icon"></span>
1391 <ul class=
"md-nav__list" data-md-scrollfix
>
1400 <li class=
"md-nav__item md-nav__item--active md-nav__item--nested">
1403 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_6_1" type=
"checkbox" id=
"__nav_6_1" checked
>
1405 <label class=
"md-nav__link" for=
"__nav_6_1">
1406 Migrating from WSC
5.3
1407 <span class=
"md-nav__icon md-icon"></span>
1409 <nav class=
"md-nav" aria-label=
"Migrating from WSC 5.3" data-md-level=
"2">
1410 <label class=
"md-nav__title" for=
"__nav_6_1">
1411 <span class=
"md-nav__icon md-icon"></span>
1412 Migrating from WSC
5.3
1414 <ul class=
"md-nav__list" data-md-scrollfix
>
1420 <li class=
"md-nav__item">
1421 <a href=
"../php/" class=
"md-nav__link">
1434 <li class=
"md-nav__item md-nav__item--active">
1436 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"toc" type=
"checkbox" id=
"__toc">
1441 <label class=
"md-nav__link md-nav__link--active" for=
"__toc">
1442 Session Handling and Authentication
1443 <span class=
"md-nav__icon md-icon"></span>
1446 <a href=
"./" class=
"md-nav__link md-nav__link--active">
1447 Session Handling and Authentication
1451 <nav class=
"md-nav md-nav--secondary" aria-label=
"Table of contents">
1457 <label class=
"md-nav__title" for=
"__toc">
1458 <span class=
"md-nav__icon md-icon"></span>
1461 <ul class=
"md-nav__list" data-md-component=
"toc" data-md-scrollfix
>
1463 <li class=
"md-nav__item">
1464 <a href=
"#summary-and-concepts" class=
"md-nav__link">
1465 Summary and Concepts
1468 <nav class=
"md-nav" aria-label=
"Summary and Concepts">
1469 <ul class=
"md-nav__list">
1471 <li class=
"md-nav__item">
1472 <a href=
"#legacy-persistent-login" class=
"md-nav__link">
1473 Legacy Persistent Login
1478 <li class=
"md-nav__item">
1479 <a href=
"#multiple-sessions" class=
"md-nav__link">
1485 <li class=
"md-nav__item">
1486 <a href=
"#merged-acp-and-frontend-sessions" class=
"md-nav__link">
1487 Merged ACP and Frontend Sessions
1492 <li class=
"md-nav__item">
1493 <a href=
"#improved-authentication-and-reauthentication" class=
"md-nav__link">
1494 Improved Authentication and Reauthentication
1504 <li class=
"md-nav__item">
1505 <a href=
"#additions-and-changes" class=
"md-nav__link">
1506 Additions and Changes
1509 <nav class=
"md-nav" aria-label=
"Additions and Changes">
1510 <ul class=
"md-nav__list">
1512 <li class=
"md-nav__item">
1513 <a href=
"#password-hashing" class=
"md-nav__link">
1519 <li class=
"md-nav__item">
1520 <a href=
"#session-storage" class=
"md-nav__link">
1526 <li class=
"md-nav__item">
1527 <a href=
"#reauthentication" class=
"md-nav__link">
1533 <li class=
"md-nav__item">
1534 <a href=
"#multi-factor-authentication" class=
"md-nav__link">
1535 Multi-factor Authentication
1538 <nav class=
"md-nav" aria-label=
"Multi-factor Authentication">
1539 <ul class=
"md-nav__list">
1541 <li class=
"md-nav__item">
1542 <a href=
"#adding-multi-factor-methods" class=
"md-nav__link">
1543 Adding Multi-factor Methods
1558 <li class=
"md-nav__item">
1559 <a href=
"#deprecations-and-removals" class=
"md-nav__link">
1560 Deprecations and Removals
1563 <nav class=
"md-nav" aria-label=
"Deprecations and Removals">
1564 <ul class=
"md-nav__list">
1566 <li class=
"md-nav__item">
1567 <a href=
"#sessionhandler" class=
"md-nav__link">
1573 <li class=
"md-nav__item">
1574 <a href=
"#acp-sessions" class=
"md-nav__link">
1580 <li class=
"md-nav__item">
1581 <a href=
"#cookies" class=
"md-nav__link">
1587 <li class=
"md-nav__item">
1588 <a href=
"#virtual-sessions" class=
"md-nav__link">
1594 <li class=
"md-nav__item">
1595 <a href=
"#security-token-constants" class=
"md-nav__link">
1596 Security Token Constants
1601 <li class=
"md-nav__item">
1602 <a href=
"#passwordutil-and-double-bcrypt-hashes" class=
"md-nav__link">
1603 PasswordUtil and Double BCrypt Hashes
1625 <li class=
"md-nav__item">
1626 <a href=
"../javascript/" class=
"md-nav__link">
1627 TypeScript and JavaScript
1637 <li class=
"md-nav__item">
1638 <a href=
"../templates/" class=
"md-nav__link">
1649 <li class=
"md-nav__item">
1650 <a href=
"../libraries/" class=
"md-nav__link">
1651 Third Party Libraries
1668 <li class=
"md-nav__item md-nav__item--nested">
1671 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_6_2" type=
"checkbox" id=
"__nav_6_2" >
1673 <label class=
"md-nav__link" for=
"__nav_6_2">
1674 Migrating from WSC
5.2
1675 <span class=
"md-nav__icon md-icon"></span>
1677 <nav class=
"md-nav" aria-label=
"Migrating from WSC 5.2" data-md-level=
"2">
1678 <label class=
"md-nav__title" for=
"__nav_6_2">
1679 <span class=
"md-nav__icon md-icon"></span>
1680 Migrating from WSC
5.2
1682 <ul class=
"md-nav__list" data-md-scrollfix
>
1688 <li class=
"md-nav__item">
1689 <a href=
"../../wsc52/php/" class=
"md-nav__link">
1700 <li class=
"md-nav__item">
1701 <a href=
"../../wsc52/templates/" class=
"md-nav__link">
1702 Templates and Languages
1712 <li class=
"md-nav__item">
1713 <a href=
"../../wsc52/libraries/" class=
"md-nav__link">
1714 Third Party Libraries
1731 <li class=
"md-nav__item md-nav__item--nested">
1734 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_6_3" type=
"checkbox" id=
"__nav_6_3" >
1736 <label class=
"md-nav__link" for=
"__nav_6_3">
1737 Migrating from WSC
3.1
1738 <span class=
"md-nav__icon md-icon"></span>
1740 <nav class=
"md-nav" aria-label=
"Migrating from WSC 3.1" data-md-level=
"2">
1741 <label class=
"md-nav__title" for=
"__nav_6_3">
1742 <span class=
"md-nav__icon md-icon"></span>
1743 Migrating from WSC
3.1
1745 <ul class=
"md-nav__list" data-md-scrollfix
>
1751 <li class=
"md-nav__item">
1752 <a href=
"../../wsc31/php/" class=
"md-nav__link">
1770 <li class=
"md-nav__item md-nav__item--nested">
1773 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_6_4" type=
"checkbox" id=
"__nav_6_4" >
1775 <label class=
"md-nav__link" for=
"__nav_6_4">
1776 Migrating from WSC
3.0
1777 <span class=
"md-nav__icon md-icon"></span>
1779 <nav class=
"md-nav" aria-label=
"Migrating from WSC 3.0" data-md-level=
"2">
1780 <label class=
"md-nav__title" for=
"__nav_6_4">
1781 <span class=
"md-nav__icon md-icon"></span>
1782 Migrating from WSC
3.0
1784 <ul class=
"md-nav__list" data-md-scrollfix
>
1790 <li class=
"md-nav__item">
1791 <a href=
"../../wsc30/php/" class=
"md-nav__link">
1802 <li class=
"md-nav__item">
1803 <a href=
"../../wsc30/javascript/" class=
"md-nav__link">
1814 <li class=
"md-nav__item">
1815 <a href=
"../../wsc30/templates/" class=
"md-nav__link">
1826 <li class=
"md-nav__item">
1827 <a href=
"../../wsc30/css/" class=
"md-nav__link">
1838 <li class=
"md-nav__item">
1839 <a href=
"../../wsc30/package/" class=
"md-nav__link">
1857 <li class=
"md-nav__item md-nav__item--nested">
1860 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_6_5" type=
"checkbox" id=
"__nav_6_5" >
1862 <label class=
"md-nav__link" for=
"__nav_6_5">
1863 Migrating from WCF
2.1
1864 <span class=
"md-nav__icon md-icon"></span>
1866 <nav class=
"md-nav" aria-label=
"Migrating from WCF 2.1" data-md-level=
"2">
1867 <label class=
"md-nav__title" for=
"__nav_6_5">
1868 <span class=
"md-nav__icon md-icon"></span>
1869 Migrating from WCF
2.1
1871 <ul class=
"md-nav__list" data-md-scrollfix
>
1877 <li class=
"md-nav__item">
1878 <a href=
"../../wcf21/php/" class=
"md-nav__link">
1889 <li class=
"md-nav__item">
1890 <a href=
"../../wcf21/templates/" class=
"md-nav__link">
1901 <li class=
"md-nav__item">
1902 <a href=
"../../wcf21/css/" class=
"md-nav__link">
1913 <li class=
"md-nav__item">
1914 <a href=
"../../wcf21/package/" class=
"md-nav__link">
1941 <li class=
"md-nav__item md-nav__item--nested">
1944 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_7" type=
"checkbox" id=
"__nav_7" >
1946 <label class=
"md-nav__link" for=
"__nav_7">
1948 <span class=
"md-nav__icon md-icon"></span>
1950 <nav class=
"md-nav" aria-label=
"Tutorials" data-md-level=
"1">
1951 <label class=
"md-nav__title" for=
"__nav_7">
1952 <span class=
"md-nav__icon md-icon"></span>
1955 <ul class=
"md-nav__list" data-md-scrollfix
>
1962 <li class=
"md-nav__item md-nav__item--nested">
1965 <input class=
"md-nav__toggle md-toggle" data-md-toggle=
"__nav_7_1" type=
"checkbox" id=
"__nav_7_1" >
1967 <label class=
"md-nav__link" for=
"__nav_7_1">
1969 <span class=
"md-nav__icon md-icon"></span>
1971 <nav class=
"md-nav" aria-label=
"Tutorial Series" data-md-level=
"2">
1972 <label class=
"md-nav__title" for=
"__nav_7_1">
1973 <span class=
"md-nav__icon md-icon"></span>
1976 <ul class=
"md-nav__list" data-md-scrollfix
>
1982 <li class=
"md-nav__item">
1983 <a href=
"../../../tutorial/series/overview/" class=
"md-nav__link">
1994 <li class=
"md-nav__item">
1995 <a href=
"../../../tutorial/series/part_1/" class=
"md-nav__link">
2006 <li class=
"md-nav__item">
2007 <a href=
"../../../tutorial/series/part_2/" class=
"md-nav__link">
2018 <li class=
"md-nav__item">
2019 <a href=
"../../../tutorial/series/part_3/" class=
"md-nav__link">
2046 <div class=
"md-sidebar md-sidebar--secondary" data-md-component=
"sidebar" data-md-type=
"toc" >
2047 <div class=
"md-sidebar__scrollwrap">
2048 <div class=
"md-sidebar__inner">
2050 <nav class=
"md-nav md-nav--secondary" aria-label=
"Table of contents">
2056 <label class=
"md-nav__title" for=
"__toc">
2057 <span class=
"md-nav__icon md-icon"></span>
2060 <ul class=
"md-nav__list" data-md-component=
"toc" data-md-scrollfix
>
2062 <li class=
"md-nav__item">
2063 <a href=
"#summary-and-concepts" class=
"md-nav__link">
2064 Summary and Concepts
2067 <nav class=
"md-nav" aria-label=
"Summary and Concepts">
2068 <ul class=
"md-nav__list">
2070 <li class=
"md-nav__item">
2071 <a href=
"#legacy-persistent-login" class=
"md-nav__link">
2072 Legacy Persistent Login
2077 <li class=
"md-nav__item">
2078 <a href=
"#multiple-sessions" class=
"md-nav__link">
2084 <li class=
"md-nav__item">
2085 <a href=
"#merged-acp-and-frontend-sessions" class=
"md-nav__link">
2086 Merged ACP and Frontend Sessions
2091 <li class=
"md-nav__item">
2092 <a href=
"#improved-authentication-and-reauthentication" class=
"md-nav__link">
2093 Improved Authentication and Reauthentication
2103 <li class=
"md-nav__item">
2104 <a href=
"#additions-and-changes" class=
"md-nav__link">
2105 Additions and Changes
2108 <nav class=
"md-nav" aria-label=
"Additions and Changes">
2109 <ul class=
"md-nav__list">
2111 <li class=
"md-nav__item">
2112 <a href=
"#password-hashing" class=
"md-nav__link">
2118 <li class=
"md-nav__item">
2119 <a href=
"#session-storage" class=
"md-nav__link">
2125 <li class=
"md-nav__item">
2126 <a href=
"#reauthentication" class=
"md-nav__link">
2132 <li class=
"md-nav__item">
2133 <a href=
"#multi-factor-authentication" class=
"md-nav__link">
2134 Multi-factor Authentication
2137 <nav class=
"md-nav" aria-label=
"Multi-factor Authentication">
2138 <ul class=
"md-nav__list">
2140 <li class=
"md-nav__item">
2141 <a href=
"#adding-multi-factor-methods" class=
"md-nav__link">
2142 Adding Multi-factor Methods
2157 <li class=
"md-nav__item">
2158 <a href=
"#deprecations-and-removals" class=
"md-nav__link">
2159 Deprecations and Removals
2162 <nav class=
"md-nav" aria-label=
"Deprecations and Removals">
2163 <ul class=
"md-nav__list">
2165 <li class=
"md-nav__item">
2166 <a href=
"#sessionhandler" class=
"md-nav__link">
2172 <li class=
"md-nav__item">
2173 <a href=
"#acp-sessions" class=
"md-nav__link">
2179 <li class=
"md-nav__item">
2180 <a href=
"#cookies" class=
"md-nav__link">
2186 <li class=
"md-nav__item">
2187 <a href=
"#virtual-sessions" class=
"md-nav__link">
2193 <li class=
"md-nav__item">
2194 <a href=
"#security-token-constants" class=
"md-nav__link">
2195 Security Token Constants
2200 <li class=
"md-nav__item">
2201 <a href=
"#passwordutil-and-double-bcrypt-hashes" class=
"md-nav__link">
2202 PasswordUtil and Double BCrypt Hashes
2220 <div class=
"md-content" data-md-component=
"content">
2221 <article class=
"md-content__inner md-typeset">
2224 <a href=
"https://github.com/WoltLab/docs.woltlab.com/edit/5.4/docs/migration/wsc53/session.md" title=
"Edit this page" class=
"md-content__button md-icon">
2225 <svg xmlns=
"http://www.w3.org/2000/svg" viewBox=
"0 0 24 24"><path d=
"M20.71 7.04c.39-.39.39-1.04 0-1.41l-2.34-2.34c-.37-.39-1.02-.39-1.41 0l-1.84 1.83 3.75 3.75M3 17.25V21h3.75L17.81 9.93l-3.75-3.75L3 17.25z"/></svg>
2229 <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>
2230 <p>WoltLab Suite
5.4 includes a completely refactored session handling.
2231 As 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>
2232 <p>You might appreciate some of the new session methods if you process security sensitive data.
</p>
2233 <h2 id=
"summary-and-concepts">Summary and Concepts
<a class=
"headerlink" href=
"#summary-and-concepts" title=
"Permanent link">#
</a></h2>
2234 <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.
2235 Both aspects are related to each other.
</p>
2236 <h3 id=
"legacy-persistent-login">Legacy Persistent Login
<a class=
"headerlink" href=
"#legacy-persistent-login" title=
"Permanent link">#
</a></h3>
2237 <p>The legacy persistent login was rather an automated login.
2238 Upon 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.
2239 If 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>
2240 <p>This legacy persistent login was completely removed.
2241 Instead, any sessions that belong to an authenticated user will automatically be long-lived.
2242 These 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>
2243 <h3 id=
"multiple-sessions">Multiple Sessions
<a class=
"headerlink" href=
"#multiple-sessions" title=
"Permanent link">#
</a></h3>
2244 <p>To allow for a proper separation of these long-lived user sessions, WoltLab Suite now allows for multiple sessions per user.
2245 These sessions are completely unrelated to each other.
2246 Specifically, they do not share session variables and they expire independently.
</p>
2247 <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.
2248 It no longer stores any private session data.
</p>
2249 <p>The actual sessions storing security sensitive information are in an unrelated location.
2250 They must only be accessed via the PHP API exposed by the
<code>SessionHandler
</code>.
</p>
2251 <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>
2252 <p>WoltLab Suite
5.4 shares a single session across both the frontend, as well as the ACP.
2253 When a user logs in to the frontend, they will also be logged into the ACP and vice versa.
</p>
2254 <p>Actual access to the ACP is controlled via the new
<a href=
"#reauthentication">reauthentication mechanism
</a>.
</p>
2255 <p>The session variable store is scoped:
2256 Session variables set within the frontend are not available within the ACP and vice versa.
</p>
2257 <h3 id=
"improved-authentication-and-reauthentication">Improved Authentication and Reauthentication
<a class=
"headerlink" href=
"#improved-authentication-and-reauthentication" title=
"Permanent link">#
</a></h3>
2258 <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>
2259 <h2 id=
"additions-and-changes">Additions and Changes
<a class=
"headerlink" href=
"#additions-and-changes" title=
"Permanent link">#
</a></h2>
2260 <h3 id=
"password-hashing">Password Hashing
<a class=
"headerlink" href=
"#password-hashing" title=
"Permanent link">#
</a></h3>
2261 <p>WoltLab Suite
5.4 includes a new object-oriented password hashing framework that is modeled after PHP’s
<code>password_*
</code> API.
2262 Check
<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>
2263 <p>The new default password hash is a standard BCrypt hash.
2264 All newly generated hashes in
<code>wcf1_user.password
</code> will now include a type prefix, instead of just passwords imported from other systems.
</p>
2265 <h3 id=
"session-storage">Session Storage
<a class=
"headerlink" href=
"#session-storage" title=
"Permanent link">#
</a></h3>
2266 <p>The
<code>wcf1_session
</code> table will no longer be used for session storage.
2267 Instead, it is maintained for compatibility with existing online lists.
</p>
2268 <p>The actual session storage is considered an implementation detail and you
<em>must not
</em> directly interact with the session tables.
2269 Future versions might support alternative session backends, such as Redis.
</p>
2270 <div class=
"admonition warning">
2271 <p class=
"admonition-title">Do not interact directly with the session database tables but only via the
<code>SessionHandler
</code> class!
</p>
2273 <h3 id=
"reauthentication">Reauthentication
<a class=
"headerlink" href=
"#reauthentication" title=
"Permanent link">#
</a></h3>
2274 <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>
2275 <p>WoltLab Suite
5.4 ships with a generic reauthentication framework.
2276 To request reauthentication within your controller you need to:
</p>
2278 <li>Use the
<code>wcf\system\user\authentication\TReauthenticationCheck
</code> trait.
</li>
2280 <div class=
"highlight"><pre><span></span><code><span class=
"nv">$this
</span><span class=
"o">-
></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">-
></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>
2281 <span class=
"cm">/* additional parameters */
</span>
2282 <span class=
"p">]));
</span>
2283 </code></pre></div></li>
2285 <p><code>requestReauthentication()
</code> will check if the user has recently authenticated themselves.
2286 If they did, the request proceeds as usual.
2287 Otherwise, they will be asked to reauthenticate themselves.
2288 After the successful authentication, they will be redirected to the URL that was passed as the first parameter (the current controller within the example).
</p>
2289 <p>Details can be found in
<a href=
"https://github.com/WoltLab/WCF/pull/3775">WoltLab/WCF#
3775</a>.
</p>
2290 <h3 id=
"multi-factor-authentication">Multi-factor Authentication
<a class=
"headerlink" href=
"#multi-factor-authentication" title=
"Permanent link">#
</a></h3>
2291 <p>To implement multi-factor authentication securely, WoltLab Suite
5.4 implements the concept of a “pending user change”.
2292 The user will not be logged in (i.e.
<code>WCF::getUser()-
>userID
</code> returns
<code>null
</code>) until they authenticate themselves with their second factor.
</p>
2293 <p>Requesting multi-factor authentication is done on an opt-in basis for compatibility reasons.
2294 If 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>
2296 <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">-
></span><span class=
"na">changeUser
</span><span class=
"p">(
</span><span class=
"nv">$targetUser
</span><span class=
"p">);
</span>
2299 <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">-
></span><span class=
"na">changeUserAfterMultifactorAuthentication
</span><span class=
"p">(
</span><span class=
"nv">$targetUser
</span><span class=
"p">);
</span>
2300 <span class=
"k">if
</span> <span class=
"p">(
</span><span class=
"nv">$isPending
</span><span class=
"p">)
</span> <span class=
"p">{
</span>
2301 <span class=
"c1">// Redirect to the authentication form. The user will not be logged in.
</span>
2302 <span class=
"c1">// Note: Do not use `getControllerLink` to support both the frontend as well as the ACP.
</span>
2303 <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">-
></span><span class=
"na">getLink
</span><span class=
"p">(
</span><span class=
"s1">'MultifactorAuthentication
'</span><span class=
"p">,
</span> <span class=
"p">[
</span>
2304 <span class=
"s1">'url
'</span> <span class=
"o">=
></span> <span class=
"cm">/* Return To */
</span><span class=
"p">,
</span>
2305 <span class=
"p">]));
</span>
2306 <span class=
"k">exit
</span><span class=
"p">;
</span>
2307 <span class=
"p">}
</span>
2308 <span class=
"c1">// Proceed as usual. The user will be logged in.
</span>
2310 <h4 id=
"adding-multi-factor-methods">Adding Multi-factor Methods
<a class=
"headerlink" href=
"#adding-multi-factor-methods" title=
"Permanent link">#
</a></h4>
2311 <p>Adding your own multi-factor method requires the implementation of a single object type:
</p>
2312 <div class=
"highlight"><pre><span></span><code><span class=
"nt"><type
></span>
2313 <span class=
"nt"><name
></span>com.example.multifactor.foobar
<span class=
"nt"></name
></span>
2314 <span class=
"nt"><definitionname
></span>com.woltlab.wcf.multifactor
<span class=
"nt"></definitionname
></span>
2315 <span class=
"nt"><icon
></span><span class=
"c"><!-- Font Awesome
4 Icon Name goes here. --
></span><span class=
"nt"></icon
></span>
2316 <span class=
"nt"><priority
></span><span class=
"c"><!-- Determines the sort order, higher priority will be preferred for authentication. --
></span><span class=
"nt"></priority
></span>
2317 <span class=
"nt"><classname
></span>wcf\system\user\multifactor\FoobarMultifactorMethod
<span class=
"nt"></classname
></span>
2318 <span class=
"nt"></type
></span>
2320 <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>
2321 <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>.
2322 Please 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>
2323 <div class=
"admonition warning">
2324 <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>
2326 <h2 id=
"deprecations-and-removals">Deprecations and Removals
<a class=
"headerlink" href=
"#deprecations-and-removals" title=
"Permanent link">#
</a></h2>
2327 <h3 id=
"sessionhandler">SessionHandler
<a class=
"headerlink" href=
"#sessionhandler" title=
"Permanent link">#
</a></h3>
2328 <p>Most of the changes with regard to the new session handling happened in
<code>SessionHandler
</code>.
2329 Most notably,
<code>SessionHandler
</code> now is marked
<code>final
</code> to ensure proper encapsulation of data.
</p>
2330 <p>A number of methods in
<code>SessionHandler
</code> are now deprecated and result in a noop.
2331 This change mostly affects methods that have been used to bootstrap the session, such as
<code>setHasValidCookie()
</code>.
</p>
2332 <p>Additionally, accessing the following keys on the session is deprecated.
2333 They directly map to an existing method in another class and any uses can easily be updated:
2334 -
<code>ipAddress
</code>
2335 -
<code>userAgent
</code>
2336 -
<code>requestURI
</code>
2337 -
<code>requestMethod
</code>
2338 -
<code>lastActivityTime
</code></p>
2339 <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>
2340 <h3 id=
"acp-sessions">ACP Sessions
<a class=
"headerlink" href=
"#acp-sessions" title=
"Permanent link">#
</a></h3>
2341 <p>The database tables related to ACP sessions have been removed.
2342 The PHP classes have been preserved due to being used within the class hierarchy of the legacy sessions.
</p>
2343 <h3 id=
"cookies">Cookies
<a class=
"headerlink" href=
"#cookies" title=
"Permanent link">#
</a></h3>
2344 <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>
2345 <h3 id=
"virtual-sessions">Virtual Sessions
<a class=
"headerlink" href=
"#virtual-sessions" title=
"Permanent link">#
</a></h3>
2346 <p>The virtual session logic existed to support multiple devices per single session in
<code>wcf1_session
</code>.
2347 Virtual sessions are no longer required with the refactored session handling.
</p>
2348 <p>Anything related to virtual sessions has been completely removed as they are considered an implementation detail.
2349 This removal includes PHP classes and database tables.
</p>
2350 <h3 id=
"security-token-constants">Security Token Constants
<a class=
"headerlink" href=
"#security-token-constants" title=
"Permanent link">#
</a></h3>
2351 <p>The security token constants are deprecated.
2352 Instead, the methods of
<code>SessionHandler
</code> should be used (e.g.
<code>-
>getSecurityToken()
</code>).
2353 Within templates, you should migrate to the
<code>{csrfToken}
</code> tag in place of
<code>{@SECURITY_TOKEN_INPUT_TAG}
</code>.
2354 The
<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>
2355 <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>
2356 <p>Most of the methods in PasswordUtil are deprecated in favor of the new password hashing framework.
</p>
2362 <div class=
"md-source-date">
2365 Last update:
2021-
02-
11
2384 <footer class=
"md-footer">
2386 <nav class=
"md-footer__inner md-grid" aria-label=
"Footer">
2388 <a href=
"../php/" class=
"md-footer__link md-footer__link--prev" rel=
"prev">
2389 <div class=
"md-footer__button md-icon">
2390 <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>
2392 <div class=
"md-footer__title">
2393 <div class=
"md-ellipsis">
2394 <span class=
"md-footer__direction">
2403 <a href=
"../javascript/" class=
"md-footer__link md-footer__link--next" rel=
"next">
2404 <div class=
"md-footer__title">
2405 <div class=
"md-ellipsis">
2406 <span class=
"md-footer__direction">
2409 TypeScript and JavaScript
2412 <div class=
"md-footer__button md-icon">
2413 <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>
2419 <div class=
"md-footer-meta md-typeset">
2420 <div class=
"md-footer-meta__inner md-grid">
2421 <div class=
"md-footer-copyright">
2423 <div class=
"md-footer-copyright__highlight">
2424 Copyright ©
2020 WoltLab GmbH
2428 <a href=
"https://squidfunk.github.io/mkdocs-material/" target=
"_blank" rel=
"noopener">
2433 <div class=
"md-footer-copyright">
2434 <a href=
"https://www.woltlab.com/legal-notice/">Legal Notice
</a>
2435 <a href=
"https://www.woltlab.com/privacy-policy/">Privacy Policy
</a>
2442 <div class=
"md-dialog" data-md-component=
"dialog">
2443 <div class=
"md-dialog__inner md-typeset"></div>
2445 <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.fe42c31b.min.js",
"version": {
"provider":
"mike"}}
</script>
2448 <script src=
"../../../assets/javascripts/bundle.d892486b.min.js"></script>