Skip to content

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

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
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

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

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
30 changes: 27 additions & 3 deletions ...-management/organization-discovery/email-domain-based-organization-discovery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,37 @@
- User Alice with email `[email protected]` should go to the login screen of `Best Car Mart` organization.
- User Bob and Ben, with emails `[email protected]` and `[email protected]` should go to the login screen of `Glory Car Mart` organization.

## Prerequisites

Before you configure email domain-based organization discovery, understand the following requirements:

### Username requirements during user creation

For any user to be discoverable by their email domain, the following requirements must be met during user creation:

Check warning on line 30 in en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[Microsoft.Passive] 'be met' looks like passive voice.

Raw Output:
{"message": "[Microsoft.Passive] 'be met' looks like passive voice.", "location": {"path": "en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md", "range": {"start": {"line": 30, "column": 88}}}, "severity": "INFO"}

Check warning on line 30 in en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[write-good.E-Prime] Try to avoid using 'be'.

Raw Output:
{"message": "[write-good.E-Prime] Try to avoid using 'be'.", "location": {"path": "en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md", "range": {"start": {"line": 30, "column": 88}}}, "severity": "INFO"}

Check warning on line 30 in en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[write-good.Passive] 'be met' may be passive voice. Use active voice if you can.

Raw Output:
{"message": "[write-good.Passive] 'be met' may be passive voice. Use active voice if you can.", "location": {"path": "en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md", "range": {"start": {"line": 30, "column": 88}}}, "severity": "WARNING"}

Check warning on line 30 in en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[write-good.E-Prime] Try to avoid using 'be'.

Raw Output:
{"message": "[write-good.E-Prime] Try to avoid using 'be'.", "location": {"path": "en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md", "range": {"start": {"line": 30, "column": 17}}}, "severity": "INFO"}

- The user's **username** must be in a valid email format (for example, `[email protected]`).

Check warning on line 32 in en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[write-good.E-Prime] Try to avoid using 'be'.

Raw Output:
{"message": "[write-good.E-Prime] Try to avoid using 'be'.", "location": {"path": "en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md", "range": {"start": {"line": 32, "column": 32}}}, "severity": "INFO"}
- The domain portion of this username (for example, `company-domain.com`) must match one of the domains configured for organization discovery.

Check warning on line 33 in en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[write-good.TooWordy] 'portion' is too wordy.

Raw Output:
{"message": "[write-good.TooWordy] 'portion' is too wordy.", "location": {"path": "en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md", "range": {"start": {"line": 33, "column": 14}}}, "severity": "WARNING"}
- This is a strict requirement during user creation. Attempting to create a user with a non-email username or a username with a non-matching domain for an organization with this feature enabled will fail.

Check warning on line 34 in en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[write-good.TooWordy] 'requirement' is too wordy.

Raw Output:
{"message": "[write-good.TooWordy] 'requirement' is too wordy.", "location": {"path": "en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md", "range": {"start": {"line": 34, "column": 20}}}, "severity": "WARNING"}

Check warning on line 34 in en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[write-good.E-Prime] Try to avoid using 'is'.

Raw Output:
{"message": "[write-good.E-Prime] Try to avoid using 'is'.", "location": {"path": "en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md", "range": {"start": {"line": 34, "column": 8}}}, "severity": "INFO"}

### Login experience

Once a user with a correctly formatted username exists, organization discovery can be triggered in two different ways:

Check warning on line 38 in en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[Microsoft.Passive] 'be triggered' looks like passive voice.

Raw Output:
{"message": "[Microsoft.Passive] 'be triggered' looks like passive voice.", "location": {"path": "en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md", "range": {"start": {"line": 38, "column": 84}}}, "severity": "INFO"}

Check warning on line 38 in en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[write-good.Passive] 'be triggered' may be passive voice. Use active voice if you can.

Raw Output:
{"message": "[write-good.Passive] 'be triggered' may be passive voice. Use active voice if you can.", "location": {"path": "en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md", "range": {"start": {"line": 38, "column": 84}}}, "severity": "WARNING"}

**Scenario A (Multi-Attribute Login disabled):**

The user enters their full username (which is in email format, for example, `[email protected]`) into the standard username field. The Identity Server detects the domain from the username, automatically discovers the organization, and then asks for the password.

**Scenario B (Multi-Attribute Login enabled):**

This provides a more flexible "identifier-first" login flow. If [Multi-Attribute Login]({{base_path}}/guides/authentication/configure-multi-attribute-login/) is enabled and `email` is an allowed attribute, the user can enter their email attribute (which may be different from their username) into the login field. The Identity Server uses this email attribute's domain to discover the organization. This is recommended for flexibility, as it allows a user's contact email attribute to change without breaking their login or discovery experience.

!!! note "Important: Existing users with non-email usernames"
Users with non-email usernames (for example, `john.smith`) who existed before this feature was configured can only use domain-based discovery if Multi-Attribute Login is enabled (Scenario B). Their username cannot be used for discovery.

Check failure on line 49 in en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md

View workflow job for this annotation

GitHub Actions / Vale style check 

[vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'can't' instead of 'cannot'.

Raw Output:
{"message": "[Microsoft.Contractions] Use 'can't' instead of 'cannot'.", "location": {"path": "en/includes/guides/organization-management/organization-discovery/email-domain-based-organization-discovery.md", "range": {"start": {"line": 49, "column": 212}}}, "severity": "ERROR"}

## Enable email domain based organization discovery

!!! note "Important"
- The root organization only permits enabling this feature and mapping email domains to organizations.
{% if product_name == "WSO2 Identity Server" %}
- For this feature to work, make sure to [enable email address as the username]({{base_path}}/guides/users/attributes/enable-email-as-username/) so that users may log in to applications with their email addresses.
{% endif %}
- **For Just-In-Time (JIT) provisioning**: Set the Subject Attribute to `http://wso2.org/claims/emailaddress` in your external identity provider. See [Map email domains to organizations](#map-email-domains-to-organizations) below.

=== "Using the Console"
Expand Down
Loading