diff --git a/en/base.yml b/en/base.yml index af3ba1ade0..6e5c9f9f8c 100644 --- a/en/base.yml +++ b/en/base.yml @@ -1,4 +1,4 @@ -# Copyright (c) 2023-2025, WSO2 LLC. (https://www.wso2.com). +# Copyright (c) 2023-2026, WSO2 LLC. (https://www.wso2.com). # # WSO2 LLC. licenses this file to you under the Apache License, # Version 2.0 (the "License"); you may not use this file except @@ -267,6 +267,8 @@ extra: icon: assets/images/sift-logo.svg Onfido: icon: assets/images/onfido-logo.svg + Password Reset Enforcer: + icon: octicons/repo-locked-16 connectors: - name: Sift diff --git a/en/identity-server/next/docs/assets/img/connectors/password-reset-enforcer/password-reset-enforcer-overview.png b/en/identity-server/next/docs/assets/img/connectors/password-reset-enforcer/password-reset-enforcer-overview.png new file mode 100644 index 0000000000..fe6aacaf6a Binary files /dev/null and b/en/identity-server/next/docs/assets/img/connectors/password-reset-enforcer/password-reset-enforcer-overview.png differ diff --git a/en/identity-server/next/docs/assets/img/logo/password-reset-enforcer-logo.svg b/en/identity-server/next/docs/assets/img/logo/password-reset-enforcer-logo.svg new file mode 100644 index 0000000000..6599b0b680 --- /dev/null +++ b/en/identity-server/next/docs/assets/img/logo/password-reset-enforcer-logo.svg @@ -0,0 +1,45 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + * + * + * + * + diff --git a/en/identity-server/next/docs/connectors/password-reset-enforcer/overview.md b/en/identity-server/next/docs/connectors/password-reset-enforcer/overview.md new file mode 100644 index 0000000000..425a2d0732 --- /dev/null +++ b/en/identity-server/next/docs/connectors/password-reset-enforcer/overview.md @@ -0,0 +1,5 @@ +--- +template: templates/connector.html +--- + +{% include "../../../../../includes/connectors/password-reset-enforcer/overview.md" %} diff --git a/en/identity-server/next/docs/connectors/password-reset-enforcer/reference.md b/en/identity-server/next/docs/connectors/password-reset-enforcer/reference.md new file mode 100644 index 0000000000..6eefdca89e --- /dev/null +++ b/en/identity-server/next/docs/connectors/password-reset-enforcer/reference.md @@ -0,0 +1,5 @@ +--- +template: templates/connector.html +--- + +{% include "../../../../../includes/connectors/password-reset-enforcer/reference.md" %} diff --git a/en/identity-server/next/docs/connectors/password-reset-enforcer/set-up.md b/en/identity-server/next/docs/connectors/password-reset-enforcer/set-up.md new file mode 100644 index 0000000000..2fca3c5747 --- /dev/null +++ b/en/identity-server/next/docs/connectors/password-reset-enforcer/set-up.md @@ -0,0 +1,5 @@ +--- +template: templates/connector.html +--- + +{% include "../../../../../includes/connectors/password-reset-enforcer/set-up.md" %} diff --git a/en/identity-server/next/docs/connectors/password-reset-enforcer/usage.md b/en/identity-server/next/docs/connectors/password-reset-enforcer/usage.md new file mode 100644 index 0000000000..7b1dbaf7c2 --- /dev/null +++ b/en/identity-server/next/docs/connectors/password-reset-enforcer/usage.md @@ -0,0 +1,5 @@ +--- +template: templates/connector.html +--- + +{% include "../../../../../includes/connectors/password-reset-enforcer/usage.md" %} diff --git a/en/identity-server/next/docs/get-started/about-this-release.md b/en/identity-server/next/docs/get-started/about-this-release.md index 36ed4723cb..1d79eb38f0 100644 --- a/en/identity-server/next/docs/get-started/about-this-release.md +++ b/en/identity-server/next/docs/get-started/about-this-release.md @@ -308,6 +308,32 @@ Administrators can define the upper limit on the number of times a user can atte Learn more about [OTP retry and resend limits]({{base_path}}/guides/authentication/conditional-auth/otp-retry-resend-limits/). +### Enhanced password expiry reset enforcement + +WSO2 Identity Server introduces two key enhancements to password expiry +reset enforcement. + +A new **Enforce password expiry for** setting is introduced to control how password expiry enforcement is applied. +This setting becomes available under **Login & Registration** > **Password Validation** when password expiry is +enabled and the password reset enforcement feature is activated via configuration. + +- **All application login flows** (default): Preserves the existing behavior. + Password expiry is enforced for every user in the organization upon login. + For applications with the Password Reset Enforcer in their login flow, + enforcement is triggered inline at the configured step and org-wide + enforcement is skipped for those applications. + +- **Selected application login flows**: Password expiry is enforced only for applications where the + Password Reset Enforcer has been explicitly added to the login flow. + +The Password Reset Enforcer now also supports app-native +authentication flows in addition to the existing redirect-based flow. +A new property is introduced in the authentication context to track the +password reset completion status, enabling adaptive authentication scripts +to conditionally control subsequent steps in the flow based on the outcome. + +Learn more about the [Password Reset Enforcer connector]({{base_path}}/connectors/password-reset-enforcer/overview/). + ## Deprecated features No features are deprecated in WSO2 Identity Server 7.3.0. diff --git a/en/identity-server/next/mkdocs.yml b/en/identity-server/next/mkdocs.yml index aa3d5034a8..e3c4318f19 100644 --- a/en/identity-server/next/mkdocs.yml +++ b/en/identity-server/next/mkdocs.yml @@ -109,6 +109,12 @@ extra: source_link: https://store.wso2.com/connector/identity-outbound-auth-naver category: authentication documentation_link: https://github.com/wso2-extensions/identity-outbound-auth-naver/blob/master/docs/README_LATEST.md + - name: Password Reset Enforcer + icon: assets/img/logo/password-reset-enforcer-logo.svg + description: Enforces password reset upon expiration as part of the application's authentication flow. + source_link: https://store.wso2.com/connector/identity-outbound-auth-passwordPolicy + category: authentication + documentation_link: password-reset-enforcer @@ -1193,6 +1199,11 @@ nav: - Usage: connectors/onfido/usage.md - Reference: connectors/onfido/reference.md - Try it: connectors/onfido/try-it.md + - Password Reset Enforcer: + - Overview: connectors/password-reset-enforcer/overview.md + - Set up: connectors/password-reset-enforcer/set-up.md + - Usage: connectors/password-reset-enforcer/usage.md + - Reference: connectors/password-reset-enforcer/reference.md - APIs: - APIs: apis/index.md - System APIs: diff --git a/en/includes/connectors/password-reset-enforcer/overview.md b/en/includes/connectors/password-reset-enforcer/overview.md new file mode 100644 index 0000000000..bc053022e9 --- /dev/null +++ b/en/includes/connectors/password-reset-enforcer/overview.md @@ -0,0 +1,21 @@ +# Password Reset Enforcer + +Password Reset Enforcer lets you enforce password reset upon expiration as part of an application's authentication flow. When a user signs in with an expired password, {{product_name}} redirects the user to the password reset screen before completing authentication. + +You can use this connector to: + +- Ensure users update passwords on a defined schedule. +- Block access to an application until the user resets an expired password. +- Apply your organization’s password validation rules during password reset. + +Configure password expiration rules from the {{product_name}} Console. For instructions, see [Password validation]({{base_path}}/guides/account-configurations/login-security/password-validation/). + +![Password Reset Enforcer overview]({{base_path}}/assets/img/connectors/password-reset-enforcer/password-reset-enforcer-overview.png) + +How it works, + +- A user starts a sign-in flow to your application. +- {{product_name}} evaluates password expiration based on your configured password expiration rules. +- If the password has expired, {{product_name}} shows the password reset screen. +- After the user resets the password successfully, {{product_name}} continues the authentication flow. + diff --git a/en/includes/connectors/password-reset-enforcer/reference.md b/en/includes/connectors/password-reset-enforcer/reference.md new file mode 100644 index 0000000000..ef8196e313 --- /dev/null +++ b/en/includes/connectors/password-reset-enforcer/reference.md @@ -0,0 +1,61 @@ +# Reference + +## Configure the event handler + +The Password Reset Enforcer relies on a background event handler that tracks password changes and determines when a user's password has expired. Add the following configuration to your `/repository/conf/deployment.toml` file to set it up. + +Password Reset Enforcer uses an event handler named `passwordExpiry`. + +```toml +[[event_handler]] +name = "passwordExpiry" +subscriptions = [ + "POST_UPDATE_CREDENTIAL", + "POST_UPDATE_CREDENTIAL_BY_ADMIN", + "POST_ADD_USER" +] + +[event_handler.properties] +passwordExpiryInDays = "30" +enableDataPublishing = false +priorReminderTimeInDays = "0" +``` + + + + + + + + + + + + + + + + + + +
PropertyDescription
passwordExpiryInDaysThe number of days after which a user's password expires.
priorReminderTimeInDaysThe reminder period in days before expiry.
enableDataPublishingEnables publishing password expiry data for analytics use cases.
+ +## Prevent password reuse + +To prevent users from reusing previous passwords, configure **Password History Count**. + +For instructions, see [Password validation]({{base_path}}/guides/account-configurations/login-security/password-validation/#password-history-count). + +## Control enforcement scope + +When you enable **Password Expiration** under **Login & Registration** > **Password Validation**, use **Enforce password expiry for** to control where password expiry enforcement applies. + +- **All application login flows** (default): Applies password expiry enforcement for all users upon sign-in. For applications that include **Password Reset Enforcer** in the login flow, enforcement happens inline at the configured step and the organization-wide enforcement is skipped for those applications. + +- **Selected application login flows**: Disables organization-wide enforcement and applies password expiry enforcement only to applications that include **Password Reset Enforcer** in the login flow. + +## Use with app-native and adaptive authentication + +Password Reset Enforcer supports API-based (App Native) authentication flows in addition to redirect-based flows. + +WSO2 Identity Server also exposes `passwordResetComplete` in the authentication context to track whether the user completed a password reset during the current authentication session. You can use this in adaptive authentication scripts to conditionally control subsequent steps based on the outcome. diff --git a/en/includes/connectors/password-reset-enforcer/set-up.md b/en/includes/connectors/password-reset-enforcer/set-up.md new file mode 100644 index 0000000000..04a3098e5a --- /dev/null +++ b/en/includes/connectors/password-reset-enforcer/set-up.md @@ -0,0 +1,62 @@ +# Set up + +The following guide explains how you can install and set up Password Reset Enforcer in {{product_name}}. + +## Prerequisites + +- A running {{product_name}} instance. +- Access to the {{product_name}} installation directory (referred to as `IS_HOME`). + +## Step 1: Install the Password Reset Enforcer connector + +1. From the WSO2 Identity Server [Connector Store](https://store.wso2.com/connector/identity-outbound-auth-passwordPolicy){: target="_blank"}, download the Password Reset Enforcer and its artifacts. + +2. Copy the `jar` file into the `/repository/components/dropins` directory of your WSO2 Identity Server installation. + +{% if is_version in ["7.0.0", "7.1.0", "7.2.0"] %} +3. Copy `pwd-reset.jsp` from the extracted artifacts package to the `/repository/deployment/server/webapps/authenticationendpoint/` directory. +{% endif %} + +## Step 2: Configure password expiry event handling + +Add the following configuration to the `IS_HOME/repository/conf/deployment.toml` file. + +```toml +[[event_handler]] +name = "passwordExpiry" +subscriptions = [ + "POST_UPDATE_CREDENTIAL", + "POST_UPDATE_CREDENTIAL_BY_ADMIN", + "POST_ADD_USER" +] + +[event_handler.properties] +passwordExpiryInDays = "30" +enableDataPublishing = false +priorReminderTimeInDays = "0" +``` + +## Step 3: Enable the authenticator + +To make the authenticator available in application step configurations, add the following configuration to the `/repository/conf/deployment.toml` file. + +```toml +[authentication.authenticator.password-reset-enforcer] +name = "password-reset-enforcer" +enable = true +``` + +{% if is_version not in ["7.0.0", "7.1.0", "7.2.0"] %} +## Step 4: Enable the enforcement scope configuration + +To make the **Enforce password expiry for** setting available in the Console, add the following configuration to the `/repository/conf/deployment.toml` file. + +```toml +[console.ui] +is_password_reset_enforcement_scope_enabled = true +``` +{% endif %} + +## Step 5: Restart {{product_name}} + +Restart {{product_name}} to apply the configuration and deploy the artifacts. diff --git a/en/includes/connectors/password-reset-enforcer/usage.md b/en/includes/connectors/password-reset-enforcer/usage.md new file mode 100644 index 0000000000..f8dac28c58 --- /dev/null +++ b/en/includes/connectors/password-reset-enforcer/usage.md @@ -0,0 +1,72 @@ +# Usage + +This guide explains how to enforce password reset upon expiry for an application using Password Reset Enforcer. + +## Prerequisites + +- [Set up Password Reset Enforcer]({{base_path}}/connectors/password-reset-enforcer/set-up/) in your {{product_name}} installation. +- Enable and configure password expiry in your organization. + + 1. On the {{product_name}} Console, go to **Login & Registration** > **Password Validation**. + 2. Enable **Password Expiration**. + 3. Select the users to whom the password expiry policy should apply using **Enforce password expiry for**. + +## Choose the password expiry enforcement scope + +When **Password Expiration** is enabled, the **Enforce password expiry for** setting controls how password expiry enforcement is applied. + +- **All application login flows** (default): Applies the password expiry policy to all users during sign-in, regardless of the application they access. For applications with **Password Reset Enforcer** in the login flow, enforcement is triggered inline at the configured step and the organization-wide enforcement is skipped for those applications. + +- **Selected application login flows**: Disables organization-wide password expiry enforcement. Enforces password expiry only when users sign in to applications that explicitly include **Password Reset Enforcer** in the login flow. + + !!! info + To enforce password expiry for a specific application, add **Password Reset Enforcer** as an authentication step in the application's login flow. + + See [Configure login flows]({{base_path}}/guides/authentication/) for instructions. + + !!! tip + By default, users are automatically signed in after they reset an expired password. + + To require users to sign in again from the beginning of the login flow, use the `passwordResetComplete` property in the authentication context of your adaptive script and call the `fail()` function. + + ```js + var onLoginRequest = function(context) { + executeStep(1, { + onSuccess: function(context) { + // Step 2: Password reset enforcer authenticator. + executeStep(2, { + onSuccess: function(context) { + var isPasswordResetComplete = context.passwordResetComplete; + if (isPasswordResetComplete === true) { + var parameterMap = {'errorCode': 'password_reset_complete', 'errorMessage': 'Your password has been successfully reset due to expiry.', "errorURI":'https://localhost:9443/authenticationendpoint/retry.do'}; + fail(parameterMap); + } + } + }); + } + }); + }; + ``` + +## Add Password Reset Enforcer to an application's login flow + +1. On the {{product_name}} Console, go to **Applications**. + +2. Select the application. + +3. Go to the **Login Flow** tab. + +4. Add **Password Reset Enforcer** as an authentication step. + +5. Click **Update** to save the changes. + +## Verify the behavior + +1. Ensure the user account has an expired password based on your configured password expiration rules. + +2. Start a sign-in flow to the application. + +3. Confirm that {{product_name}} redirects the user to the password reset screen before completing authentication. + +!!! note + Password Reset Enforcer supports both redirect-based and app-native authentication flows.