Wiki source code of XWiki Two-Factor Authentication

Version 28.1 by Alex Cotiuga on 2026/06/24 16:39

Manage
- Copy
Actions
- Export
- Print Preview
Viewers
- Source
- Siblings
- Content
- Comments
- Attachments (12)
- History
- Information
- Likes

version	line-number	content
1.18	1	{{velocity}}
	2	#set ($discard = $xwiki.ssx.use('PublicWebSite.WebHome'))
10.1	3
23.1	4	#set ($mainCapabilityItems = [{
24.1	5	'title': 'Second verification step',
23.1	6	'icon': 'key',
24.1	7	'content': 'Add an additional verification screen after the normal XWiki username and password login.'
10.1	8	},{
24.1	9	'title': 'Authenticator app codes',
23.1	10	'icon': 'mobile',
	11	'content': 'Let users verify access with time-based TOTP codes generated by authenticator applications.'
10.1	12	},{
23.1	13	'title': 'Recovery and trusted devices',
	14	'icon': 'shield',
	15	'content': 'Provide backup access with recovery codes and reduce repeated prompts on trusted browsers.'
10.1	16	}])
	17
23.1	18	#set ($adminExperienceItems = [{
25.2	19	'title': 'Rollout policy',
22.5	20	'icon': 'cog',
25.2	21	'content': 'Make additional verification optional at first or required for all users from the XWiki Administration section.'
10.1	22	},{
23.1	23	'title': 'Configuration options',
	24	'icon': 'sliders',
	25	'content': 'Set the authenticator issuer name, recovery-code count and trusted-device duration.'
10.1	26	},{
23.1	27	'title': 'Administration overview',
22.5	28	'icon': 'table',
25.2	29	'content': 'Review adoption with summary indicators and a filterable Live Data table.'
10.1	30	}])
	31
23.1	32	#set ($userExperienceItems = [{
22.5	33	'title': 'Self-service setup',
	34	'icon': 'qrcode',
25.2	35	'content': 'Users configure the second verification step from their profile by scanning a QR code or entering the setup key manually.'
10.1	36	},{
23.1	37	'title': 'Login verification',
	38	'icon': 'sign-in',
25.2	39	'content': 'After the normal login, users enter the verification code generated by their authenticator app.'
10.1	40	},{
22.5	41	'title': 'Trusted browser option',
	42	'icon': 'desktop',
	43	'content': 'Users can trust the current browser for the configured duration after successful verification.'
10.1	44	}])
	45
23.1	46	#set ($selfServiceItems = [{
	47	'title': 'Recovery codes',
22.5	48	'icon': 'life-ring',
23.1	49	'content': 'Recovery codes provide backup access when a user loses access to the authenticator application.'
10.1	50	},{
23.1	51	'title': 'Trusted devices',
	52	'icon': 'desktop',
	53	'content': 'Trusted devices can be reviewed and removed from the user profile.'
22.6	54	},{
23.1	55	'title': 'Profile management',
	56	'icon': 'user',
25.2	57	'content': 'Users can review status, generate recovery codes, manage trusted devices and reset their setup.'
10.1	58	}])
	59
22.3	60	#set ($adminSupportItems = [{
25.2	61	'title': 'User status',
22.5	62	'icon': 'user',
25.2	63	'content': 'Administrators can open a user profile and check the verification status for that account.'
22.3	64	},{
25.2	65	'title': 'Setup reset',
22.5	66	'icon': 'refresh',
25.2	67	'content': 'Administrators can reset the setup when a user needs to restart the configuration process.'
22.3	68	},{
23.1	69	'title': 'Controlled recovery',
	70	'icon': 'unlock-alt',
25.2	71	'content': 'Resetting the setup removes the authenticator configuration, recovery codes and trusted devices for that user.'
22.3	72	}])
	73
10.1	74	#set ($rolloutItems = [{
22.5	75	'title': 'Start with a pilot group',
	76	'content': 'Test the extension with administrators or a small user group before enabling it widely.'
