Skip to Content

Published

Convert the User Authentication documentation into the documentation tree

Last modified by Eleni Cojocariu on 2026/08/08 00:48

Conversion of Documentation.AdminGuide.Authentication (revision 127.1) into documentation.xs.admin.authentication, following the Documentation Guide. Authentication had no page in the new tree yet, so this is a new topic beside rights and user.

The legacy page was one long page mixing every Diataxis type, so it becomes a hub plus seven pages: two References (types, parameters) and five How-tos (select-authenticator, configure-container, set-groovy-authenticator, configure-kerberos-sso, customize-mail-templates).

Content that was checked against the sources on master and against a running XWiki 17.10.11, and corrected:

  • default_page does not exist: XWikiAuthServiceImpl reads xwiki.authentication.defaultpage.
  • cookieprefix was missing from the parameters table.
  • The encryption and validation keys are no longer mandatory — they are generated and stored when left empty.
  • The administration path is "Administration > Users & Rights > Authentication", not "Administration > Authentication".
  • The Kerberos warning was stale: AppServerTrustedKerberosAuthServiceImpl is part of xwiki-platform-oldcore, so no authkerb.jar has to be copied into WEB-INF/lib. Kerberos also needs createuser=empty, which the legacy page only mentioned for Container authentication.
  • The Groovy authenticator requires programming rights on the page holding the code, and reads its page name from a groovy_pagename wiki preference before falling back to xwiki.cfg. Neither was documented.
  • xwiki.cfg's authclass takes precedence over the authenticator chosen in the administration, and the administration list only offers the Component-based authenticators.
  • The legacy "Security Module" link now resolves to a page titled "Authorization API" and is about authorization, so it became a hub FAQ entry instead of a section.

Content reduced to a link, to stop duplicating what the extension pages own: OpenID Connect, LDAP (its OldLDAPAuthenticator reference dropped), Active Directory, and the Security part of the Configuration section, which now points at the Authentication API extension.

Content dropped: the first-person SSOLdapAuthenicationImpl JBoss SPNEGO Java dump in the Kerberos section — it extends XWikiLDAPAuthServiceImpl, removed in XWiki 7.4. The Kerberos How-to keeps the part that covers the shipped authenticator.

The two screenshots are attached to this change request, so the pages render complete once it is merged. Three How-tos (configure-container, set-groovy-authenticator, configure-kerberos-sso) end on a textual result step instead: each would need a reconfigured and restarted server to be captured honestly.

The original page is stripped in the same change request and points at the new tree. Its two attachments, its backlinks and its two OldLDAPAuthenticator child pages are handled separately, since deleting or repointing them needs their own backlink pass.

