Email domain based organization discovery

In the realm of Business-to-Business (B2B), seamlessly authenticating users from external organizations into your applications is essential for a smooth user experience. One way to achieve this is through email domain-based organization discovery. With this feature, your application is able to provide a customized and a familiar login experience for a user based on the domain of their email address.

For example, when users log in with an @xyz.com email address, they will be automatically redirected to the login screen customized for the XYZ organization, providing 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 is an insurance provider. Best Car Mart and Glory Car Mart are two of its customer organizations. When a user enters an email address to log into the Guardio Insurance platform, it is required to resolve a user's organization based on the email domain and redirect them to the respective organization's login screen.

In this example scenario,

• User Alice with email [email protected] should be routed to the login screen of Best Car Mart organization.
• User Bob and Ben, with emails [email protected] and [email protected] should be routed to the login screen of Glory Car Mart organization.

Enable email domain based organization discovery

Important

• Enabling this feature and mapping email domains to organizations is only permitted in the root organization.
• For this feature to work, make sure to enable email address as the username so that users may log in to applications with their email addresses.

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

Mapping an email domain to an organization allows for a customized user experience, but it is not mandatory. When an organization does not have a mapped email domain, the behavior changes as follows:

• If an organization registers an email domain mapping,

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

  • Just-In-Time (JIT) provisioning during federated authentication only occurs if the user's email domain matches one of the domains claimed by the organization.

• 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 result in existing users being unable to log 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

To try out user login,

1. Set up the Guardio business application by following the steps here.

2. Create an organization for Best Car Mart by following the steps here.

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

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, Alice will be redirected to the authentication option of Best Car Mart.