10.1	77	},{
25.2	78	'title': 'Define the rollout policy',
	79	'content': 'Decide whether additional verification should be optional at first or required for all users.'
10.1	80	},{
22.5	81	'title': 'Configure recovery options',
	82	'content': 'Choose the number of recovery codes and whether trusted devices should be allowed.'
10.1	83	},{
23.1	84	'title': 'Inform users',
25.2	85	'content': 'Explain how users configure the authenticator app, save recovery codes and manage trusted devices.'
10.1	86	},{
22.5	87	'title': 'Monitor adoption',
25.2	88	'content': 'Use the administration overview to identify users who still need to configure protection.'
10.1	89	}])
	90
1.18	91	{{html clean="false"}}
1.2	92
10.1	93	<section class="hero hero-centered" aria-labelledby="product-title">
1.18	94	<div class="container hero-inner">
	95	<div class="hero-kicker">
1.2	96	<i class="fa fa-lock" aria-hidden="true"></i>
25.2	97	XWiki 2FA with MFA rollout support
1.2	98	</div>
	99
25.2	100	<h1 id="product-title">XWiki Two-Factor Authentication</h1>
1.2	101
22.5	102	<p class="lead">
25.2	103	Protect XWiki logins with authenticator app verification, recovery codes,
	104	trusted devices and administration controls for a safer rollout.
22.5	105	</p>
1.2	106
22.5	107	<div class="hero-actions">
	108	<a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Ask about this extension</a>
	109	<a class="btn btn-secondary" href="$xwiki.getURL('products.WebHome')">View all products</a>
	110	</div>
1.18	111	</div>
	112	</section>
	113
	114	<section aria-labelledby="overview-title">
	115	<div class="container">
	116	<div class="product-layout">
	117	<article class="product-summary-card">
24.1	118	<h2 id="overview-title">Two-factor authentication built into XWiki</h2>
1.18	119
22.5	120	<p>
25.2	121	XWiki Two-Factor Authentication adds an additional verification step to the standard
	122	XWiki login flow. Users continue to sign in with their normal username and password,
	123	then confirm access with a time-based code from an authenticator application.
22.5	124	</p>
1.18	125
22.5	126	<p>
25.3	127	The application has evolved beyond a simple login-code screen. It supports global
	128	enforcement, recovery codes, trusted devices, user self-service, administrator
	129	reset actions and an overview for monitoring adoption.
22.5	130	</p>
	131	</article>
1.18	132
22.5	133	<aside class="product-info-card" aria-labelledby="quick-facts-title">
	134	<h3 id="quick-facts-title">Quick facts</h3>
	135	<ul>
	136	<li>Works with the standard XWiki login flow</li>
23.1	137	<li>Supports TOTP authenticator applications</li>
25.2	138	<li>Can require additional verification for all users</li>
22.5	139	<li>Includes one-time recovery codes</li>
23.1	140	<li>Can remember trusted browsers or devices</li>
22.5	141	<li>Includes user self-service controls</li>
23.1	142	<li>Includes an administration overview</li>
22.5	143	</ul>
	144	</aside>
	145	</div>
1.18	146	</div>
	147	</section>
	148
23.1	149	<section aria-labelledby="capabilities-title">
1.18	150	<div class="container">
24.1	151	<h2 id="capabilities-title">Main capabilities</h2>
1.18	152
22.5	153	<p class="section-intro">
25.2	154	A focused set of authentication protection features for stronger XWiki account security
	155	without replacing the familiar login experience.
22.5	156	</p>
1.18	157
22.5	158	<div class="product-feature-grid">
23.1	159	#foreach ($entry in $mainCapabilityItems)
22.5	160	<article class="product-feature">
	161	<div class="card-heading">
	162	<div class="feature-icon">
	163	<i class="fa fa-$entry.icon" aria-hidden="true"></i>
	164	</div>
	165	<h3>$entry.title</h3>
	166	</div>
