User management with OpenID Connect
[]
This article explains how user accounts in the provider system are matched with their records in the censhare system.
User asset lookup
Remember that HCMS Client itself does not store any user data. Instead, such data is kept directly in the censhare system, in the person.account. assets.
Upon login, an asset lookup happens to match the user identity.
By unique identifier (sub claim)
Each provider has its own identifier for users, but, following the OpenID standard, identifiers are always passed in the sub claim of the authentication request. On the censhare side, those identifiers are stored in the subfeature hcms:account.openid.sub of the person.account. assets.
By email
When the user account is not found using the sub claim , the person.account. asset is looked up based on the preferred_username claim if it exists, otherwise on the email claim.
This workflow needs to be explicitly enabled in the HCMS Client configuration by setting accountPairBy to email.
Warning Please note that pairing by preferred_username or even email should be enabled only when the OpenID provider is fully trusted. Enabling it for untrusted, public provider, is considered a security issue as this allows any other user who knows your email, to self-register and get access to all your data stored in censhare.
General notes
Both the asset type and features used for authentication can be customized by changing the HCMS account schema.
A user that has accounts with multiple provides will be considered the same person by the HCMS Client if the following requirements are met:
- Email match is enabled, i.e., this is set as
"accountPairBy": "email"in the application configuration. - The user email is identical for all these accounts.
- Email match is enabled, i.e., this is set as
User creation
When you need to add users to your system, you have a few options here.
Server-side automation
The recommended approach is to create user assets by a server-side automation that imports them directly to the censhare system from an external source, using a special API of the provider. Alternatively, this import can be also done via the HCMS API, by an application that can create its own JWT token.
A server-side automation is not available out-of-the-box, but is also not strictly necessary; there are easier options as explained below.
Self-registration
The HCMS Client can automatically create new assets (entities) when the user logs in for the first time. This must be explicitly enabled by setting "autoCreate": true in the HCMS Client configuration for the corresponding OpenID Connect provider.
However, you need to keep in mind the following prerequisites:
- either the user needs to have an account in the OpenID provider system before trying to self-register in the HCMS Client or
- if the user does not have such an account, self-registration must be enabled by the provider: in this case, the user registers in both systems by logging in the Client for the first time.
Self-registration workflows in the HCMS Client and in the OpenID provider systems are otherwise completely unrelated and need to be managed separately.
Email match
If the user asset lookup based on email is enabled, then, if a matching asset is found, an openid.sub subfeature with the value from the sub claim will be added to it. This is similar to the self-registration from the user perspective, with the difference that their data should exist in the censhare system upfront.
Combining multiple options
It is possible to use all options together and, in particular, to have email match and self-registration enabled at the same time.