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

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

1. Login to the organization (root) from the Asgardeo Console.
2. On the Asgardeo Console, go to Login & Registration, and click Email Domain Discovery under Organization Settings.

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

   

Using the API

1. Get an access token with the internal_organization_config_add scope.

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

   curl --location --request POST 'https://api.asgardeo.io/t/<root_organization_name>/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 Asgardeo. See Manage organizations for instructions.

Using the Console

1. On the Asgardeo Console, go to Login & Registration.
2. Click Email Domain Discovery under Organization Settings.

3. Click +Assign Email Domains.

   

4. Select the organization you want to claim an email domain from the dropdown under Organization Name.

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

   

6. 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) has 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 the email domains of organizations in the hierarchy.

Using the API

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://api.asgardeo.io/t/<root_organization_name>/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

1. On the Asgardeo Console, go to Login & Registration,
2. Click Email Domain Discovery under Organization Settings.

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

   

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

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://api.asgardeo.io/t/<root_organization_name>/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

1. Set up the Guardio-Business-App as a B2B application.

2. Create an organization on the Asgardeo Console with Best Car Mart as the Organization Name.

3. Configure the email domain mapping for the Best Car Mart organization as follows:

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

4. Switch to the Best Car Mart organization on the Asgardeo 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. Try to log in to the Guardio-Business-App by selecting Sign In With 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://api.asgardeo.io/t/<root_organization_name>/oauth2/authorize?
   client_id=<client_id>
   &redirect_uri=<redirect_url>
   &scope=<scopes>
   &response_type=code
   &login_hint=<user_email>
   &fidp=OrganizationSSO
   

   https://api.asgardeo.io/t/<root_organization_name>/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, Alice will be redirected to the authentication option of Best Car Mart.