6.7	167
22.5	168	<p>$entry.content</p>
	169	</article>
	170	#end
	171	</div>
10.1	172	</div>
	173	</section>
	174
23.1	175	<section class="product-section-muted" aria-labelledby="security-title">
10.1	176	<div class="container">
23.1	177	<div class="product-layout">
	178	<article class="product-summary-card">
24.1	179	<h2 id="security-title">Useful for XWiki security and access protection</h2>
10.1	180
23.1	181	<p>
	182	Many organizations use XWiki to store internal documentation, procedures, operational
25.2	183	knowledge and business-critical information. Adding an additional authentication factor helps
23.1	184	reduce the risk of account compromise when a password is exposed or reused.
	185	</p>
1.18	186
23.1	187	<p>
	188	The extension is especially useful for protecting administrator accounts, remote users,
	189	private knowledge bases and customer or partner portals.
	190	</p>
	191	</article>
8.1	192
23.1	193	<aside class="product-info-card" aria-labelledby="use-cases-title">
	194	<h3 id="use-cases-title">Typical use cases</h3>
	195	<ul>
	196	<li>Administrator account protection</li>
	197	<li>Internal knowledge base security</li>
	198	<li>Private documentation platforms</li>
	199	<li>Remote user access protection</li>
	200	<li>Customer or partner portals</li>
23.4	201	<li>Security review, MFA rollout and compliance readiness</li>
23.1	202	</ul>
	203	</aside>
22.5	204	</div>
10.1	205	</div>
	206	</section>
	207
23.1	208	<section aria-labelledby="admin-experience-title">
10.1	209	<div class="container">
23.1	210	<h2 id="admin-experience-title">Administrator configuration and monitoring</h2>
10.1	211
22.5	212	<p class="section-intro">
25.2	213	Administrators can configure the policy, define recovery options and monitor adoption
	214	from the XWiki Administration section.
22.5	215	</p>
10.1	216
22.5	217	<div class="product-feature-grid">
23.1	218	#foreach ($entry in $adminExperienceItems)
22.5	219	<article class="product-feature">
	220	<div class="card-heading">
	221	<div class="feature-icon">
	222	<i class="fa fa-$entry.icon" aria-hidden="true"></i>
	223	</div>
	224	<h3>$entry.title</h3>
	225	</div>
1.18	226
22.5	227	<p>$entry.content</p>
	228	</article>
	229	#end
	230	</div>
10.1	231
	232	{{/html}}
	233
	234	{{gallery}}
23.1	235	[[image:mfa-admin-configuration.png]]
10.1	236	[[image:mfa-admin-overview.png]]
17.2	237	[[image:mfa-admin-full.png]]
10.1	238	{{/gallery}}
	239
	240	{{html clean="false"}}
	241
22.5	242	<p class="product-gallery-caption">
25.2	243	Administration screens for configuring the policy and reviewing adoption across users.
22.5	244	</p>
7.2	245	</div>
	246	</section>
	247
23.1	248	<section class="product-section-muted" aria-labelledby="user-experience-title">
6.11	249	<div class="container">
23.1	250	<h2 id="user-experience-title">User setup and login verification</h2>
10.1	251
22.5	252	<p class="section-intro">
25.2	253	Users can configure the authenticator app from their profile or during the enforced setup flow,
	254	then verify future logins with a generated code.
22.5	255	</p>
10.1	256
22.5	257	<div class="product-feature-grid">
23.1	258	#foreach ($entry in $userExperienceItems)
22.5	259	<article class="product-feature">
	260	<div class="card-heading">
	261	<div class="feature-icon">
	262	<i class="fa fa-$entry.icon" aria-hidden="true"></i>
	263	</div>
	264	<h3>$entry.title</h3>
	265	</div>
10.1	266
22.5	267	<p>$entry.content</p>
	268	</article>
	269	#end
	270	</div>
10.1	271
	272	{{/html}}
	273
	274	{{gallery}}
	275	[[image:mfa-user-setup-qr.png]]
