User Store

Create new IDP

Steps to create a new IDP:

• Navigate to the ProAuth Admin UI and login with a user assigned to role SubscriptionAdmin or higher
• Navigate to Idp Instances and click on Create Idp Instance
• Choose the IDP Type UserStore
• Enable the flag Active
• Enable the flag Auto Create ProAuth User
• Choose the proper Subscription
• Click Save

Configure new IDP

After the creation of the IDP in the step before, it's now necessary to configure the IDP. Invalid IPDs aren't available in ProAuth.

It's necessary to already have an existing and deployed UserStore database. The connection string with Read/Write permissions to this database is one of the mandatory options.

Steps to complete the configuration of the IDP:

• Open the IDP in the extended edit view
• Assign the IDP to the required Tenants

Configure mandatory Options:

• Set the ConnectionString for the SQL database
• Set the CallbackPath (e.g. /signin-userstore)
• Set the ClaimIssuer (default: UserStore)
• Set the HashAlgorithmName (default: System.Security.Cryptography.SHA256)
• Set the IsDatabaseReadOnlyMode (default: false)

Enable UserStore login by email address:

The UserStore identifies its users by their unique username. The user entry also contains an e-mail field which is primarily used for notifications. People are used to login by their e-mail address. There are two possibilities to achieve that behavior. Either the username is set to the users e-mail or you can enable to UserStore to accept logins by the username or the e-mail address. The latter option only works, if the e-mail addresses are unique across all users in the same user store. To enable login by e-mail, please set the following options:

• Set the LoginByEmailEnabled option to true

  

INFO

• The user input (username or e-mail) is always checked against the username first. If no username is found and this option is enabled, the e-mail address is used to identify the user. This order is necessary because e-mail addresses can also be used as usernames in the user store.

• If more than one user is found due to the email address (two or more users have entered the same email address) an error message is displayed (username/email or password wrong). We treat this case as if the e-mail address does not exist. For these users a login via username is mandatory. For security reasons, only a general error message is returned.

• The password reset works similar to the login: If the option is enabled, the password reset can be requested via the e-mail address. If the e-mail address is used more than once, the password reset must be requested via the username.

Configure mail setting Options

• Set the EMailSenderAddress
• Set the MailServerConfig

MailServerConfiguration sample data for SMTP Server:

{
    "MailType": "SMTP",
    "Host": "<smtp-host-address>",
    "Port": 465,
    "EnableSSL": true,
    "UserName": "<smtp-username>",
    "Password": "<smtp-password>",
    "Timeout": 20000
}

MailServerConfiguration sample data for Microsoft365:

{
    "MailType": "M365",
    "ClientId": "<aad-app-clientid>",
    "ClientSecret": "<aad-app-clientsecret>",
    "TenantId": "<aad-app-tenantid>",
    "UserId": "<aad-user-objectid>"
}

User lock notifications Options

An email notification can be enabled to inform administrators about locked users (due to too many wrong login attempts).

• Enable notification by the option LockedUserNotificationEnabled
• Configure the recipients by adding a semicolon separated list of e-mail addresses in the option LockedUserNotificationRecipients

The subject and the content of the e-mail message can be customized. The following options are used for this:

• LockedUserNotificationMailSubjectTemplate: Contains the reference for a label used as the e-mail subject
• LockedUserNotificationCulture: This defines the culture which is used to translate the labels (The culture name in the format languagecode2-country/regioncode2)

The following syntax is used within templates or options:

• Labels: In the form of [[labelname]]
• Placeholders for data values: In the form of . Each template has a fixed set of placeholders.

The values of the labels can be modified by overwriting the label values in the label management of ProAuth.

Configure Password Hashing Algorithm

ProAuth provides a modular password hashing functionality for its UserStore which means that different hashing algorithms can be used side-by-side. Password hashes can be migrated to other algorithms upon a user login. Besides our standard algorithms, custom algorithms can be developed to ease the migration of UserStores from other systems.

We currently support 3 algorithms:

• AspNetCoreIdentity V2
• AspNetCoreIdentity V3
• ProAuthPasswordHasher V1

