Password change and initial credentials

UserStore supports user-initiated password change, password reset, required change at sign-in, and administrator-created initial passwords. Every new or replacement password is validated by the effective server policy.

Why the workflow matters

Changing a credential affects more than the password hash. A secure workflow must verify the actor, enforce current policy, advance authentication security state, revoke affected sessions and renewable grants, and notify the user. A client application should not reproduce this logic locally.

For new onboarding, prefer unified invitations with user-controlled password or passkey enrollment. An administrator-created initial password remains available for compatibility, but the administrator necessarily knows that temporary credential and must deliver it through a protected channel.

Available journeys

Journey	When to use it	Security behavior
Account Management password change	The signed-in UserStore user knows the current password.	Derives the target user from the session, validates the old password and new policy, advances security state, and applies revocation.
Required change during sign-in	The password is initial, expired with change permitted, or marked for replacement.	No ordinary authorization result is issued until the change completes.
Forgot password	The user cannot supply the current password and has an eligible verified recovery route.	Uses a hashed, expiring, single-use recovery artifact and durable delivery.
Invitation enrollment	A new user is onboarding.	The user creates the initial credential inside a restricted bootstrap journey; activation waits for all invitation requirements.
Administrator-created initial password	A legacy integration requires a temporary credential.	Marks the password as initial and requires replacement. Use only with a short expiry and a protected delivery process.

Passwordless policy remains authoritative. If PasskeyPasswordRecreationPolicy prohibits password recreation, reset, initial-password, and self-service routes cannot be used to bypass it.

Account Management

UserStore users can change their password from /account/security. The action is available only when password use is permitted and the current password state supports a normal change.

The portal obtains password requirements from the effective v2 policy. Browser validation improves guidance, but the server reevaluates the complete password. See Password policy and recovery security.

Standalone password-change link

A relying application can link to the built-in change page:

https://<proauth-domain>/UserStore/ChangePassword?loginName=<login-name>&tenantid=<tenant-id>&idpinstanceid=<idp-instance-id>

Optional query parameters are:

• clientId — selects client-specific view customization;
• changePwReturnUrl — redirects after success when the destination is valid for the request context.

Do not construct an arbitrary return destination from untrusted input. ProAuth validates the URL, but the application should still use registered, predictable destinations.

The claim engine can publish a password-change URL to an application. For example:

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

Initial-password options

Option	Purpose
InitialPasswordExpirationInSeconds	Default validity of an administrator-created initial password.
PasswordChangeEnabled	Enables the built-in password-change journey for the UserStore IDP instance.
UserPasswordExpirationInSeconds	Legacy password-age limit for normal user passwords. Use 0 or the documented disabled value when periodic expiration is not required.
AutomaticPasswordRehash	Rehashes a successfully verified password when its format or parameters are obsolete.

Avoid periodic password expiration unless a regulation or confirmed compromise requires it. Forced periodic changes tend to produce predictable variations and do not replace compromise detection, MFA, passkeys, or abuse controls.

Password reset

When PasswordResetByEmailEnabled is enabled, the forgot-password page uses an active verified contact with the PasswordRecovery purpose. PasswordResetTokenExpirationInSeconds controls the reset artifact lifetime; mail subject and body options control the notification template.

The response does not reveal whether the account or eligible contact exists. Reset completion consumes the artifact atomically, advances the UserStore authentication-security epoch, invalidates incompatible recovery artifacts, and revokes dependent authentication state.

For the complete security model, see Password policy and recovery security and Verified security contacts.

Administrative guidance

• Prefer invitation, temporary access pass, or recovery workflows over communicating an administrator-chosen password.
• Never send an initial password and its login name in the same unprotected channel.
• Set a short initial-password expiry and require change at the next sign-in.
• Do not set verified contact state through generic user update operations.
• Treat password reset after a recent contact change as a high-risk event.
• Monitor reset requests, delivery failures, replay rejection, policy failures, rehash duration, and revocation completion.

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

Manage a User Store account in the React AdminApp

Select the intended User Store before opening a user. This record owns the local sign-in account. The corresponding ProAuth user owns the identity presented to applications and its ProAuth roles and MFA configuration.

Tab	Configuration and workflow
General	Edit login name, first and last name, and email address. Keep email confirmation beside the address and verify ownership before marking it confirmed. The record ID is read-only.
Security	Configure account activation and validity dates, then inspect permanent and temporary lockout diagnostics.
Credentials	Configure password expiration and inspect initial-password/change-required status.
Membership	Manage membership in local User Store groups.
Profiles	Manage additional local profile attributes.

Sign-in requires an active account and a current time inside the validity interval. Either date may be empty for an unbounded interval on that side. Validity dates remain editable while the account is inactive so an operator can prepare reactivation.

Account validity and password expiration use UTC. A date selected in the AdminApp represents midnight UTC on that date, independent of the display language or server timezone. In User Store API v2 create, update, and patch requests, timestamps with an explicit offset are converted to UTC; date-only values and timestamps without an offset are interpreted as UTC. These rules apply to both SQL Server and PostgreSQL storage.

Enable permanent lockout combines with the provider’s failed-attempt threshold. Temporary lockout has separate provider options. Disabling permanent lockout does not clear an existing lock or disable temporary protection. The permanent lock flag, failed-login counter, temporary-lock expiry and temporary-lock counter are read-only diagnostics. The expiry displays its full stored timestamp so a short temporary lock can be distinguished from one lasting all day. A future temporary-lock expiry can block sign-in even when the permanent flag is off. See Brute-force protection for provider thresholds.

Password never expires bypasses password expiration. The expiration date and permission to change a password after expiration remain visible but disabled while this option is selected; toggling it preserves their form values. With the option off, a date limits the password’s lifetime and an empty date has no expiration. Initial-password change requirements continue to apply regardless of expiration policy.

Set initial password operates immediately on the saved account. It sets the initial-password and change-required flags, clears lockout state and counters, and derives expiration from the provider’s initial-password lifetime unless the saved account is configured never to expire passwords. Save pending account changes before using this action. Neither the status flags nor counters can be set through the normal account Save command.

Changing the legacy email confirmation flag does not send a verification message. Password reset prefers an active, verified security contact authorized for password recovery; the confirmed account email remains a compatibility fallback when no eligible security contact exists. Review recovery contacts and the confirmation flag when changing an address.