Authentication Parameters
Reference
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.
Login Flow
| Name | Allowed values | Default | Description |
|---|---|---|---|
| xwiki.authentication | form, basic | form | How the standard authenticator asks for credentials. |
| always | 0, 1 | 0 | Authenticate on every request instead of once per session. |
| authclass | Java class name | none | The authenticator to use, overriding the choice made in the wiki administration. The values are listed in Authentication Types. |
| createuser | empty | none | Create a wiki profile for the users an external system authenticated. Required by Container and Kerberos authentication. |
| realmname | String | XWiki | Realm name sent with an HTTP Basic challenge. |
| defaultpage | String | the wiki home page | Page to redirect to after login when no xredirect parameter was given. |
| loginpage | String | /bin/login/XWiki/XWikiLogin | Page to redirect to when the user is not logged in. |
| loginsubmitpage | String | /loginsubmit/XWiki/XWikiLogin | URL the login form posts the credentials to. |
| logoutpage | String | see below | Page to redirect to after logging out. |
| errorpage | String | /bin/loginerror/XWiki/XWikiLogin | Page to redirect to when the login failed. |
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.
Only realmname applies when xwiki.authentication is set to basic; the redirection parameters belong to the form flow.
Remember-Me Cookies
| Name | Allowed values | Default | Description |
|---|---|---|---|
| cookieprefix | String | empty | Prefix added to the names of the authentication cookies. |
| 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. |
| 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. |
| cookielife | Number | 14 | Number of days before the cookies expire. |
| protection | all, validation, encryption, none | all | Protection applied to the cookie values. |
| useip | true, false | true | Bind the cookies to the IP address that obtained them, which forces a new login when it changes. |
| validationKey | String | generated | Key used to hash the cookie so that tampering is detected. XWiki 18.9.0+ Also used to derive the CSRF tokens. |
| encryptionKey | String | generated | Key used to encrypt the cookie values. |
| encryptionalgorithm | String | the cipher default | Algorithm used to encrypt and decrypt the cookies. |
| encryptionmode | String | the cipher default | Cipher mode used to encrypt and decrypt the cookies. |
| encryptionpadding | String | the cipher default | Padding used to encrypt and decrypt the cookies. |
When validationKey or encryptionKey is not set, XWiki generates a random value the first time it needs it and stores it in the configuration.properties file of the permanent directory. In a cluster, set the same random value on every node, otherwise users are logged out whenever the load balancer switches nodeXWiki 18.9.0+ and the CSRF tokens of one node are rejected by the others. Like any parameter of xwiki.cfg, they can also be set without editing the file, for example from a secret store, with the XCONF_xwikicfg_xwiki_authentication_validationKey and XCONF_xwikicfg_xwiki_authentication_encryptionKey environment variables.
FAQ
Do the encryption and validation keys have to be set?
No. When they are left empty XWiki generates them and stores them, so a fresh instance protects its cookies without any configuration.
Where are the failed-login strategies configured?
Not in xwiki.cfg: they belong to the wiki administration and to the Authentication API extension.