Each UserStore defines a default hasher which is used for newly created users or to upgrade existing hashes during a login. Our current system default is AspNETCoreIdentity V3. The two other algorithms indicate a "rehash needed" flag which triggers the password hash migration to the default algorithm if configured accordingly.

Password Hashing Algorithm Options

• DefaultPasswordHasher

  With this option the default password hash algorithm can be defined. By default, the most current one is always configured.

  

  Possible password hashers:

  • ProAuthPasswordHasher
    • ProAuthPasswordHasherV1
  • AspNetCoreIdentity
    • AspNetCoreIdentityV2
    • AspNetCoreIdentityV3

  For the password hasher a generic hasher (e.g. AspNetCoreIdentity) can be chosen as well as an explicit hasher (e.g. AspNetCoreIdentityV3). With a generic hasher, the latest version of this hasher is always used.

• AutomaticPasswordRehash

  

  This option defines whether a password hash that should be rehashed is automatically rehashed the next time it is used

UserStore to ProAuth synchronization (implicit SCIM synchronization)

By default, UserStore groups and users are synchronized with ProAuth users and groups (one-way only). All possible properties of groups and users are synchronized. For users, all profiles are also synchronized, for groups all metadata as well. The synchronized ProAuth groups and users are read-only, they cannot be edited. It is only possible to define ProAuth Roles or TwoFactor settings on synchronized objects.

UserStore to ProAuth synchronization can be configured via the UserStore option: ProAuthSynchronizationEnabled.

UserStore AuditTrail

By default, failed login attempts are audited in UserStore. Optionally, all successful logins to ProAuth can also be audited.

The auditing of logins can be controlled by following UserStore options:

User Store DB Deployment Worker

ProAuth provides a worker container which is able to automatically create and configure databases for newly created UserStore IDP instances. To deploy and run the DB deployment worker container, please enable it in the Helm values and configure the appropriate settings corresponding to your setup.

The DB deployment worker listens for ProAuth UserStore changed events. Either a change on an active UserStore IDP with a configured ConnectionString or the change of the ConnectionString itself triggers the worker to create the potentially missing database.

If a change event is received, the DB deployment worker performs the following steps:

• Identify the database type based on the connection string information (Azure SQL or SQL Server)
• Create the database if it does not already exist.
• Add the SQL users if they do not already exist.
• Apply the security roles to the users

User Store Password Change

The password of a user can be changed by the user as follows:

• During the login process, the user can choose to change the password which is then changed withing the login process.
• The client application may provide a password change link which takes the user to the password change page and routes him back to the application or shows a confirmation page.
• By choosing "forgot password" on the login page. The user will then receive a password reset link via e-mail if there is a validated e-mail address associated to the user.

An administrator is also able to perform the following password change operations through the admin UI:

• Send a password reset e-mail to the user
• Set a new initial password and provide the password to the user (e.g. by phone, e-mail, etc.). Since the administrator sets an initial password, the user is required to change the password on the next login.

The password change is also possible through a client application with the proper permissions. Here the logic to handle the password change safely is completely up to the client application.

Change password link

The easiest way to provide a password change functionality which is not part of the login process, is to present the user with a link to change the password.

The password change link is defined as follows:

https://<ProAuthBaseUrl>/UserStore/ChangePassword?loginName=<UserStoreUserLoginName>&tenantid=<TenantId>&idpinstanceid=<IdpInstanceId>

In addition to the required query parameters, the following optional query parameters can be added:

• clientId

  The id of the client app. This information will be used to find the proper view customization if the views are customized for a specific client application

• changePwReturnUrl

  If the password change has been successful, a confirmation page will be shown. If the changePwReturnUrl is provided, the user will be redirected to this URL without showing a confirmation page.

To simplify the usage of the password change links, the claim engine can be used to add a new claim for the identity token which contains the password change link. The claim engine rule definition is as follows:

• RuleType

  Create

• Type Transformation Replacement

  i.e. pwchangeurl

• Value Transformation Replacement

  {% if Context.IsUserStoreLogin %}https://{{ Context.Host }}/UserStore/ChangePassword?loginName={{ Context.LoginName }}&tenantid={{ Context.TenantId }}&idpinstanceid={{ Context.IdpInstanceId }}&clientid={{ Context.ClientAppId }}{% endif %}