Fix: Correct inaccurate Email as Username prerequisite for all affected versions (Product IS issue #26241)

[wso2-engineering-bot]

This PR was automatically generated by Claude AI.

Issue Details

• Issue: Correct inaccurate "Email as Username" prerequisite for email domain-based organization discovery product-is#26241
• Type: Type/Bug (Documentation)
• Issue Author: @vfraga

Summary

Corrected inaccurate documentation that incorrectly stated "Email as Username" is a mandatory prerequisite for Email Domain-Based Organization Discovery. The feature can work without it, with specific requirements for username format during user creation and different login scenarios.

Changes Made

• Removed: Incorrect statement requiring "Email as Username" feature to be enabled
• Added: Comprehensive Prerequisites section with two subsections:
  1. Username requirements during user creation
  2. Login experience scenarios (A and B)
• Clarified: Username must be in email format during user creation
• Documented: Two scenarios for login - with and without Multi-Attribute Login
• Added: Important note about existing users with non-email usernames

Affected Versions

This single change to the shared include file affects:

• IS 7.0.0
• IS 7.1.0
• IS 7.2.0

All three versions use the same include file (en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md), so one fix updates all versions.

Style Scope Verification

Microsoft Style Guidelines have been applied ONLY to newly added content without modifying existing content style unless specifically requested.

Verification

• Documentation builds successfully: mkdocs build passed
• Note: mkdocs build --strict fails due to pre-existing configuration warnings unrelated to this PR (verified on master branch)
• Changes have been validated to address all requirements specified in the issue

Summary by CodeRabbit

• Documentation
  • Expanded email domain-based organization discovery guide with detailed prerequisites, step-by-step configuration instructions, Multi-Attribute Login scenarios, and important considerations regarding domain mapping changes and their potential login implications.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

wso2-engineering-bot seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

Walkthrough

A comprehensive Prerequisites section is added to the email domain-based organization discovery guide. The addition clarifies username format requirements, Multi-Attribute Login scenarios, user creation constraints, and configuration procedures via console or API, including warnings about email domain mapping changes affecting user login access.

Changes

Cohort / File(s)	Summary
Organization Discovery Documentation en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md	Added Prerequisites section detailing username format requirements (email format with matching domain), Multi-Attribute Login configuration scenarios, and API/console-based setup procedures. Included guidance on email domain mapping implications and existing user access considerations.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

• Verify technical accuracy of Multi-Attribute Login scenarios against actual implementation
• Confirm API/console configuration steps are current and complete
• Validate warnings about email domain mapping impacts on existing users

Poem

🐰 A guide grows wise with detail and care,

Prerequisites shared, conditions laid bare,

Email domains dance, organizations align,

Discovery blooms where credentials combine! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: correcting inaccurate documentation about the Email as Username prerequisite and identifying the associated issue.
Description check	✅ Passed	The description is comprehensive and well-structured with clear sections covering purpose, changes, affected versions, and verification. However, the template sections for Test environment and Security checks are not addressed.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fixing-product-is-issue-26241-1762945462

---

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.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md (1)

36-49: Login scenarios clearly differentiate behavior based on Multi-Attribute Login configuration.

Scenario A straightforwardly describes the standard flow, while Scenario B explains the enhanced flexibility and explicitly recommends it. The important note correctly addresses the experience for existing non-email username users, which is crucial for migration paths.

However, per the PR objectives, the change goal was to clarify that "Email as Username" is not a mandatory prerequisite. Consider adding an explicit statement like: "Note: This feature does not require the 'Email as Username' capability to be enabled." This would make the fix more obvious to readers who may have encountered the previous documentation.

Optional verification: Confirm that the Multi-Attribute Login link at line 46 ({{base_path}}/guides/authentication/configure-multi-attribute-login/) is accurate and current in all supported versions (IS 7.0.0, 7.1.0, 7.2.0).

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bb37e6d and 5474f04.

📒 Files selected for processing (1)

• en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md (1 hunks)

🔇 Additional comments (2)

en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md (2)

24-49: Comprehensive Prerequisites section successfully clarifies requirements and scenarios.

The new Prerequisites section effectively communicates the key requirements for email domain-based organization discovery. The structure is logical, moving from username requirements during user creation to two distinct login scenarios based on Multi-Attribute Login configuration. The important note about existing users with non-email usernames (lines 48-49) correctly identifies a critical edge case.

---

28-34: Username requirements are clearly articulated with good use of examples.

The subsection correctly specifies that usernames must be in email format with domain matching, and importantly notes this is a strict requirement during user creation. The progressive detail (format requirement → domain matching → strict enforcement) follows a logical learning curve.