From 9393ea5dbcf020e021abd7a24882f9783f1f3b63 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 27 Sep 2025 18:32:53 +0000 Subject: [PATCH 1/3] Initial plan From 22a634968c14482a1b8759759150066d7e688ce6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 27 Sep 2025 18:43:25 +0000 Subject: [PATCH 2/3] Add TOTP configuration documentation for WSO2 IS 7.1.0 Co-authored-by: pavinduLakshan <41533942+pavinduLakshan@users.noreply.github.com> --- .../mfa/totp-config-advanced.md | 145 ++++++++++++++++++ en/identity-server/7.1.0/mkdocs.yml | 2 +- 2 files changed, 146 insertions(+), 1 deletion(-) create mode 100644 en/identity-server/7.1.0/docs/guides/authentication/mfa/totp-config-advanced.md diff --git a/en/identity-server/7.1.0/docs/guides/authentication/mfa/totp-config-advanced.md b/en/identity-server/7.1.0/docs/guides/authentication/mfa/totp-config-advanced.md new file mode 100644 index 0000000000..305eacc6aa --- /dev/null +++ b/en/identity-server/7.1.0/docs/guides/authentication/mfa/totp-config-advanced.md @@ -0,0 +1,145 @@ +# TOTP configurations + +This page lists all the advanced configurations related to TOTP (Time-based One-Time Password) authentication. + +## Default TOTP configuration + +The following code snippet shows a sample TOTP configuration in the `/repository/conf/deployment.toml` file: + +```toml +[authentication.authenticator.totp.parameters] +encodingMethod="Base32" +timeStepSize="30" +windowSize="3" +authenticationMandatory=true +enrolUserInAuthenticationFlow=true +usecase="local" +secondaryUserstore="primary" +TOTPAuthenticationEndpointURL="authenticationendpoint/totp.do" +TOTPAuthenticationEndpointErrorPage="authenticationendpoint/totp_error.do" +TOTPAuthenticationEndpointEnableTOTPPage="authenticationendpoint/totp_enroll.do" +Issuer="WSO2" +UseCommonIssuer=true +``` + +The parameter values above show the **default** configurations in WSO2 Identity Server. + +## Update TOTP configuration + +To change a parameter value from the default value, add the configuration to the `deployment.toml` file using the following format: + +```toml +[authentication.authenticator.totp.parameters] + = +``` + +## Configuration parameters + +Learn about each TOTP configuration parameter and how to customize them. + +### encodingMethod + +**Description:** The encoding method used to generate the TOTP. + +**Default value:** `Base32` + +--- + +### timeStepSize + +**Description:** The time step size (in seconds) used to validate the TOTP. + +**Default value:** `30` + +--- + +### windowSize + +**Description:** The window size used to validate the TOTP. This determines how many time steps before and after the current time step are accepted. + +**Default value:** `3` + +--- + +### authenticationMandatory + +**Description:** If this value is `true`, TOTP authentication will be enforced as a second step. + +**Default value:** `true` + +--- + +### enrolUserInAuthenticationFlow + +**Description:** If this value is `true`, it will ask users to enable the TOTP authenticator during the authentication flow. + +**Default value:** `true` + +--- + +### usecase + +**Description:** This field can take one of the following values: `local`, `association`, `userAttribute`, `subjectUri`. If you do not specify any usecase, the default value is `local`. + +**Default value:** `local` + +If you choose `userAttribute` as the usecase, add the following parameter to specify the user attribute: + +```toml +userAttribute = "http://wso2.org/foursquare/claims/email" +``` + +--- + +### secondaryUserstore + +**Description:** If you use secondary user stores, enter all the user store values for the particular tenant as comma-separated values. + +**Default value:** `primary` + +**Example:** + +```toml +[authentication.authenticator.totp.parameters] +secondaryUserstore= "jdbc, abc, xyz" +``` + +--- + +### TOTPAuthenticationEndpointURL + +**Description:** The endpoint of the UI used to gather the TOTP. + +**Default value:** `authenticationendpoint/totp.do` + +--- + +### TOTPAuthenticationEndpointErrorPage + +**Description:** The endpoint of the error page. + +**Default value:** `authenticationendpoint/totp_error.do` + +--- + +### TOTPAuthenticationEndpointEnableTOTPPage + +**Description:** The endpoint of the TOTP authenticator enrollment page. + +**Default value:** `authenticationendpoint/totp_enroll.do` + +--- + +### Issuer + +**Description:** The issuer name that will be shown on the mobile authenticator application. If this parameter is not configured, the tenant domain will be shown. + +**Default value:** `WSO2` + +--- + +### UseCommonIssuer + +**Description:** If set to `true`, the issuer name defined in the `deployment.toml` file will be used as the issuer for all tenants. + +**Default value:** `true` diff --git a/en/identity-server/7.1.0/mkdocs.yml b/en/identity-server/7.1.0/mkdocs.yml index def4e03441..2416244ceb 100644 --- a/en/identity-server/7.1.0/mkdocs.yml +++ b/en/identity-server/7.1.0/mkdocs.yml @@ -153,7 +153,6 @@ plugins: "guides/mfa/2fa-fido.md": "guides/authentication/mfa/add-passkey-login.md" "guides/mfa/x509.md": "guides/authentication/mfa/add-x509-login.md" "guides/mfa/email-otp-config-advanced.md": "guides/authentication/mfa/add-emailotp-login.md" - "guides/mfa/totp-config-advanced.md": "guides/authentication/mfa/add-totp-login.md" "guides/mfa/sms-otp-config-advanced.md": "guides/authentication/mfa/add-smsotp-login.md" "guides/adaptive-auth/configure-adaptive-auth.md": "guides/authentication/conditional-auth/index.md" "guides/adaptive-auth/adaptive-auth-overview.md": "guides/authentication/conditional-auth/configure-conditional-auth.md" @@ -513,6 +512,7 @@ nav: - Add multi-factor authentication: - Add multi-factor authentication: guides/authentication/mfa/index.md - Add TOTP: guides/authentication/mfa/add-totp-login.md + - TOTP configurations: guides/authentication/mfa/totp-config-advanced.md - Add Email OTP: guides/authentication/mfa/add-emailotp-login.md - Add Passkey: guides/authentication/mfa/add-passkey-login.md - Add SMS OTP: guides/authentication/mfa/add-smsotp-login.md From cb3318eb0bcd314b967c06f81435cc3e33e1fede Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 28 Sep 2025 11:46:24 +0000 Subject: [PATCH 3/3] Remove redundant default values and description prefixes from TOTP configuration parameters Co-authored-by: pavinduLakshan <41533942+pavinduLakshan@users.noreply.github.com> --- .../mfa/totp-config-advanced.md | 48 +++++-------------- 1 file changed, 12 insertions(+), 36 deletions(-) diff --git a/en/identity-server/7.1.0/docs/guides/authentication/mfa/totp-config-advanced.md b/en/identity-server/7.1.0/docs/guides/authentication/mfa/totp-config-advanced.md index 305eacc6aa..cffdfeed3c 100644 --- a/en/identity-server/7.1.0/docs/guides/authentication/mfa/totp-config-advanced.md +++ b/en/identity-server/7.1.0/docs/guides/authentication/mfa/totp-config-advanced.md @@ -39,49 +39,37 @@ Learn about each TOTP configuration parameter and how to customize them. ### encodingMethod -**Description:** The encoding method used to generate the TOTP. - -**Default value:** `Base32` +The encoding method used to generate the TOTP. --- ### timeStepSize -**Description:** The time step size (in seconds) used to validate the TOTP. - -**Default value:** `30` +The time step size (in seconds) used to validate the TOTP. --- ### windowSize -**Description:** The window size used to validate the TOTP. This determines how many time steps before and after the current time step are accepted. - -**Default value:** `3` +The window size used to validate the TOTP. This determines how many time steps before and after the current time step are accepted. --- ### authenticationMandatory -**Description:** If this value is `true`, TOTP authentication will be enforced as a second step. - -**Default value:** `true` +If this value is `true`, TOTP authentication will be enforced as a second step. --- ### enrolUserInAuthenticationFlow -**Description:** If this value is `true`, it will ask users to enable the TOTP authenticator during the authentication flow. - -**Default value:** `true` +If this value is `true`, it will ask users to enable the TOTP authenticator during the authentication flow. --- ### usecase -**Description:** This field can take one of the following values: `local`, `association`, `userAttribute`, `subjectUri`. If you do not specify any usecase, the default value is `local`. - -**Default value:** `local` +This field can take one of the following values: `local`, `association`, `userAttribute`, `subjectUri`. If you do not specify any usecase, the default value is `local`. If you choose `userAttribute` as the usecase, add the following parameter to specify the user attribute: @@ -93,9 +81,7 @@ userAttribute = "http://wso2.org/foursquare/claims/email" ### secondaryUserstore -**Description:** If you use secondary user stores, enter all the user store values for the particular tenant as comma-separated values. - -**Default value:** `primary` +If you use secondary user stores, enter all the user store values for the particular tenant as comma-separated values. **Example:** @@ -108,38 +94,28 @@ secondaryUserstore= "jdbc, abc, xyz" ### TOTPAuthenticationEndpointURL -**Description:** The endpoint of the UI used to gather the TOTP. - -**Default value:** `authenticationendpoint/totp.do` +The endpoint of the UI used to gather the TOTP. --- ### TOTPAuthenticationEndpointErrorPage -**Description:** The endpoint of the error page. - -**Default value:** `authenticationendpoint/totp_error.do` +The endpoint of the error page. --- ### TOTPAuthenticationEndpointEnableTOTPPage -**Description:** The endpoint of the TOTP authenticator enrollment page. - -**Default value:** `authenticationendpoint/totp_enroll.do` +The endpoint of the TOTP authenticator enrollment page. --- ### Issuer -**Description:** The issuer name that will be shown on the mobile authenticator application. If this parameter is not configured, the tenant domain will be shown. - -**Default value:** `WSO2` +The issuer name that will be shown on the mobile authenticator application. If this parameter is not configured, the tenant domain will be shown. --- ### UseCommonIssuer -**Description:** If set to `true`, the issuer name defined in the `deployment.toml` file will be used as the issuer for all tenants. - -**Default value:** `true` +If set to `true`, the issuer name defined in the `deployment.toml` file will be used as the issuer for all tenants.