15.2	276	[[image:mfa-login-verification-setup.png]]
	277	[[image:mfa-login-verification-code.png]]
10.1	278	{{/gallery}}
	279
	280	{{html clean="false"}}
	281
22.5	282	<p class="product-gallery-caption">
25.2	283	User setup, enforced configuration and login verification screens.
22.5	284	</p>
10.1	285	</div>
	286	</section>
	287
23.1	288	<section aria-labelledby="self-service-title">
10.1	289	<div class="container">
24.1	290	<h2 id="self-service-title">Recovery codes and trusted devices</h2>
10.1	291
22.5	292	<p class="section-intro">
23.1	293	Recovery codes and trusted devices help balance stronger access protection with a smoother user experience.
22.5	294	</p>
10.1	295
22.5	296	<div class="product-feature-grid">
23.1	297	#foreach ($entry in $selfServiceItems)
22.5	298	<article class="product-feature">
	299	<div class="card-heading">
	300	<div class="feature-icon">
	301	<i class="fa fa-$entry.icon" aria-hidden="true"></i>
	302	</div>
	303	<h3>$entry.title</h3>
	304	</div>
10.1	305
22.5	306	<p>$entry.content</p>
	307	</article>
	308	#end
	309	</div>
10.1	310
	311	{{/html}}
	312
	313	{{gallery}}
23.1	314	[[image:mfa-user-profile-overview.png]]
22.2	315	[[image:mfa-recovery-codes-not-generated.png]]
	316	[[image:mfa-recovery-codes-generated.png]]
10.1	317	[[image:mfa-trusted-devices.png]]
22.2	318	[[image:mfa-user-profile-full.png]]
10.1	319	{{/gallery}}
	320
	321	{{html clean="false"}}
	322
22.5	323	<p class="product-gallery-caption">
25.2	324	User profile screens for recovery codes, trusted devices and self-service management.
22.5	325	</p>
10.1	326	</div>
	327	</section>
	328
22.3	329	<section class="product-section-muted" aria-labelledby="admin-support-title">
10.1	330	<div class="container">
22.3	331	<h2 id="admin-support-title">Administrator support and user recovery</h2>
	332
22.5	333	<p class="section-intro">
25.2	334	Administrators can help users recover from lost devices or restart setup when needed.
22.5	335	</p>
22.3	336
22.5	337	<div class="product-feature-grid">
	338	#foreach ($entry in $adminSupportItems)
	339	<article class="product-feature">
	340	<div class="card-heading">
	341	<div class="feature-icon">
	342	<i class="fa fa-$entry.icon" aria-hidden="true"></i>
	343	</div>
	344	<h3>$entry.title</h3>
	345	</div>
22.3	346
22.5	347	<p>$entry.content</p>
	348	</article>
	349	#end
	350	</div>
22.3	351
	352	{{/html}}
	353
	354	{{gallery}}
	355	[[image:mfa-admin-user-management.png]]
	356	{{/gallery}}
	357
	358	{{html clean="false"}}
	359
22.5	360	<p class="product-gallery-caption">
25.2	361	Administrator view for checking and resetting a user setup.
22.5	362	</p>
22.3	363	</div>
	364	</section>
	365
