Skip to Content

Published

Move the User Profiles and External Identities explanation into the authentication topic

Last modified by Eleni Cojocariu on 2026/08/20 10:23

The documentation.xs.admin.instance-cloning hub carried three level-2 sections. Two of them are about cloning; the third, "User Profiles and External Identities", explains how the wiki records an external identity on a user profile, which is an authentication concept that merely has a cloning consequence. It was also the longest of the three, and it made the hub the longest page of the Administrator tree — 3627 characters against 2408 for the User Authentication hub and 1817 for Upgrade — and longer than the How-to it exists to route to.

The evidence that it sat in the wrong topic is the User Authentication hub itself, which had to link backwards into a cloning page in order to introduce one of its own concepts. That link was added in the change request that finished the cloning topic, and the question of moving the explanation was raised there and approved without being answered. This is the answer.

A new page, User Profiles and External Identities, an Explanation for administrators under the User Authentication topic. It holds the mechanism and only that: profiles are pages; an external identity provider gets a mirror profile per user, created on their first login or by a synchronization; the OpenID Connect authenticator records an issuer and a subject on it; and every later login is matched on that pair, never on the user name.

The cloning hub loses that section and keeps one paragraph: what cloning does to the copied identities, and the link to Preserve User Profiles When Cloning to a Different Identity Provider for the case that needs a procedure. It also loses its level-2 headings — it was the only hub in the Administrator tree to carry any — and one sentence that previewed the paragraphs below it. It is now 341 words over 6 paragraphs, shorter than its own How-to.

The User Authentication hub links the explanation where it now lives, and links cloning on the wording that names it, instead of one link doing both jobs.

The preserve How-to links the explanation from the wording that names the concept, in its intro and in the step that tells the reader to edit the identity data in the database. The class and property names stay on that page, because they are what the reader needs in order to act; the semantics stay on the explanation. Its intro also drops the consequence the cloning hub now states, so that fact is on one page.

No fact moved twice: the mechanism is on the new page alone, the cloning consequence on the cloning hub alone, the procedure on the preserve page alone.

All changes

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +User Profiles and External Identities
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,5 @@
1 +XWiki stores [[user profiles>>documentation.xs.user.user.WebHome]] as pages, one per user, whether the wiki checks their password itself or hands that decision over to an external identity provider.
2 +
3 +The first time a provider authenticates a user the wiki has never seen, it creates a mirror profile for them — a synchronization can also create it in advance — and records on it the identity that profile stands for. The [[OpenID Connect authenticator>>extensions:Extension.OpenID Connect.OpenID Connect Authenticator.WebHome]] records two values: the issuer, which is the provider's URL and is therefore the same on every profile, and the subject, which identifies that one user at that provider.
4 +
5 +Every later login is matched on that pair, never on the user name. A profile therefore belongs to one identity at one provider: the same person arriving from anywhere else is someone the wiki has never seen, and gets a profile of their own.
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,7 @@
1 +== Does renaming a user break the link with their external identity? ==
2 +
3 +No. The authenticator looks the profile up by the issuer and the subject recorded on it, so the user name it carries can change freely.
4 +
5 +== What happens when the same person signs in through two different providers? ==
6 +
7 +Each provider gives them a different pair, so the wiki matches neither identity to the other and keeps one profile per identity.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Authentication Types>>documentation.xs.admin.authentication.types.WebHome]].
2 +* [[Instance Cloning>>documentation.xs.admin.instance-cloning.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

Edition of Instance Cloning

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Instance Cloning
Parent
... ... @@ -1,0 +1,1 @@
1 +documentation.xs.admin.WebHome
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.XWikiGuest
1 +XWiki.elenicojocariu
Default language
... ... @@ -1,0 +1,1 @@
1 +en
Content
... ... @@ -1,0 +1,11 @@
1 +Cloning an XWiki instance means making a full, independent copy of it: an instance that serves the same content while keeping its own identity. A common case is copying a live instance into a preproduction environment, to test changes before they go live.
2 +
3 +The base procedure is a [[Backup/Restore>>Documentation.AdminGuide.Backup]] of the database and the [[permanent directory>>documentation.xs.admin.configuration.directories.permanent-directory.WebHome]], which together hold everything the instance contains. What that copy cannot do on its own is tell apart what belongs to the wiki from what identifies //this// instance in //this// environment. [[Clone an XWiki Instance>>documentation.xs.admin.instance-cloning.clone-instance.WebHome]] covers both halves.
4 +
5 +Every instance has an [[id of its own>>documentation.xs.dev.instance.get-instance-id.WebHome]], stored as the single row of the ##xwikiid## database table. Restoring that row would hand the source's identity to the target, so the table is left out of the restore. Licenses for [[paid extensions>>https://store.xwiki.com/xwiki/bin/view/Main/]] are issued against an instance id, which is why the ones restored with the database do not apply to the target: it reloads its own from the store instead.
6 +
7 +A domain name, a mail server, the address of a third-party service: these describe the environment rather than the wiki, and they live in two places that behave differently when cloning. ##xwiki.cfg## and ##xwiki.properties## are [[configuration files>>documentation.xs.admin.configuration.WebHome]], so no database restore touches them. They have to be copied from the source and then reviewed, because any of their uncommented settings may name the source's environment.
8 +
9 +Everything else is in the database and comes back holding the source's values: the "Alias" property of the ##XWiki.XWikiServerXwiki## page, which is the domain name the wiki answers on, the [[mail sending>>extensions:Extension.Mail.MailApplication]] settings, and the settings of every extension that connects to an external service.
10 +
11 +The [[external identities>>documentation.xs.admin.authentication.user-profiles-external-identities.WebHome]] an identity provider recorded on the [[user profiles>>documentation.xs.user.user.WebHome]] are copied with them, which is what you want when both instances authenticate against the same provider. When the target uses a different one, returning users are given a second, empty profile — and its own [[authentication>>documentation.xs.admin.authentication.WebHome]] settings are not enough to prevent that, hence [[Preserve User Profiles When Cloning to a Different Identity Provider>>documentation.xs.admin.instance-cloning.preserve-user-profiles-different-identity-provider.WebHome]].
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,11 @@
1 +== Should ##hibernate.cfg.xml## be copied from the source as well? ==
2 +
3 +No. It holds the database connection of the instance it belongs to, so copying it would point the target instance at the source's database.
4 +
5 +== What if the target instance's own id is lost during the restore? ==
6 +
7 +XWiki generates a new one on the next start and stores it, so the instance keeps working — but it is no longer the instance its licenses were issued against.
8 +
9 +== Can a XAR export of every page replace the database dump? ==
10 +
11 +No. Some data is not stored in wiki pages and is therefore absent from an [[export in XAR format>>documentation.xs.admin.exports.export-content-xar-format.WebHome]]: the instance id, the event stream, the statistics, the deleted documents and attachments, and the mail statuses.
Related
... ... @@ -1,0 +1,2 @@
1 +* [[Backup/Restore>>Documentation.AdminGuide.Backup]].
2 +* [[Multi-tenancy>>Documentation.AdminGuide.Virtualization.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +explanation
DocApp.Code.DocumentationExtensionClass[0]

Edition of Preserve User Profiles When Cloning to a Different Identity Provider

Summary

Details

Page properties
Title
... ... @@ -1,0 +1,1 @@
1 +Preserve User Profiles When Cloning to a Different Identity Provider
Parent
... ... @@ -1,0 +1,1 @@
1 +documentation.xs.admin.instance-cloning.WebHome
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 +When the target instance of a clone authenticates against a different identity provider than the source — or against the same provider with a different client configuration — the [[external identities>>documentation.xs.admin.authentication.user-profiles-external-identities.WebHome]] recorded on the copied [[user profiles>>documentation.xs.user.user.WebHome]] match nothing. To keep returning users on the profile they already have:
2 +
3 +1. Export the user profiles of the target instance that are linked to an external identity, before cloning it: one at a time with [[Export a Page>>documentation.xs.user.exports.export-page.WebHome]], or together with [[Export Content in XAR format>>documentation.xs.admin.exports.export-content-xar-format.WebHome]].
4 +1. Clone the instance by following [[Clone an XWiki Instance>>documentation.xs.admin.instance-cloning.clone-instance.WebHome]], which keeps the target instance's own [[authentication>>documentation.xs.admin.authentication.WebHome]] settings rather than the source's.
5 +1. Reconnect the copied profiles to the target instance's identity provider, in one of two ways:(((
6 +* [[Import>>documentation.xs.admin.imports.import-xwiki-pages.WebHome]] the profile pages exported in step 1, which restores the identity data the target instance had recorded.
7 +* Edit that [[identity data>>documentation.xs.admin.authentication.user-profiles-external-identities.WebHome]] in the database instead. The [[OpenID Connect authenticator>>extensions:Extension.OpenID Connect.OpenID Connect Authenticator.WebHome]] keeps it in an ##XWiki.OIDC.UserClass## [[object>>documentation.xs.dev.data-model.x-objects.WebHome]] on each profile page, as an ##issuer## and a ##subject##, either of which the target instance's provider may spell differently.
8 +)))
9 +1. Log in on the target instance as a user the identity provider authenticates, and check that they reach the profile they already had, with no second profile created for them in the [[user index>>documentation.xs.user.user.view-wiki-users.WebHome]].
DocApp.Code.DocumentationClass[0]
FAQ
... ... @@ -1,0 +1,11 @@
1 +== Which users does this concern? ==
2 +
3 +Only the users an external identity provider authenticates. A user whose password is stored in their own profile is matched by user name and is unaffected.
4 +
5 +== Is exporting and importing better than editing the database? ==
6 +
7 +Both reach the same result. Exporting and importing uses nothing but the wiki's own tools; editing the identity data in the database saves the re-import but needs direct access to it.
8 +
9 +== Why not copy the authentication settings like every other setting? ==
10 +
11 +The target instance would then authenticate its users against the source's identity provider, which is exactly what a separate environment is meant to avoid.
Related
... ... @@ -1,0 +1,3 @@
1 +* [[User Authentication>>documentation.xs.admin.authentication.WebHome]].
2 +* [[Export Content in XAR format>>documentation.xs.admin.exports.export-content-xar-format.WebHome]].
3 +* [[Import XWiki Pages>>documentation.xs.admin.imports.import-xwiki-pages.WebHome]].
Target
... ... @@ -1,0 +1,1 @@
1 +administrator
Type
... ... @@ -1,0 +1,1 @@
1 +howto
DocApp.Code.DocumentationExtensionClass[0]

Summary

Details

Page properties
Content
... ... @@ -1,4 +1,4 @@
1 -Authentication is the process XWiki uses to determine who is making a request. 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. An authenticator that hands it over brings the provider's own notion of who a user is, so the wiki holds [[User Profiles and External Identities>>documentation.xs.admin.instance-cloning.WebHome]], which is what makes copying such a wiki to another environment a case of its own.
1 +Authentication is the process XWiki uses to determine who is making a request. 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. An authenticator that hands it over brings the provider's own notion of who a user is, so the wiki holds [[User Profiles and External Identities>>documentation.xs.admin.authentication.user-profiles-external-identities.WebHome]], which is what makes [[copying such a wiki to another environment>>documentation.xs.admin.instance-cloning.WebHome]] a case of its own.
2 2  
3 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 4  
Aug 11, 2026, 4:02:33 PM

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