Skip to content

Add documentation for displaying the TOTP secret key during enrollment in IS 7.1 #6301

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JeethJJ wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add documentation for displaying the TOTP secret key during enrollment in IS 7.1 #6301

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added ...y-server/7.1.0/docs/assets/img/guides/mfa/totp/scan-qr-code-with-secret-key.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 5 additions & 1 deletion en/includes/guides/authentication/mfa/add-totp-login.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@
!!! note
TOTP authenticators use the [TOTP specification](https://datatracker.ietf.org/doc/html/rfc6238){:target="_blank"} to calculate access tokens based on the current time and the secret key shared between the user and the identity provider.

## Prerequisites

Check failure on line 14 in en/includes/guides/authentication/mfa/add-totp-login.md

View workflow job for this annotation

GitHub Actions / lint

Headings should be surrounded by blank lines 

en/includes/guides/authentication/mfa/add-totp-login.md:14 MD022/blanks-around-headings Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "## Prerequisites"] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md022.md
- To get started, you need to [register an application with {{ product_name }}]({{base_path}}/guides/applications/). You can register your own application or use one of the [sample applications]({{base_path}}/get-started/try-samples/) provided.

Check failure on line 15 in en/includes/guides/authentication/mfa/add-totp-login.md

View workflow job for this annotation

GitHub Actions / lint

Lists should be surrounded by blank lines 

en/includes/guides/authentication/mfa/add-totp-login.md:15 MD032/blanks-around-lists Lists should be surrounded by blank lines [Context: "- To get started, you need to ..."] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md032.md

- Download and install one of the authenticator apps mentioned above.

Expand Down Expand Up @@ -95,7 +95,7 @@

!!! note "Enable enrolling in TOTP at first login"
To enable enrolling in TOTP the first time a user logs in, use any of the following approaches:

Check failure on line 98 in en/includes/guides/authentication/mfa/add-totp-login.md

View workflow job for this annotation

GitHub Actions / lint

Trailing spaces 

en/includes/guides/authentication/mfa/add-totp-login.md:98:1 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 10] https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md009.md
- Update the value of `enrolUserInAuthenticationFlow` parameter to `true`.
```js
var enrolUserInAuthenticationFlow = "true";
Expand All @@ -104,7 +104,7 @@

4. Click **Update** to save your changes.

{% if product_name == "WSO2 Identity Server" and is_version == "7.2.0" %}
{% if product_name == "WSO2 Identity Server" and (is_version == "7.2.0" or is_version == "7.1.0") %}

## Display the secret key during enrollment

Expand All @@ -118,7 +118,11 @@
```

!!! note
{% if is_version == "7.2.0" %}
This configuration is available from update level **7.2.0.27** onwards.
{% elif is_version == "7.1.0" %}

Check warning on line 123 in en/includes/guides/authentication/mfa/add-totp-login.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
Did you really mean 'elif'?

Raw Output:
{"message":"Did you really mean 'elif'?","location":{"path":"en/includes/guides/authentication/mfa/add-totp-login.md","range":{"start":{"line":123,"column":4},"end":{"line":123,"column":8}}},"severity":"WARNING","code":{"value":"Vale.Spelling"}}
This configuration is available from update level **7.1.0.100** onwards.

Check warning on line 124 in en/includes/guides/authentication/mfa/add-totp-login.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
Did you really mean 'onwards'?

Raw Output:
{"message":"Did you really mean 'onwards'?","location":{"path":"en/includes/guides/authentication/mfa/add-totp-login.md","range":{"start":{"line":124,"column":69},"end":{"line":124,"column":76}}},"severity":"WARNING","code":{"value":"Vale.Spelling"}}
{% endif %}
Comment on lines +121 to +125

@coderabbitai coderabbitai Bot Aug 4, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Files matching target/name:"
fd -a 'add-totp-login\.md$|Vale|vale' . | sed 's#^\./##' | head -100

echo
echo "Target excerpt:"
FILE="en/includes/guides/authentication/mfa/add-totp-login.md"
if [ -f "$FILE" ]; then
  sed -n '110,130p' "$FILE" | nl -ba -v110
else
  echo "target file not found"
fi

echo
echo "Search for Vale configuration:"
fd -a 'Vale|vale|\.vale|_vale|vocabulary|accept\.txt' . | sed 's#^\./##' | head -200

echo
echo "Search for is_version directives/templates:"
rg -n "is_version|{% if|{% elif|{% endif|" . -g '*.md' | head -200

Repository: wso2/docs-is

Length of output: 1910

🌐 Web query:

Vale linter conditional directives ignore {% if elif endif {% raw %}

💡 Result:

To ignore template-based conditional directives (such as {% if %}, {% elif %}, {% endif %}) in Vale, you can use the TokenIgnores configuration option in your.vale.ini file [1][2]. Because these directives are typically inline-level patterns, TokenIgnores is the appropriate mechanism to prevent Vale from linting their content [2]. Add the following to your.vale.ini file to ignore these tags: [.md] TokenIgnores = ({%.+?%}) Explanation: 1. TokenIgnores: This configuration accepts a list of regular expressions that match the tokens you wish to exclude from linting [1][2]. The pattern ({%.+?%}) captures Liquid-style or template-style tags starting with {% and ending with %} [1]. 2. Scope: You can apply this to specific file formats (like [.md] or [.mdx]) to ensure it only runs where those directives exist [1][3]. 3. BlockIgnores: If your directives span multiple lines or wrap large blocks of text that you want to ignore entirely, use BlockIgnores with a multiline regex (using the (?s) flag) [4][1]. For example: BlockIgnores = (?s){% if.? %}.*?{% endif %} Additionally, if you need to ignore these sections only in specific parts of a document, you can use inline comment controls within your source file [5][6]: {% if condition %}... some content to ignore... {% endif %} This turns off linting entirely for the duration of the block [5]. Ensure you have the proper comment syntax enabled for your specific file format [7][3].

Citations:

🌐 Web query:

Vale linter token ignores value {%if.*?%} regex parentheses

💡 Result:

In Vale, the TokenIgnores configuration allows you to exclude inline-level text patterns from being linted [1][2]. To correctly ignore patterns that include special characters like parentheses or braces (such as {%... %}), you must define a regular expression that captures the entire token within the first grouping [1][2][3]. For patterns like {%... %}, you can use the following configuration in your.vale.ini file: [*.md] TokenIgnores = ({%.+?%}) Key considerations for using TokenIgnores: 1. Capture Groups: The regex must capture the entire desired ignore-string in the first capture group [1][3]. 2. Format Support: TokenIgnores are only supported for markup formats that are converted to HTML (e.g., Markdown, reStructuredText, AsciiDoc, and Org Mode) [1][2][4]. 3. Special Characters: If your pattern contains characters that have special meaning in regex, such as curly braces or dollar signs, you must escape them (e.g., {, }, $) or ensure the pattern is accurately defined to match the literal characters [3][5]. 4. Embedded Formats: If you are trying to use TokenIgnores in a file type that is not natively supported (like.js or.jl), you must first assign an embedded markup format (e.g., [formats] js = md) in your configuration for the ignores to take effect [6][4][7]. If your regex seems to have no effect, ensure that the file format is correctly recognized and supported, and verify your capture group matches the intended token entirely [6][4][8].

Citations:

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "Target excerpt:"
FILE="en/includes/guides/authentication/mfa/add-totp-login.md"
if [ -f "$FILE" ]; then
  sed -n '110,130p' "$FILE" | nl -ba -v110
else
  echo "target file not found"
fi

echo
echo "Locate Vale configs/vocab files:"
for name in .vale.ini .vale/_styles/ .vale/styles/ vale.ini; do
  if [ -e "$name" ]; then
    echo "FOUND: $name"
  fi
done
find . -maxdepth 4 \( -name '.vale.ini' -o -path '*/.vale/styles*' -o -path '*/.vale/_styles*' -o -name 'vocab*' -o -name 'accept.txt' \) -print 2>/dev/null | head -200

Repository: wso2/docs-is

Length of output: 1910

Resolve the remaining Vale warning in the availability note.

Configure Vale to ignore template directives or add elif to the accepted vocabulary. Replace onwards with and later, then run vale en/includes/guides/authentication/mfa/add-totp-login.md with no warnings.

🧰 Tools
🪛 GitHub Check: Vale style check

[warning] 124-124:
[vale] reported by reviewdog 🐶
Did you really mean 'onwards'?

Raw Output:
{"message":"Did you really mean 'onwards'?","location":{"path":"en/includes/guides/authentication/mfa/add-totp-login.md","range":{"start":{"line":124,"column":69},"end":{"line":124,"column":76}}},"severity":"WARNING","code":{"value":"Vale.Spelling"}}

[warning] 123-123:
[vale] reported by reviewdog 🐶
Did you really mean 'elif'?

Raw Output:
{"message":"Did you really mean 'elif'?","location":{"path":"en/includes/guides/authentication/mfa/add-totp-login.md","range":{"start":{"line":123,"column":4},"end":{"line":123,"column":8}}},"severity":"WARNING","code":{"value":"Vale.Spelling"}}

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@en/includes/guides/authentication/mfa/add-totp-login.md` around lines 121 -
125, Update the availability note in the is_version template block to use “and
later” instead of “onwards,” and configure Vale to accept the template
directives or add “elif” to its vocabulary. Run Vale against add-totp-login.md
and ensure it completes without warnings.

Sources: Coding guidelines, Linters/SAST tools


When enabled, users will see the secret key alongside the QR code during TOTP enrollment:

Expand Down
Loading