25.2	366	<section aria-labelledby="faq-title">
22.3	367	<div class="container">
25.2	368	<h2 id="faq-title">Frequently asked questions</h2>
	369
	370	<p class="section-intro">
	371	Common questions about how the extension works, how users configure it and how administrators can manage rollout and recovery.
	372	</p>
	373
	374	<div class="resource-content">
	375	<details class="resource-faq-item">
	376	<summary>Does this extension replace the standard XWiki login?</summary>
	377	<p>
	378	No. Users still sign in with their normal XWiki username and password. The extension adds
	379	an additional verification step after the standard login check.
	380	</p>
	381	</details>
	382
	383	<details class="resource-faq-item">
	384	<summary>Which verification method is used?</summary>
	385	<p>
	386	Users verify access with time-based codes generated by an authenticator application.
	387	The setup page provides a QR code and a manual setup key.
	388	</p>
	389	</details>
	390
	391	<details class="resource-faq-item">
	392	<summary>Can the second verification step be required for all users?</summary>
	393	<p>
	394	Yes. Administrators can make the verification step optional or required for all users
	395	from the XWiki Administration section.
	396	</p>
	397	</details>
	398
	399	<details class="resource-faq-item">
	400	<summary>What happens if a user loses access to the authenticator app?</summary>
	401	<p>
	402	Recovery codes can provide backup access when enabled. Administrators can also reset
	403	the user setup so the configuration process can be restarted.
	404	</p>
	405	</details>
	406
	407	<details class="resource-faq-item">
	408	<summary>Can trusted browsers or devices be disabled?</summary>
	409	<p>
	410	Yes. Administrators can configure how long trusted devices remain valid. Setting the
	411	trusted-device duration to 0 disables this option.
	412	</p>
	413	</details>
	414
	415	<details class="resource-faq-item">
	416	<summary>Is this only a basic 2FA login-code screen?</summary>
	417	<p>
	418	No. The main login mechanism is two-factor authentication, but the application also includes
	419	features needed for a safer organization-wide rollout: enforcement policy, recovery codes,
	420	trusted devices, user self-service, administrator monitoring and administrator reset actions.
	421	</p>
	422	</details>
	423
	424	<details class="resource-faq-item">
	425	<summary>Is this enough for compliance on its own?</summary>
	426	<p>
	427	No. This extension provides an important access-protection control, but it should be part
	428	of a broader security and compliance approach that includes permissions, upgrades,
	429	infrastructure, monitoring and operational procedures.
	430	</p>
	431	</details>
	432	</div>
	433	</div>
	434	</section>
	435
	436	<section class="product-section-muted" aria-labelledby="rollout-title">
	437	<div class="container">
8.1	438	<div class="product-layout">
	439	<article class="product-summary-card">
24.1	440	<h2 id="rollout-title">Rollout recommendations</h2>
6.11	441
22.5	442	<p>
25.2	443	For a smooth rollout, start with a small administrator or pilot group before requiring
	444	the additional verification step for everyone. This helps validate the configuration,
	445	prepare user communication and reduce support issues.
22.5	446	</p>
6.11	447
22.5	448	<ol class="process-list">
	449	#foreach ($entry in $rolloutItems)
	450	<li>
	451	<strong>$entry.title</strong>
	452	$entry.content
	453	</li>
	454	#end
	455	</ol>
	456	</article>
6.11	457
22.5	458	<aside class="product-info-card" aria-labelledby="planning-title">
	459	<h3 id="planning-title">Useful information before installation</h3>
10.1	460
22.5	461	<p class="product-card-note">
	462	These details help evaluate compatibility, rollout scope and configuration options.
	463	</p>
8.1	464
22.5	465	<ul>
	466	<li>XWiki version</li>
	467	<li>Single wiki or wiki farm with subwikis</li>
	468	<li>Current authentication setup</li>
25.2	469	<li>Optional or required rollout policy</li>
22.5	470	<li>Trusted-device policy</li>
	471	<li>Recovery-code policy</li>
	472	<li>Rollout communication needs</li>
	473	</ul>
	474	</aside>
	475	</div>
7.2	476	</div>
	477	</section>
	478
1.18	479	<section class="cta-section" aria-labelledby="cta-title">
	480	<div class="container">
	481	<div class="cta-panel">
24.1	482	<h2 id="cta-title">Interested in using this extension?</h2>
10.1	483
22.5	484	<p>
25.2	485	Send a short message with your XWiki version, current authentication setup and rollout goal.
22.5	486	</p>
10.1	487
22.5	488	<a class="btn btn-primary" href="$xwiki.getURL('contact.WebHome')">Contact Agnease</a>
	489	</div>
1.18	490	</div>
	491	</section>
	492
	493	{{/html}}
	494	{{/velocity}}