Add org level configuration details for TOTP enrollment

[LinukaAr]

Purpose

$subject

Related PRs

• Add org level config to govern TOTP enrolment in the user login wso2-extensions/identity-outbound-auth-totp#225
• Add Organization Level TOTP Enrollment Configuration UI identity-apps#9494

Security checks

• Followed secure coding standards in http://wso2.com/technical-reports/wso2-secure-engineering-guidelines
• Ran FindSecurityBugs plugin and verified report?
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets?

Summary by CodeRabbit

• Documentation
  • Expanded TOTP enrollment configuration guidance with organization-level and application-level configuration pathways
  • Added step-by-step instructions for configuring default policies and conditional authentication overrides
  • Clarified enrollment behavior and recovery options across different configuration levels

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

The documentation for TOTP enrollment is expanded with two configuration pathways: organization-level default policy and application-level conditional authentication override. A negative bulleted statement is converted to an affirmative sentence, and detailed step-by-step instructions with UI paths, toggle names, and code snippets are added for both configuration methods.

Changes

Cohort / File(s)

Summary

TOTP Login Documentation en/includes/guides/authentication/mfa/add-totp-login.md

Expanded documentation for TOTP enrollment configuration. Converted default statement from bulleted negative to affirmative format. Added organization-level configuration pathway with UI navigation and toggle settings. Added application-level configuration pathway via Conditional Authentication with authentication script guidance and code snippets. Clarified when TOTP enrollment can be enabled or disabled with related recovery guidance.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 Two pathways through the TOTP maze,
Organization and app ablaze,
Clear instructions light the way,
Security's stronger every day,
Configuration made crystal bright,
Hopping forward, all feels right! ✨🔐

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The PR description includes Purpose, Related PRs, and completed Security checks sections matching the template. However, the 'Test environment' section is entirely missing, and the Purpose section contains only '$subject' as a placeholder rather than an actual description.	Complete the Purpose section with an actual description instead of '$subject' and add the missing 'Test environment' section listing relevant JDK versions, operating systems, databases, and browsers tested.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add org level configuration details for TOTP enrollment' clearly and specifically describes the main change: adding organization-level configuration documentation for TOTP enrollment.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

🧹 Recent nitpick comments

en/includes/guides/authentication/mfa/add-totp-login.md (1)

32-39: Consider clarifying the precedence between configuration levels.

The documentation clearly introduces two configuration pathways. However, it would be helpful to explicitly state the precedence when both org-level and app-level configurations are set. For example, adding a sentence like: "Application-level settings override organization-level settings when both are configured."

📝 Suggested addition for clarity

 {{ product_name }} provides two ways to control this enrollment behavior:

 - **Organization-level configuration**: Define a default policy that applies across all applications in the organization.
 - **Application-level configuration**: Override the organization-level setting for specific applications using conditional authentication scripts.
+
+Application-level settings take precedence over organization-level settings when both are configured.

 !!! note
     The organization-level configuration is available for both root organizations and sub-organizations.

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 339953d and 0ca8d20.

⛔ Files ignored due to path filters (1)

• en/asgardeo/docs/assets/img/guides/mfa/totp/totp-org-level-config.png is excluded by !**/*.png

📒 Files selected for processing (1)

• en/includes/guides/authentication/mfa/add-totp-login.md

🔇 Additional comments (5)

en/includes/guides/authentication/mfa/add-totp-login.md (5)

30-30: LGTM: Clearer affirmative statement.

The change from a negative bulleted statement to a plain affirmative sentence improves readability and clearly establishes the default behavior.

---

57-96: LGTM: Well-structured application-level configuration with clear examples.

The application-level configuration section provides:

• Clear step-by-step instructions
• Properly structured JavaScript authentication script
• Helpful notes about step configuration and how to enable enrollment
• Good use of code snippets and formatting

The script correctly demonstrates disabling enrollment (matching the section title), while the note provides guidance for the opposite scenario.

---

108-108: LGTM: Section reference is correct.

The anchor reference correctly links to the section "Disable enrolling in TOTP during first login" defined at line 28.

---

123-123: LGTM: Minor formatting adjustment.

The line formatting is correct within the note block context.

---

40-56: The referenced image file exists and is properly available in the repository at en/asgardeo/docs/assets/img/guides/mfa/totp/totp-org-level-config.png. The image reference is valid.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}