Email domain based organization discovery

In Business-to-Business (B2B) applications, seamlessly authenticating users from external organizations remains essential. This ensures a smooth user experience.

One way to achieve this involves email domain-based organization discovery. With this feature, your application can provide a customized login experience. The experience depends on the domain of the user's email address.

For example, when users log in with an @xyz.com email address, the system automatically redirects them to the login screen customized for the XYZ organization. This provides a familiar and consistent experience.

This guide explains how you may use WSO2 Identity Server to configure email domain-based organization discovery for your B2B applications.

Scenario

Guardio Insurance serves as an insurance provider. Best Car Mart and Glory Car Mart represent two of its customer organizations.

When a user enters an email address to log into the Guardio Insurance platform, the system needs to resolve the user's organization. It does this based on the email domain. Then it redirects them to the respective organization's login screen.

In this example scenario:

• 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:

• The user's username must be in a valid email format (for example, [email protected]).
• The domain part of this username (for example, company-domain.com) must match one of the domains configured for organization discovery.
• 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.

Enable email domain based organization discovery

Important

• The root organization only permits enabling this feature and mapping email domains to organizations.
• 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 below.

Using the ConsoleUsing the API

To do so,

1. Login to the root organization Console.
2. Navigate to Login & Registration, and under Organization Settings, click Organization Discovery.

3. Turn the toggle on to enable email domain based organization discovery.

   

4. Select the Email domain discovery for self-registration checkbox if you want to allow users to discover organizations based on their email domain and self-register in them.

   Note

   For this to work, child organizations should have self-registration enabled. Currently, you can enable self-registration for all child organizations by adding the following configuration to the <IS_HOME>/repository/conf/deployment.toml file.

   [identity_mgt.user_self_registration]
   allow_self_registration = true
   

5. Map email domains to organizations.

To do so,

1. Get an access token with the internal_organization_config_add scope.

2. Use the obtained access token to execute the following command.

   curl --location --request POST 'https://localhost:9443/api/server/v1/organization-configs/discovery' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer <access_token>' \
   --data '{
       "properties": [
           {
               "key": "emailDomain.enable",
               "value": true
           }
       ]
   }'
   

3. Map email domains to organizations.

Map email domains to organizations

When you map an email domain to an organization, the organization's behavior changes as follows:

• A user can only onboard to the organization if the user's email domain matches one of the domains claimed by the organization.

• The system restricts federated authentication and Just-In-Time (JIT) provisioning for users logging in with email domains not claimed by the organization.

  Map subject attribute for JIT provisioning and federated authentication

  In OIDC and SAML applications, the subject uniquely identifies the user.

  If your organization uses email domain-based organization discovery, make sure to map the subject attribute correctly as explained below:

  • Set the email attribute as the subject attribute i.e. http://wso2.org/claims/emailaddress.
  • Map the email attribute from the external identity provider to the same WSO2 claim: http://wso2.org/claims/emailaddress.

  Why this matters: Domain-based organization discovery relies on email addresses to identify organizations. Mapping the subject attribute to the email claim ensures smooth federated authentication and Just-in-Time (JIT) provisioning creates and updates users correctly.

  Learn more about selecting selecting the subject attribute for OIDC applications and selecting the subject attribute for SAML applications.

• If not, a user can register to the organization with an email address of any domain (other than the domains claimed by other organizations).

Using the ConsoleUsing the API

Before you begin

• Enable email domain based organization discovery for the root organization.
• Create the required organizations under the root organization. See Manage organizations for instructions.

To do so,

1. On the WSO2 Identity Server Console, go to Login & Registration.
2. Under Organization Settings, click Email Domain Discovery.

3. Click Assign Email Domain.

   

4. Under Organization Name, select the organization.

5. Under Email Domains, type the email domain you want to claim for the selected organization and press enter. You can add more than one email domain.

   

6. Click Assign.

Before you begin

• Enable email domain based organization discovery for the root organization.
• Create the required organizations under the root organization. See Manage organizations for instructions.

To do so,

1. Get an access token with the internal_organization_discovery_update scope.

2. Use the obtained access token to execute the following cURL.

   curl --location --request POST 'https://localhost:9443/api/server/v1/organizations/discovery' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer <access_token>' \
   --data '{
       "attributes": [
           {
               "type": "emailDomain",
               "values": [
                   "bcmart.com"
               ]
           }
       ],
       "organizationId": "<organization-id>"
   }'
   

Update email domain mappings

Warning

Changing the email domain mappings may prevent existing users from logging in to the B2B applications due to organization discovery failures.

Using the ConsoleUsing the API

To do so,

1. On the WSO2 Identity Server Console, go to Login & Registration,
2. Under Organization Settings, click Email Domain Discovery.

3. Click Edit of the organization you want to update the email domains.

   

4. Update the email domains in Email Domains and click Update.

To do so,

1. Get an access token with the internal_organization_discovery_update scope.

2. Use the obtained access token to execute the following cURL.

   curl --location --request PUT 'https://localhost:9443/api/server/v1/organizations/<organization-id>/discovery' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer <access_token>' \
   --data '{
       "attributes": [
           {
               "type": "emailDomain",
               "values": [
                   "bcmart.com",
                   "bestcars.com"
              ]
           }
       ]
   }'
   

Try it out

Follow the sections below to try out each of the organization discovery scenarios.

User login

To try out user login,

1. Set up the Guardio business application by following the B2B setup steps.

2. Create an organization for Best Car Mart by following the organization creation guide.

3. Follow the guides in this page and enable email domain based organization discovery. Add the following email domain mapping.

   • Organization Name: Best Car Mart
   • Email Domain: bcmart.com

4. On the WSO2 Identity Server Console, switch to the Best Car Mart organization Console.

5. Onboard a new user to the Best Car Mart organization with the following information. You can either set a password for the user or invite the user to set the password.

   Username and Email	A unique email address to identify the user. [email protected]
   First Name	First name of the user. Alice
   Last Name	Last name of the user. Charlotte

6. Log in to the Guardio business app by selecting Sign In With Single Sign-On (SSO).

   Note

   You can bypass the Sign In With SSO page and go directly to your organization's login page by adding the following query parameters in the login request.

   • login_hint: The email address of the user that will be used to resolve the domain.
   • fidp: If you have additional B2C login options configured for the application, you can set this parameter to OrganizationSSO to direct users straight to the organization login page.

   Sample requests:

   OIDCSAML

   https://localhost:9443/oauth2/authorize?
   client_id=<client_id>
   &redirect_uri=<redirect_url>
   &scope=<scopes>
   &response_type=code
   &login_hint=<user_email>
   &fidp=OrganizationSSO
   

   https://localhost:9443/samlsso?
   spEntityID=<app_entity_id>
   &login_hint=<user_email>
   &fidp=OrganizationSSO
   

7. Input the email address associated with the username for Alice within the Best Car Mart organization.

   

8. After resolving the organization from the email, the system redirects Alice to the authentication option of Best Car Mart.

   

Self-registration

To try out self-registration,

1. Set up the Guardio business application by following the B2B setup steps.

2. Create an organization for Best Car Mart by following the organization creation guide.

3. Follow the guides in this page and enable email domain based organization discovery and email domain discovery for self-registration. Add the following email domain mapping.

   • Organization Name: Best Car Mart
   • Email Domain: bcmart.com

4. Navigate to the login page of the application configured in above step 1 and click Register.

   

5. Enter an organization email with the domain bcmart.com and Submit.

   

6. After resolving the organization from the email, the system redirects you to the self-registration page of the Best Car Mart organization.

   

7. Fill in the user details and click Sign Up to complete the registration.