Email domain based organization discovery¶
In the realm of Business-to-Business (B2B) scenarios, it's essential to efficiently manage users from different organizations. One way to achieve this is through organization discovery based on criteria such as email domain and user attributes. WSO2 Identity Server offers a solution for email domain-based organization discovery.
The primary purpose of email domain based discovery is to route B2B users from various organizations to their respective authentication options based on their email addresses.
This guide explains how to configure and use email domain-based organization discovery in WSO2 Identity Server.
Scenario¶
Consider Guardio Insurance is a B2B SaaS provider and Best Car Mart
and Glory Car Mart
are two of its customer/partner organizations.
Guardio Insurance wants to resolve the organization of a user based on the email domain of the user's email address and route them to the respective authentication options.
User Alice with email [email protected]
should be routed to the authentication options provided by the Best Car Mart
organization,
and user Bob and Ben, with emails [email protected]
and [email protected]
should be routed to the authentication options provided by the Glory Car Mart
organization.
Enable email domain based organization discovery¶
Note
- This feature can only be used when email address is configured as the username.
- Enabling email domain based organization discovery feature, and adding email domain mapping against the organizations is permitted only for the organization (root).
Using the Console¶
- Login to the organization (root) from the WSO2 Identity Server Console.
- On the WSO2 Identity Server Console, go to Login & Registration, and click Email Domain Discovery under Organization Settings.
-
Turn on the toggle to enable email domain based organization discovery.
Using the API¶
-
Get an access token with the
internal_organization_config_add
scope. -
Use the obtained access token to execute the following cURL.
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 } ] }'
Configure email domains for organizations¶
Prerequisites¶
You need to: - enable email domain based organization discovery for the organization (root). - have registered organizations in WSO2 Identity Server. See Manage organizations for instructions.
Using the Console¶
- On the WSO2 Identity Server Console, go to Login & Registration.
- Click Email Domain Discovery under Organization Settings.
-
Click +Assign Email Domains.
-
Select the organization you want to claim an email domain from the dropdown under Organization Name.
-
Type the email domain you want to claim for the selected organization under Email Domains and press enter. Here you can add one or more email domains.
-
Click Assign.
Note
- If the organization has any email domain mapping: During the onboarding process of a user to an organization, the user's username (which is an email) undergoes a check against the assigned email domains of that organization. If there's a match, the user is successfully onboarded to the organization. However, if there is no match, the user onboarding process will fail.
- While the organization (root) have enabled email domain based organization discovery, it is not compulsory to configure an email domain mapping for every organization in the hierarchy. If an organization doesn't have an email domain mapping, the user onboarded to that organization can have any email domain other than email domains of organizations in the hierarchy.
Using the API¶
-
Get an access token with the
internal_organization_discovery_update
scope. -
Use the obtained access token to execute the following cURL.
curl --location --request POST 'https://localhost:94433/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 configured email domains of organizations¶
Using the Console¶
- On the WSO2 Identity Server Console, go to Login & Registration,
- Click Email Domain Discovery under Organization Settings.
-
Click Edit of the organization you want to update the email domains.
-
Update the email domains in Email Domains and click Update.
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 API¶
-
Get an access token with the
internal_organization_discovery_update
scope. -
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¶
-
Set up the
Guardio-Business-App
as a B2B application. -
Create an organization on the WSO2 Identity Server Console with
Best Car Mart
as the Organization Name. -
Configure the email domain mapping for the
Best Car Mart
organization as follows:- Organization Name:
Best Car Mart
- Email Domain:
bcmart.com
- Organization Name:
-
Switch to the
Best Car Mart
organization on the WSO2 Identity Server Console. -
Onboard a new user to
Best Car Mart
organization with following information. You can either set a password for the user or invite 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
-
Try to log in to the
Guardio-Business-App
by selectingSign In With SSO
. -
Input the username (which is an email) of
Alice
inBest Car Mart
organization. -
After resolving the organization from the email, Alice will be redirected to the authentication option of
Best Car Mart
.