All changes

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +User Authentication
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,7 @@
1 +Authentication is how XWiki decides which user a request belongs to. A wiki uses one authenticator at a time: the standard one checks the password stored in the user's profile, while others hand that decision over to the [[Servlet container>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.WebHome]], an [[LDAP directory>>extensions:Extension.LDAP.Authenticator.WebHome]], an [[OpenID Connect provider>>extensions:Extension.OpenID Connect.OpenID Connect Provider.WebHome]], or to code of your own.
2 +
3 +[[Authentication Types>>documentation.xs.admin.authentication.types.WebHome]] lists what is available, and [[Select the Authenticator>>documentation.xs.admin.authentication.select-authenticator.WebHome]] shows where the choice is made. Three authenticators need server-side setup of their own: [[Configure Container Authentication>>documentation.xs.admin.authentication.configure-container.WebHome]], [[Set Up a Groovy Authenticator in a Wiki Page>>documentation.xs.admin.authentication.set-groovy-authenticator.WebHome]] and [[Configure Kerberos SSO Authentication>>documentation.xs.admin.authentication.configure-kerberos-sso.WebHome]].
4 +
5 +Whichever authenticator is active, the session is carried by cookies, so a browser that refuses them cannot stay logged in from one page to the next. Their lifetime and protection, and the pages the login flow redirects to, come from the [[Authentication Parameters>>documentation.xs.admin.authentication.parameters.WebHome]].
6 +
7 +Two things sit beside authentication rather than inside it. Repeated failed logins can disable an account or demand a CAPTCHA, through strategies configured in the same administration section and documented by the [[Authentication API>>extensions:Extension.Authentication Security Module.WebHome]] extension. And the messages a user receives after requesting a password reset or a forgotten user name are wiki pages, which an administrator can [[Customize the Authentication Mail Templates>>documentation.xs.admin.authentication.customize-mail-templates.WebHome]].
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Can several authenticators be active at the same time? ==
2 +
3 +No, a wiki resolves exactly one authenticator. Some of them chain internally — Container Authentication falls back to the standard one when the container authenticated nobody — but two cannot be enabled side by side.
4 +
5 +== Does authentication decide what a user is allowed to do? ==
6 +
7 +No, that is authorization, which is driven by [[rights>>documentation.xs.admin.rights.WebHome]] and whose implementation can be replaced through the [[Authorization API>>extensions:Extension.Security Module.WebHome]].
Related
... ... @@ -1,0 +1,1 @@
1 +* [[Change Your Password>>documentation.xs.user.user.edit-profile.edit-profile-preferences.change-password.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +explanation
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-security-authentication-api

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Authentication Types
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,34 @@
1 +Only one authenticator is active at a time on a wiki, chosen as described in [[Select the Authenticator>>documentation.xs.admin.authentication.select-authenticator.WebHome]]. The authenticators below are part of XWiki.
2 +
3 +|=Authenticator|=##authclass## value|=Description
4 +|Standard|none, this is the default|Checks the password stored in the user's profile. Shown as "Standard XWiki Authenticator" in the wiki administration.
5 +|Container|##com.xpn.xwiki.user.impl.xwiki.AppServerTrustedAuthServiceImpl##|Trusts the user the Servlet container already authenticated, and falls back to the standard authenticator when there is none. See [[Configure Container Authentication>>documentation.xs.admin.authentication.configure-container.WebHome]].
6 +|Kerberos|##com.xpn.xwiki.user.impl.xwiki.AppServerTrustedKerberosAuthServiceImpl##|Behaves like Container, extracting the user name out of a Kerberos principal. See [[Configure Kerberos SSO Authentication>>documentation.xs.admin.authentication.configure-kerberos-sso.WebHome]].
7 +|Groovy|##com.xpn.xwiki.user.impl.xwiki.GroovyAuthServiceImpl##|Runs an authenticator written in Groovy and stored in a wiki page. See [[Set Up a Groovy Authenticator in a Wiki Page>>documentation.xs.admin.authentication.set-groovy-authenticator.WebHome]].
8 +
9 +The values above go into the ##xwiki.authentication.authclass## property, described in the [[Authentication Parameters>>documentation.xs.admin.authentication.parameters.WebHome]].
10 +
11 +== Form and Basic Credentials ==
12 +
13 +The standard authenticator collects credentials in one of two ways, selected with the ##xwiki.authentication## property: ##form##, the default, serves the login form, while ##basic## answers an unauthenticated request with an HTTP Basic challenge.
14 +
15 +A single request can ask for Basic authentication without changing the configuration, by adding the ##basicauth## parameter to the URL:
16 +
17 +{{code language="none"}}
18 +https://username:[email protected]/xwiki/bin/view/Main/WebHome?basicauth=1
19 +{{/code}}
20 +
21 +{{warning}}
22 +Over plain HTTP those credentials cross the network in clear text. Serve the wiki over HTTPS before relying on Basic authentication.
23 +{{/warning}}
24 +
25 +== Authenticators Provided by Extensions ==
26 +
27 +* [[OpenID Connect Authenticator>>extensions:Extension.OpenID Connect.OpenID Connect Authenticator.WebHome]], to authenticate against an OpenID Connect provider.
28 +* [[LDAP Authenticator>>extensions:Extension.LDAP.Authenticator.WebHome]], to authenticate against an LDAP directory.
29 +
30 +To write an authenticator of your own, follow [[Create a Custom Authenticator>>Documentation.DevGuide.Tutorials.Create a Custom Authenticator.WebHome]].
31 +
32 +== Active Directory ==
33 +
34 +An Active Directory server is reached either through the LDAP Authenticator above, configured by hand, or through the [[Active Directory Application>>https://store.xwiki.com/xwiki/bin/view/Extension/ActiveDirectoryApplication]] — a paying application from XWiki SAS that adds a visual configuration editor, settings applied without restarting the server, and support.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Which authenticator is used when none is configured? ==
2 +
3 +The standard one, which checks the password stored in the user's profile.
4 +
5 +== Can an authenticator be combined with another? ==
6 +
7 +Only when it does so itself: Container and Kerberos authentication fall back to the standard authenticator, so the login form keeps working for users who have a password.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Select the Authenticator>>documentation.xs.admin.authentication.select-authenticator.WebHome]].
2 +* [[Authentication Parameters>>documentation.xs.admin.authentication.parameters.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +reference
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-security-authentication-api

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Select the Authenticator
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,9 @@
1 +To choose the authenticator a wiki uses:
2 +
3 +1. Comment out ##xwiki.authentication.authclass## in the ##xwiki.cfg## file and restart the wiki, because a class named there takes precedence over the choice made in the administration.
4 +1. Go to "Administration" then "Users & Rights" then "Authentication".
5 +1. Pick an authenticator in the "Authentication service" list.
6 +1. Click "Save".
7 +1. Check that "Current Authentication service" now names the authenticator you picked, as follows:(((
8 +{{image reference="authentication-service-section.png" size="large" alt="The Authentication service part of the Authentication administration section, with the current authenticator outlined" caption="XWiki 17.10.11"/}}
9 +)))
authentication-service-section.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +27.6 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Why is there only one authenticator to choose from? ==
2 +
3 +The list holds the authenticators implemented as Components, and reports "No alternative authentication service can be found." while the standard one is alone. An authenticator set through ##xwiki.authentication.authclass## never appears there.
4 +
5 +== Can each subwiki use a different authenticator? ==
6 +
7 +Yes, the setting belongs to the wiki, so a subwiki keeps its own choice as long as no authenticator is forced globally in ##xwiki.cfg##. This is validated on domain-based subwikis; on path-based subwikis it is not fully verified.
Related
... ... @@ -1,0 +1,1 @@
1 +* [[Authentication Types>>documentation.xs.admin.authentication.types.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-security-authentication-api

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Configure Container Authentication
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,15 @@
1 +To hand authentication over to the [[Servlet container>>documentation.xs.admin.installation.methods.install-xwiki-war.configure-servlet-container.WebHome]]:
2 +
3 +1. Configure the container itself to authenticate the requests it serves, following its own documentation.
4 +1. Set the Container authenticator in the ##xwiki.cfg## file:(((
5 +{{code language="properties"}}
6 +xwiki.authentication.authclass=com.xpn.xwiki.user.impl.xwiki.AppServerTrustedAuthServiceImpl
7 +{{/code}}
8 +)))
9 +1. Add the property below to the same file, so that the users the container authenticates are created in the wiki:(((
10 +{{code language="properties"}}
11 +xwiki.authentication.createuser=empty
12 +{{/code}}
13 +)))
14 +1. Restart the wiki.
15 +1. Log in through the container and check that the wiki shows you as that user, and that a profile page now exists for it in the ##XWiki## space.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== What happens when the container authenticates nobody? ==
2 +
3 +The authenticator falls back to the standard XWiki authentication, so the login form still works for users who have a password in their profile.
4 +
5 +== Why is no user profile created? ==
6 +
7 +The ##xwiki.authentication.createuser## property is missing or does not hold the value ##empty##; without it the authenticated user is only set on the request and never stored.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Authentication Types>>documentation.xs.admin.authentication.types.WebHome]].
2 +* [[Authentication Parameters>>documentation.xs.admin.authentication.parameters.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-security-authentication-api

Creation of Set Up a Groovy Authenticator in a Wiki Page

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Set Up a Groovy Authenticator in a Wiki Page
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,16 @@
1 +To authenticate through a script kept in a wiki page:
2 +
3 +1. Create a wiki page whose content is Groovy code returning an ##XWikiAuthService## object.
4 +1. Save that page as a user who has [[programming rights>>Documentation.AdminGuide.Access Rights.Permission types.WebHome||anchor="HProgrammingRight"]], since the code only runs while the page has them.
5 +1. Set the Groovy authenticator in the ##xwiki.cfg## file:(((
6 +{{code language="properties"}}
7 +xwiki.authentication.authclass=com.xpn.xwiki.user.impl.xwiki.GroovyAuthServiceImpl
8 +{{/code}}
9 +)))
10 +1. Point the authenticator at the page holding the code:(((
11 +{{code language="properties"}}
12 +xwiki.authentication.groovy.pagename=MySpace.MyPage
13 +{{/code}}
14 +)))
15 +1. Restart the wiki.
16 +1. Log in and check that your script decided the outcome; when it could not be used, the wiki logs "No page specified for auth service implementation" or a missing programming rights error instead.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Where else can the page name be set? ==
2 +
3 +The authenticator first looks for a ##groovy_pagename## preference in the wiki preferences, and only then falls back to ##xwiki.authentication.groovy.pagename## in ##xwiki.cfg##.
4 +
5 +== Why is the script ignored? ==
6 +
7 +Either no page is configured, or that page does not have programming rights; both cases are logged as an error and leave the wiki with no working authenticator.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Authentication Types>>documentation.xs.admin.authentication.types.WebHome]].
2 +* [[Create a Custom Authenticator>>Documentation.DevGuide.Tutorials.Create a Custom Authenticator.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-security-authentication-api

Creation of Configure Kerberos SSO Authentication

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Configure Kerberos SSO Authentication
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,44 @@
1 +To let Apache HTTP Server authenticate users with Kerberos and pass them on to XWiki:
2 +
3 +1. Create a principal and a keytab for the web server:(((
4 +{{code language="none"}}
5 +# kadmin
6 +kadmin> addprinc -randkey HTTP/wiki.example.com
7 +kadmin> ktadd -k /etc/apache2/ssl/wiki.keytab HTTP/wiki.example.com
8 +kadmin> quit
9 +{{/code}}
10 +)))
11 +1. Restrict the keytab to the user the web server runs as:(((
12 +{{code language="bash"}}
13 +chown www-data:www-data /etc/apache2/ssl/wiki.keytab
14 +chmod 400 /etc/apache2/ssl/wiki.keytab
15 +{{/code}}
16 +)))
17 +1. Install the Apache module for Kerberos authentication, which on Debian and Ubuntu is ##libapache2-mod-auth-kerb##.
18 +1. Protect the wiki location in the virtual host configuration:(((
19 +{{code language="apache"}}
20 +<Location "/xwiki">
21 + AuthType Kerberos
22 + AuthName "Kerberos Login"
23 + KrbAuthRealms EXAMPLE.COM
24 + Krb5Keytab "/etc/apache2/ssl/wiki.keytab"
25 + KrbMethodK5Passwd off
26 + KrbMethodNegotiate on
27 + KrbSaveCredentials on
28 + require valid-user
29 +</Location>
30 +{{/code}}
31 +)))
32 +1. Make the Servlet container trust that authentication. On Apache Tomcat, set ##tomcatAuthentication## to ##false## on the connector, in its ##server.xml## file:(((
33 +{{code language="xml"}}
34 +<Connector port="8009" address="127.0.0.1" enableLookups="false" tomcatAuthentication="false" redirectPort="8443" protocol="AJP/1.3"></Connector>
35 +{{/code}}
36 +)))
37 +1. Set the Kerberos authenticator in the ##xwiki.cfg## file, together with the property that creates the authenticated users in the wiki:(((
38 +{{code language="properties"}}
39 +xwiki.authentication.authclass=com.xpn.xwiki.user.impl.xwiki.AppServerTrustedKerberosAuthServiceImpl
40 +xwiki.authentication.createuser=empty
41 +{{/code}}
42 +)))
43 +1. Restart Apache HTTP Server, the Servlet container and the wiki.
44 +1. Open the wiki from a workstation holding a Kerberos ticket and check that you are logged in without a login form, under the user name taken from your principal.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Why does the browser still ask for credentials? ==
2 +
3 +The browser has to be allowed to negotiate on that host: in Firefox, add the wiki URL to the ##network.negotiate-auth.trusted-uris## preference.
4 +
5 +== Is an extra jar needed? ==
6 +
7 +No, the authenticator is part of XWiki, so nothing has to be copied into the ##WEB-INF/lib## directory.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Authentication Types>>documentation.xs.admin.authentication.types.WebHome]].
2 +* [[Configure Container Authentication>>documentation.xs.admin.authentication.configure-container.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-security-authentication-api

Creation of Authentication Parameters

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Authentication Parameters
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,34 @@
1 +Authentication is configured in the ##xwiki.cfg## file. Apart from ##xwiki.authentication## itself, every parameter below is prefixed with ##xwiki.authentication.## — the second row of the first table is therefore written ##xwiki.authentication.always=1##.
2 +
3 +== Login Flow ==
4 +
5 +|=Name|=Allowed values|=Default|=Description
6 +|##xwiki.authentication##|form, basic|form|How the standard authenticator asks for credentials.
7 +|always|0, 1|0|Authenticate on every request instead of once per session.
8 +|authclass|Java class name|none|The authenticator to use, overriding the choice made in the wiki administration. The values are listed in [[Authentication Types>>documentation.xs.admin.authentication.types.WebHome]].
9 +|createuser|empty|none|Create a wiki profile for the users an external system authenticated. Required by Container and Kerberos authentication.
10 +|realmname|String|XWiki|Realm name sent with an HTTP Basic challenge.
11 +|defaultpage|String|the wiki home page|Page to redirect to after login when no ##xredirect## parameter was given.
12 +|loginpage|String|##/bin/login/XWiki/XWikiLogin##|Page to redirect to when the user is not logged in.
13 +|loginsubmitpage|String|##/loginsubmit/XWiki/XWikiLogin##|URL the login form posts the credentials to.
14 +|logoutpage|String|see below|Page to redirect to after logging out.
15 +|errorpage|String|##/bin/loginerror/XWiki/XWikiLogin##|Page to redirect to when the login failed.
16 +
17 +The shipped ##xwiki.cfg## already gives ##logoutpage## a pattern that matches the ##logout## action whatever the path in front of it, so that logging out keeps working with short URLs and with path-based subwikis. Replace it only when the wiki is served from a different URL layout.
18 +
19 +Only ##realmname## applies when ##xwiki.authentication## is set to ##basic##; the redirection parameters belong to the form flow.
20 +
21 +== Remember-Me Cookies ==
22 +
23 +|=Name|=Allowed values|=Default|=Description
24 +|cookieprefix|String|empty|Prefix added to the names of the authentication cookies.
25 +|cookiepath|String|##/##|Path the cookies are sent to. Set it to the context path of the wiki, ##/xwiki## for instance, when something else runs on the same server.
26 +|cookiedomains|Comma-separated list|the server host name|Domains the cookies are shared with, which is only needed to share a session between the wikis of a farm.
27 +|cookielife|Number|14|Number of days before the cookies expire.
28 +|protection|all, validation, encryption, none|all|Protection applied to the cookie values.
29 +|useip|true, false|true|Bind the cookies to the IP address that obtained them, which forces a new login when it changes.
30 +|validationKey|String|generated|Key used to hash the cookie so that tampering is detected.
31 +|encryptionKey|String|generated|Key used to encrypt the cookie values.
32 +|encryptionalgorithm|String|the cipher default|Algorithm used to encrypt and decrypt the cookies.
33 +|encryptionmode|String|the cipher default|Cipher mode used to encrypt and decrypt the cookies.
34 +|encryptionpadding|String|the cipher default|Padding used to encrypt and decrypt the cookies.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Do the encryption and validation keys have to be set? ==
2 +
3 +No. When they are left empty XWiki generates them and stores them, so a fresh instance protects its cookies without any configuration.
4 +
5 +== Where are the failed-login strategies configured? ==
6 +
7 +Not in ##xwiki.cfg##: they belong to the wiki administration and to the [[Authentication API>>extensions:Extension.Authentication Security Module.WebHome]] extension.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Authentication Types>>documentation.xs.admin.authentication.types.WebHome]].
2 +* [[Select the Authenticator>>documentation.xs.admin.authentication.select-authenticator.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +reference
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-security-authentication-api

Creation of Customize the Authentication Mail Templates

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Customize the Authentication Mail Templates
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,10 @@
1 +To change the emails XWiki sends when a user requests a password reset or a forgotten user name:
2 +
3 +1. Go to the ##XWiki.ResetPasswordMailContent## page for the password reset message, or to ##XWiki.ForgotUsernameMailContent## for the forgotten user name one.
4 +1. Edit the page with the [[object editor>>documentation.xs.user.base.page.edit-page.edit-object-editor.WebHome]].
5 +1. Expand the "XWiki.Mail" object.(((
6 +{{image reference="mail-template-object.png" size="extra" alt="The XWiki.Mail object of the password reset template in the object editor, with the subject property outlined" caption="XWiki 17.10.11"/}}
7 +)))
8 +1. Change the "subject", "html" and "text" properties, keeping the Velocity variables they contain.
9 +1. Click "Save".
10 +1. Request a password reset for a test user and check that the message received uses your wording.
mail-template-object.png
Author
... ... @@ -1,0 +1,1 @@
1 +XWiki.elenicojocariu
Size
... ... @@ -1,0 +1,1 @@
1 +66.5 KB
Content
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== What are the Velocity variables in the template for? ==
2 +
3 +They insert the data of the request, such as the user name and the link to follow, so a template stripped of them sends a message the user cannot act on.
4 +
5 +== Can the message be translated? ==
6 +
7 +Yes, the mail is rendered with the locale of the request, so a template object per language provides the translated wording.
Related
... ... @@ -1,0 +1,1 @@
1 +* [[Change Your Password>>documentation.xs.user.user.edit-profile.edit-profile-preferences.change-password.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]
Technical Identifier
... ... @@ -1,0 +1,1 @@
1 +xwiki:org.xwiki.platform:xwiki-platform-security-authentication-api

Edition of User Authentication

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.ThomasMortagne
1 +XWiki.elenicojocariu
Content
... ... @@ -1,370 +7,13 @@
1 -{{box cssClass="floatinginfobox" title="**Contents**"}}
2 -{{toc/}}
3 -{{/box}}
4 -
5 -XWiki supports several different authentication mechanisms for authenticating users.
6 -
7 7  {{info}}
8 -XWiki currently allows only one method of authentication to be enabled at a time. This will probably be improved in the future.
2 +This documentation moved to [[User Authentication>>documentation.xs.admin.authentication.WebHome]] in the Administrator documentation.
9 9  {{/info}}
10 10  
11 -Also note that XWiki requires cookies to be enabled in order to track your session and to keep you logged in between pages.
5 +The pages below replace the sections of this one:
12 12  
13 -= Choose the authenticator =
14 -
15 -Historically, the authenticator to use in XWiki is controlled by the property ##xwiki.authentication.authclass## in the ##xwiki.cfg## file.
16 -
17 -{{version since="15.3"}}
18 -For authenticators which supports it, it's possible to choose the authenticator to use in the wiki administration.
19 -
20 -{{image reference="authserviceadmin.png"/}}
21 -{{/version}}
22 -
23 -Each subwiki can have its own authenticator. This requires that no global authenticator is declared in ##xwiki.cfg##, by making sure that the line below is commented out:
24 -
25 -{{code}}
26 -# xwiki.authentication.authclass=com.xpn.xwiki.user.impl.xwiki.XWikiAuthServiceImpl
27 -{{/code}}
28 -
29 -Then, the Administration > Authentication section will display the available authenticators, allowing each subwiki to have a specific one.
30 -
31 -{{warning}}
32 -At this stage, the scenario for configuring custom authenticators at wiki level has been tested and validated on [[domain-based subwikis>>xwiki:Documentation.AdminGuide.Virtualization.WebHome]], not yet fully for path-based wikis.
33 -{{/warning}}
34 -
35 -= Authentication Types =
36 -
37 -== Form Authentication ==
38 -
39 -Form authentication is the default way to get authenticated within a Wiki. It requires a user and a password.
40 -
41 -== Basic Authentication ==
42 -
43 -XWiki supports [[basic access authentication>>https://en.wikipedia.org/wiki/Basic_access_authentication]], a method designed to allow a web browser or other client programs to provide credentials - in the form of a user name and password - when making a request. You can get authenticated against an XWiki server with the basic authentication protocol using the following URL scheme:
44 -
45 -{{code}}
46 -https://username:[email protected]/xwiki/bin/view/Main/WebHome?basicauth=1
47 -{{/code}}
48 -
49 -{{warning}}
50 -Be careful that if you use the ##HTTP## protocol your password will be sent in clear over the network and is thus very unsafe. When using basic authentication you should make sure your wiki is configured to use ##HTTPS##.
51 -{{/warning}}
52 -
53 -== Container Authentication ==
54 -
55 -Delegates authentication to the Servlet Container. If it fails it falls back to the standard XWiki authentication.
56 -
57 -To configure XWiki to use it, specify:
58 -
59 -{{code language="properties"}}
60 -xwiki.authentication.authclass=com.xpn.xwiki.user.impl.xwiki.AppServerTrustedAuthServiceImpl
61 -{{/code}}
62 -
63 -For users to be actually created and not just set as context user you must set in ##xwiki.cfg## configuration file (if the property does not already exist, create it):
64 -
65 -{{code language="properties"}}
66 -xwiki.authentication.createuser=empty
67 -{{/code}}
68 -
69 -== OpenId Connect Authentication ==
70 -
71 -See the [[OpenId Connect Authenticator Extension>>extensions:Extension.OpenID Connect.OpenID Connect Authenticator.WebHome]].
72 -
73 -== Active Directory ==
74 -
75 -If you're looking to connect XWiki to an Active Directory server, you currently have 2 options:
76 -
77 -* Using the manual and generic approach using the [[LDAP Authenticator extension>>extensions:Extension.LDAP.Authenticator]]
78 -* Using the dedicated [[Active Directory Application>>https://store.xwiki.com/xwiki/bin/view/Extension/ActiveDirectoryApplication]] which is a paying application dedicated to simplifying the integration of Active Directory with XWiki. The Active Directory Application allows you to easily connect your Active Directory server to XWiki using a **visual editor**, update **advanced configuration** settings without restarting the application server, **technical support** provided by [[XWiki SAS>>https://xwiki.com/]], etc.
79 -
80 -== LDAP ==
81 -
82 -See the [[LDAP Authenticator extension>>extensions:Extension.LDAP.Authenticator]].
83 -
84 -The deprecated LDAP core authenticator (for XWiki < 7.4) can be found on [[OldLDAPAuthenticator]].
85 -
86 -== Custom Authentication ==
87 -
88 -You can create your custom authentication by following [[Create a Custom Authenticator>>Documentation.DevGuide.Tutorials.Create a Custom Authenticator.WebHome]] tutorial.
89 -
90 -Note that it's also possible to customize the right management system, see [[Security Module>>extensions:Extension.Security Module]] for more details.
91 -
92 -=== Custom Authentication using a Groovy script in a wiki page ===
93 -
94 -Start by specifying you want to use the Groovy Authenticator:
95 -
96 -{{code language="properties"}}
97 -xwiki.authentication.authclass = com.xpn.xwiki.user.impl.xwiki.GroovyAuthServiceImpl
98 -{{/code}}
99 -
100 -Then add another configuration parameter to specify in which wiki page the authenticator is:
101 -
102 -{{code language="properties"}}
103 -xwiki.authentication.groovy.pagename = MySpace.MyPage
104 -{{/code}}
105 -
106 -Then put some Groovy code in a wiki page that returns a XWikiAuthService object.
107 -
108 -= Configuration =
109 -
110 -== Authentication parameters ==
111 -
112 -You can set each of these parameters by setting:
113 -
114 -{{code}}
115 -xwiki.authentication.<param_name>=<param_value>
116 -{{/code}}
117 -
118 -|=Name|=Optional|=Allowed values|=Default value|=Description
119 -|encryptionKey|No(1)/{{version since="15.9, 15.5.4, 14.10.19"}}Yes{{/version}}|?|n/a|Set the Encryption Key used to create a secret key, the secret key is passed to the Cipher object to be used during encryption and decryption of cookie values.
120 -|validationKey|No(2)/{{version since="15.9, 15.5.4, 14.10.19"}}Yes{{/version}}|?|n/a|Set the Validation Key used to generate hash value; the hash value is stored with the cookie and used to verify that the cookie has not been tampered with.
121 -|cookiedomains|Yes|String|Server host name|Which host(s) should your cookies be sent to; use only if you want to share cookies across domains, otherwise should be commented out
122 -|cookielife|Yes|Number|14|Number of days cookies take to expire
123 -|cookiepath|Yes|String|/|The webapp path that XWiki cookies should be sent to; if you have anything else running on your web server, this should be set to ///xwiki//
124 -|default_page|Yes|String|/bin/view/ Main/WebHome|Page to redirect to if xredirect parameter is not set
125 -|encryptionalgorithm|Yes|?|?|Set the Encryption Algorithm used to encrypt and decrypt cookies
126 -|encryptionmode|Yes|?|?|Set the Encryption Mode used to encrypt and decrypt cookies
127 -|encryptionpadding|Yes|?|?|Set the Encryption Padding used to encrypt and decrypt cookies
128 -|errorpage|Yes|String|/bin/loginerror/ XWiki/XWikiLogin|Page to redirect to if there is an error logging in
129 -|loginpage|Yes|String|/bin/login/ XWiki/XWikiLogin|Page to redirect to when not logged in
130 -|loginsubmitpage|Yes|String|/loginsubmit/ XWiki/XWikiLogin|The URL where the username and password are posted to when logging in.
131 -|logoutpage|Yes|String|/bin/logout/ XWiki/XWikiLogout|Page to redirect to after logged out
132 -|realmname|Yes|String|XWiki|Sets the realm name
133 -|protection|Yes|all, validation, encryption, none|all|Protection level for the "remember me" cookie functionality
134 -|useip|Yes|true / false|true|Specify to use the IP address when encrypting the cookie data; if IP address changes will need to re-login.
135 -
136 -1. Only required if protection = encryption or all (default)
137 -1. Only required if protection = validation or all (default)
138 -
139 -== Security ==
140 -
141 -Starting with {{code}}XWiki 11.6RC1{{/code}} we provide some authentication strategies that are triggered if a user fails several time in a row to login.
142 -You can configure those strategies and when they should be triggered in the Administration > Authentication page.
143 -
144 -{{gallery}}
145 -image:authentication-security-administration.png
146 -{{/gallery}}
147 -
148 -
149 -For more information see the [[Authencation Security Module documentation>>extensions:Extension.Authentication Security Module]].
150 -
151 -
152 -= Kerberos SSO Authentication =
153 -
154 -{{warning}}
155 -This implementation of SSO is currently under review see: https://jira.xwiki.org/browse/XWIKI-2496 . The class which is described in this segment of documentation, AppServerTrustedKerberosAuthServiceImpl, is not part of the default XWiki distribution!
156 -{{/warning}}
157 -
158 -The following is an example of **mod_auth_kerb** for Apache being used to easily implement XWiki authentication of users via HTTP Negotiate on a linux server. This example assumes you already have a working Apache2 HTTPD and Apache Tomcat setup with mod_jk.
159 -
160 -First of all you need to create a principal and keytab for the webserver:
161 -
162 -{{code}}
163 -# kadmin
164 -kadmin> addprinc -randkey HTTP/wiki.example.com
165 -kadmin> ktadd -k /etc/apache2/ssl/wiki.keytab HTTP/wiki.example.com
166 -kadmin> quit
167 -{{/code}}
168 -
169 -Make sure the keytab has the right permissions and ownership:
170 -
171 -{{code}}
172 -chown www-data:www-data /etc/apache2/ssl/wiki.keytab
173 -chmod 400 /etc/apache2/ssl/wiki.keytab
174 -{{/code}}
175 -
176 -Install **mod_auth_kerb** in your linux installation. On Debian or Ubuntu this would be achieved by running:
177 -
178 -{{code}}
179 -aptitude install libapache2-mod-auth-kerb
180 -{{/code}}
181 -
182 -Of course the installation procedure varies per Linux distribution.
183 -
184 -If your xwiki installation is mounted in Apache HTTPD under /xwiki, add the following to the virtual host configuration:
185 -
186 -{{code}}
187 -<Location "/xwiki">
188 - AuthType Kerberos
189 - AuthName "Kerberos Login"
190 - KrbAuthRealms EXAMPLE.COM
191 - Krb5Keytab "/etc/apache2/ssl/wiki.keytab"
192 - KrbMethodK5Passwd off
193 - KrbMethodNegotiate on
194 - KrbSaveCredentials on
195 - require valid-user
196 -</Location>
197 -{{/code}}
198 -
199 -Make sure Apache Tomcat uses the authentication performed by Apache HTTPD with the "tomcatAuthentication" property in the connector description (which is in the **server.xml** file of Apache Tomcat):
200 -
201 -{{code}}
202 -<Connector port="8009" address="127.0.0.1" enableLookups="false" tomcatAuthentication="false" redirectPort="8443" protocol="AJP/1.3" ></Connector>
203 -{{/code}}
204 -
205 -Place the **authkerb.jar** jar in the ##WEB-INF/lib## directory of XWiki in Apache Tomcat.
206 -
207 -Have Xwiki use the authentication module by changing the "xwiki.authentication.authclass" property in the ##WEB-INF/lib/xwiki.cfg## file.
208 -
209 -{{code}}
210 -xwiki.authentication.authclass=com.xpn.xwiki.user.impl.xwiki.AppServerTrustedKerberosAuthServiceImpl
211 -{{/code}}
212 -
213 -If you use Firefox, do not forget to whitelist the xwiki URL for HTTP Negotiate in about:config with the "network.negotiate-auth.trusted-uris" property. Possible values for this property include: //https:~/~/// for all secured connections or **example.com** for all example.com subdomains.
214 -
215 -When I used JBoss SPNEGO (Kerberos in combination with LDAP) I changed the code of the **XWikiLDAPAuthServiceImpl** to be able to detect the sso user. The authenication already happend by using the SPNEGO module (JAAS). After that I'm using the ldap synchronisation feature to make sure that the user is up to date. The combination leads to an automatic login in XWiki and the user rights are controlled in the Active Directory server. I hope you can adopt this code or that you can use it for your own projects.
216 -
217 -The configuration of ldap:
218 -
219 -{{code}}
220 -xwiki.authentication.authclass=com.wiki.sso.SSOLdapAuthenicationImpl
221 -xwiki.authentication.ldap=1
222 -xwiki.authentication.ldap.server=<ad-server>
223 -xwiki.authentication.ldap.port=389
224 -xwiki.authentication.ldap.base_DN=<OU=Users,...............>
225 -#use a fixed user to attach to the ldap database,
226 -#the password is not provided with the SSOLdapAuthenicationImpl
227 -xwiki.authentication.ldap.bind_DN=<domain>\\<user>
228 -xwiki.authentication.ldap.bind_pass=<password>
229 -#Microsoft AD configuration
230 -xwiki.authentication.ldap.UID_attr=sAMAccountName
231 -xwiki.authentication.ldap.fields_mapping=name=sAMAccountName,last_name=sn,first_name=givenName,fullname=displayName,mail=mail,ldap_dn=dn
232 -xwiki.authentication.ldap.group_memberfields=member,uniqueMember
233 -#LDAP group mapping
234 -xwiki.authentication.ldap.group_mapping=XWiki.XWikiAdminGroup=CN=WIKI_Admin,............|\
235 - XWiki.XWikiAllGroup=CN=WIKI_User,...........
236 -{{/code}}
237 -
238 -The java code:
239 -
240 -{{code}}
241 -package com.wiki.sso;
242 -
243 -
244 -import org.apache.commons.logging.Log;
245 -import org.apache.commons.logging.LogFactory;
246 -
247 -import com.xpn.xwiki.XWikiContext;
248 -import com.xpn.xwiki.XWikiException;
249 -import com.xpn.xwiki.user.api.XWikiUser;
250 -import com.xpn.xwiki.user.impl.LDAP.XWikiLDAPAuthServiceImpl;
251 -
252 -import java.security.Principal;
253 -
254 -public class SSOLdapAuthenicationImpl extends XWikiLDAPAuthServiceImpl {
255 - /**
256 - * Logging tool.
257 - */
258 - private static final Log LOG = LogFactory.getLog(SSOLdapAuthenicationImpl.class);
259 -
260 -
261 - public XWikiUser checkAuth(XWikiContext context) throws XWikiException {
262 - String user = getRemoteUser(context);
263 - if ((user != null) || !user.equals("")) {
264 - if (LOG.isInfoEnabled())
265 - LOG.info("Launching create user for " + user);
266 - if ( authenticate(user, context) != null ) {
267 - if (LOG.isInfoEnabled())
268 - LOG.info("Create user done for " + user);
269 - user = "XWiki." + user;
270 - context.setUser(user);
271 - System.out.println("User is set to:" + user);
272 - return new XWikiUser(user);
273 - } else {
274 - LOG.error( "User " + user + " can't be authenticated against ldap" );
275 - }
276 - }
277 - return super.checkAuth(context);
278 - }
279 -
280 - /**
281 - * We cannot authenticate locally since we need to trust the app server for
282 - * authentication
283 - *
284 - * @param username
285 - * @param password
286 - * @param context
287 - * @return
288 - * @throws XWikiException
289 - */
290 - public XWikiUser checkAuth(String username, String password,
291 - String rememberme, XWikiContext context) throws XWikiException {
292 - String user = getRemoteUser(context);
293 - if ((user == null) || user.equals("")) {
294 - return super.checkAuth(username, password, rememberme, context);
295 - }
296 - return checkAuth(context);
297 - }
298 -
299 - private String getRemoteUser(XWikiContext context) {
300 - String userName = context.getRequest().getHttpServletRequest()
301 - .getRemoteUser();
302 - if (userName != null) {
303 - // only take the front of the username@domain
304 - String[] elements = userName.split("@", 2);
305 - userName = elements[0];
306 - }
307 - return userName;
308 - }
309 -
310 - public Principal authenticate(String login, XWikiContext context) throws XWikiException
311 - {
312 - if (LOG.isTraceEnabled()) {
313 - LOG.trace("Starting LDAP authentication");
314 - }
315 -
316 - /*
317 - * TODO: Put the next 4 following "if" in common with XWikiAuthService to ensure coherence This method was
318 - * returning null on failure so I preserved that behaviour, while adding the exact error messages to the context
319 - * given as argument. However, the right way to do this would probably be to throw XWikiException-s.
320 - */
321 -
322 - if (login == null) {
323 - // If we can't find the username field then we are probably on the login screen
324 -
325 - if (LOG.isDebugEnabled()) {
326 - LOG.debug("The provided user is null."
327 - + " We don't try to authenticate, it probably means the user is in non logged mode.");
328 - }
329 -
330 - return null;
331 - }
332 -
333 - // Check for empty usernames
334 - if (login.equals("")) {
335 - context.put("message", "nousername");
336 -
337 - if (LOG.isDebugEnabled()) {
338 - LOG.debug("LDAP authentication failed: login empty");
339 - }
340 -
341 - return null;
342 - }
343 -
344 - // If we have the context then we are using direct mode
345 - // then we should specify the database
346 - // This is needed for virtual mode to work
347 - Principal principal = null;
348 -
349 - // Try authentication against ldap
350 - principal = ldapAuthenticate(login, "", context);
351 -
352 - if (LOG.isDebugEnabled()) {
353 - if (principal != null) {
354 - LOG.debug("LDAP authentication succeed with principal [" + principal.getName() + "]");
355 - } else {
356 - LOG.debug("LDAP authentication failed for user [" + login + "]");
357 - }
358 - }
359 -
360 - return principal;
361 - }
362 -}
363 -{{/code}}
364 -
365 -= Mail Templates =
366 -
367 -When [[logging in>>Documentation.UserGuide.Features.Authentication#HLoggingin]], you have the option of resetting your user's password if you forgot it, or to find your username based on your email address. When choosing these options, you'll be sent an email. It's possible to control the templates used for these emails and to customize them by editing the following pages in object mode:
368 -
369 -* ##XWiki.ResetPasswordMailContent##
370 -* ##XWiki.ForgotUsernameMailContent##
7 +* {{id name="HFormAuthentication"/}}{{id name="HCustomAuthentication"/}}[[Authentication Types>>documentation.xs.admin.authentication.types.WebHome]], including Form, Basic and the authenticators provided by extensions.
8 +* [[Select the Authenticator>>documentation.xs.admin.authentication.select-authenticator.WebHome]].
9 +* [[Configure Container Authentication>>documentation.xs.admin.authentication.configure-container.WebHome]].
10 +* [[Set Up a Groovy Authenticator in a Wiki Page>>documentation.xs.admin.authentication.set-groovy-authenticator.WebHome]].
11 +* [[Configure Kerberos SSO Authentication>>documentation.xs.admin.authentication.configure-kerberos-sso.WebHome]].
12 +* [[Authentication Parameters>>documentation.xs.admin.authentication.parameters.WebHome]].
13 +* [[Customize the Authentication Mail Templates>>documentation.xs.admin.authentication.customize-mail-templates.WebHome]].
authentication-security-administration.png
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.ThomasMortagne
1 +XWiki.surli
Size
... ... @@ -1,1 +1,1 @@
1 -30.8 KB
1 +52.7 KB
Content
Aug 8, 2026, 12:48:00 AM

Approved by Eleni Cojocariu

Approvers

Approvers have not been explicitly defined for this Change Request. Approvers will be based entirely on approval rights.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected