mirror of
https://github.com/hedgedoc/hedgedoc.git
synced 2024-12-18 02:53:06 -05:00
87 lines
4.2 KiB
Markdown
87 lines
4.2 KiB
Markdown
# User Profiles and Authentication
|
|
Each user in HedgeDoc 2 has a profile
|
|
which contains the following information:
|
|
|
|
- username (`janedoe`)
|
|
- display name (`Jane Doe`)
|
|
- email address, optional (`janedoe@example.com`)
|
|
- profile picture, optional
|
|
- the date the user was created
|
|
- the date the profile was last updated
|
|
|
|
HedgeDoc 2 supports multiple authentication methods per user.
|
|
These are called *identities* and each identity is backed by an
|
|
auth provider (like OAuth, SAML, LDAP or internal auth).
|
|
|
|
One of a users identities may be marked as *sync source*.
|
|
This identity is used to automatically update profile attributes like the
|
|
display name or profile picture on every login. If a sync source exists, the
|
|
user can not manually edit their profile information.
|
|
If an external provider was used to create the account,
|
|
it is automatically used as sync source.
|
|
|
|
The administrator may globally set one or more auth providers as sync source,
|
|
e.g. to enforce that all profile information comes from the corporate
|
|
LDAP and is the same across multiple applications.
|
|
If global sync sources exist, new accounts can only be created using
|
|
these auth providers. The auth provider that was used to create the account
|
|
is automatically set as sync source and cannot be changed by the user.
|
|
This effectively pins the account to this provider.
|
|
|
|
## Example: Corporate LDAP
|
|
The administrator wants to allow users to log in via the corporate LDAP
|
|
and Google. Login must only be possible for users present in LDAP and
|
|
all users must be displayed as they are in the LDAP.
|
|
|
|
The admin therefore sets up two login providers:
|
|
|
|
- corporate LDAP, marked as global sync source
|
|
- Google OAuth login
|
|
|
|
If a new user tries to log in via Google, they will not be found in the
|
|
database. The frontend detects that a global sync source exists and
|
|
suggests logging in via LDAP first.
|
|
|
|
After a new user created their account by logging in via LDAP, they can use
|
|
the 'add a new login method' feature in their profile page to link their
|
|
Google account and use it to login afterwards.
|
|
|
|
## Example: Username Conflict
|
|
HedgeDoc is configured with two auth providers.
|
|
|
|
- A user logs in using auth provider A.
|
|
- The backend recieves the profile information from provider A and notices that the username in the profile
|
|
already exists in the database, but no identity for this provider-username combination exists.
|
|
- The backend creates a new user with another username to solve the username conflict.
|
|
- The frontend warns the user that the username provided by the auth provider is already taken and that another
|
|
username has been generated. It also offers to instead link the new auth provider (in this case A) with the
|
|
existing auth provider (in this case B).
|
|
- If the user chooses the latter option, the frontend sends a request to delete the newly created user to the backend.
|
|
- The user can then log in with auth provider B and link provider A using the "link auth provider" feature in
|
|
the profile page.
|
|
|
|
### Handling of sync sources and username conflicts
|
|
|
|
#### Global sync sources
|
|
If at the time of logging in with auth provider A, *only* A is configured as a *global* sync source,
|
|
the backend cannot automatically create a user with another username.
|
|
|
|
This is because:
|
|
|
|
- Creating new accounts is only possible with a sync source auth provider.
|
|
- Setting an auth provider as sync-source entails that profile information the auth provider provides must be
|
|
saved into the local HedgeDoc database.
|
|
- As the username the auth provider provides already exists in the database, a new user cannot be created with
|
|
that username.
|
|
|
|
In this case, the frontend should show the use a notice that they should contact an admin to resolve the issue.
|
|
|
|
!!! warning
|
|
Admins must ensure that usernames are unique across all auth providers set as a global sync source.
|
|
Otherwise, if e.g. in both LDAPs configured as sync source a user `johndoe` exists,
|
|
only the first that logs in can use HedgeDoc.
|
|
|
|
#### Local sync sources
|
|
If auth provider A is configured as a sync source by the user, syncing is automatically disabled, and a notice is shown.
|
|
Re-enabling the sync source is not possible until the username conflict is resolved, e.g. by changing the username
|
|
in the auth provider.
|