Onboard organization administrators

You can onboard organization administrators using any of the following approaches:

• Sales-led approach
• Self-service approach

Sales-led approach

In this approach, the admin of the root organization creates the organization and adds a user as an admin of the created organization. This method is typically used when the root organization should regulate the creation of B2B organizations, and the administrator's supervision is required to ensure proper setup.

Follow the steps below to onboard organization administrators using the Asgardeo Console.

Prerequisites

You need to create an organization and switch to the created organization.

Only organization creators can onboard administrators for their organizations using the Asgardeo Console.

Step 1: Create a user

To create a new organization user:

1. Switch to the organization on the Asgardeo Console.

2. Go to User Management > Users and click Add User.

3. Enter the following details:

   Email (Username)	A unique email address to identify the user.
   First Name	First name of the user. You can add/change this later.
   Last Name	Last name of the user. You can add/change this later.

4. You can either request the user to set the password or set one on the user's behalf.

   • Invite user to set their own password: If this option is selected, an email with a confirmation link will be sent to the provided email address for the user to set their own password.

   • Set a temporary password for the user: If this option is selected, the administrator can set a temporary password for the user.

5. Click Finish to add the new user.

Step 2: Assign the user to the Administrator role

The Administrator role is available in all organizations by default. To assign the created user to this role:

1. Switch to the organization on the Asgardeo Console.

2. Go to User Management > Roles and click Configure in the Organization Roles section.

3. Select the Administrator role and go to the Users tab.

4. Click the edit button to open the Manage Users dialog box.

5. Assign the user to the role by selecting the user and moving to the box on the right.

   See details of all the available administrator permissions you are granting the organization administrator.

   

6. Click Save.

You have now onboarded an administrator to the organization. From thereon, the organization administrator can manage that organization's identity and access management requirements.

Note that organization administrators do not have access to the Asgardeo Console as they are not direct users of Asgardeo. A separate administration portal is required to carry out these functions. Learn more about implementing an administration portal.

Self-service approach

In this approach, organization users can self-subscribe to the B2B application and easily create their own B2B organizations. This method empowers organization users to take control of the onboarding process, making it quick and convenient.

Using the self-service approach, the organization users can maintain their administrators either in the organization itself or the root organization. The selection of the creation place depends on the organization's business requirements.

• Maintain admins in the organizations: You can create the user in an organization if the user needs to be isolated into one organization.
• Maintain admins in the root organization: You can create the user in the root organization if the same user can manage multiple organizations.

Initial setup: Get access tokens

Before creating admins using the APIs, you need to obtain the required access tokens and enable self-service. Follow the steps below to set up the initial requirements to create organization admins.

1. Get an access token from your root organization.

   Required scopes

   Include the following scopes when requesting for the access token: openid`` internal_application_mgt_create internal_application_mgt_view internal_organization_view internal_organization_update internal_governance_view internal_governance_update internal_email_mgt_view internal_email_mgt_update`` internal_email_mgt_delete internal_email_mgt_create internal_userstore_view internal_userstore_update internal_userstore_delete

2. Enable self-service for the root organization.

   curl --location --request PATCH 
   'https://api.asgardeo.io/o/{root-org-id}/api/server/v1/self-service/preferences' \
   -H 'Content-Type: application/json' \
   -H 'Authorization: Bearer <access-token-obtained-from-step-1>' \
   -d '{
       "operation": "UPDATE",
       "properties": [
           {
               "name": "Organization.SelfService.Enable",
               "value": "true"
           }
       ]
   }'
   

   The {root-org-id} is the organization ID of the root organization. To obtain the organization ID of your root organization, copy the provided organization ID from the organization drop-down. Learn more.

   Enabling self-service will create the following in the root organization:

   • A system user named B2B-SS-System-User.
   • A system role named B2B-SS-System-Role.
   • A system application named B2B-Self-Service-Mgt-Application. This application has limited permissions to facilitate subsequent API calls.

   You will be able to see these entities on the Asgardeo console.

3. Get an access token for the B2B-Self-Service-Mgt-Application using the following cURL.

   Take note of the system application's Client ID and Client Secret created on the Asgardeo console, as it will be required in the next steps.

   curl -X POST \
   https://api.asgardeo.io/t/<root_org_name>/oauth2/token \
   -u  '<client_id>:<client_secret>' \
   -H 'Content-Type: application/x-www-form-urlencoded' \
   -d 'grant_type=client_credentials&scope=openid internal_identity_mgt_create internal_identity_mgt_delete internal_identity_mgt_update internal_identity_mgt_view internal_organization_admin internal_organization_create internal_organization_view internal_user_mgt_create internal_user_mgt_list internal_user_mgt_view'
   

   The access token expiration time is set to 7200 seconds by default. If you wish to modify this duration, you can do so via the console. Go to the B2B-Self-Service-Mgt-Application application's protocol section and update the User access token expiry time.

Maintain admins in the organization

This approach is suitable when you want organizations to govern themselves with minimal interaction from the root organization. Additionally, if you have a B2C user, this approach will help you to separate them from B2B users easily.

If a user wants to create multiple organizations, they will need to register a new account for each organization. Thus they will have separate identities in each organization.

To create and maintain admins in the organization:

1. Use the following cURL to check if the name of organization you wish to create is already available.

   curl --location 'https://api.asgardeo.io/o/{root-org-id}/api/server/v1/organizations/check-name' \
   --header 'Authorization: Bearer {access token obtained for the B2B-Self-Service-Mgt-Application }' 
   --header 'Content-Type: application/json' \
   --data '{
   "name": "{organization name}"
   }'
   

   If the organization name is available for use, the response will be "available": true, else it will be "available": false.

2. If the required organization name is available for use, use the following cURL to create the organization.

   curl --location 'https://api.asgardeo.io/o/{root-org-id}/api/server/v1/organizations' \
   --header 'Authorization: Bearer {access token obtained for the B2B-Self-Service-Mgt-Application}' \
   --header 'Content-Type: application/json' \
   --data '{
       "name": "{organization name}",
       "parentId": "{root-org-id}"
   }'
   

   Take note of the id parameter in the response. This is the organization-id of the newly created organization and you will need it in the following steps.

3. Get an access token for the created organization by exchanging the access token obtained for the B2B-Self-Service-Mgt-Application. Use credentials of the B2B-Self-Service-Mgt-Application to execute the cURL.

4. Create a user in the organization using the following cURL.

   curl --location 'https://api.asgardeo.io/o/{organization-id-obtained-in-step-2}/scim2/Users' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer {token obtained in step 3}' \
   --data-raw '{
       "emails": [
           {
               "primary": true,
               "value": "{customer-email}"
           }
       ],
       "name": {
           "familyName": "{customer-family-name}",
           "givenName": "{customer-given-name}"
       },
       "password": "{customer-password}",
       "userName": "{customer-username}"
   }'
   

   Take note of the user-id returned in the response of the above cURL.

5. Use the following cURL to obtain the id of the Administrator role.

   curl --location 'https://api.asgardeo.io/o/{org-id}/api/server/v1/organizations/{org-id}/roles?filter=name%20eq%20Administrator' ' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer {access-token-obtained-for-the-organization}' \
   

6. Create a user and assign the user to the administrator role by using the following cURL.

   curl --location --request PATCH 'https://api.asgardeo.io/o/{org-id}/api/server/v1/organizations/{org-id}/roles/{administrator-role-id}' \
   --header 'Authorization: Bearer {org access token}' \
   --header 'Content-Type: application/json' \
   --data '{
       "operations": [
           {
               "op": "ADD",
               "path": "users",
               "value": [
                   "{user-id obtained from step 4}"
               ]
           }
       ]
   }'
   

Maintain admins in the root organization

This approach is particularly suitable when an organization user prefers to maintain a single identity linked to multiple B2B organizations. Under this approach, organization users are treated as business users (B2C users) within the organization. It grants organization users the capability to access various B2C applications, such as billing portals, within the Business organization.

Separating B2C and B2B users will be more complicated.

To create and maintain admins in the root organization:

1. Create a user in the root organization using Asgardeo’s SCIM APIs.

   curl --location 'https://api.asgardeo.io/o/{root-org-id}/scim2/Users' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer {access token obtained for the B2B-Self-Service-Mgt-Application}' \
   --data-raw '{
       "emails": [
           {
               "primary": true,
               "value": "{customer-email}"
           }
       ],
       "name": {
           "familyName": "{customer-family-name}",
           "givenName": "{customer-given-name}"
       },
       "password": "{customer-password}",
       "userName": "{customer-username}"
   }'
   

Take note of the user-id received in the response of the above cURL.

2. Use the following cURL to check if the name of the organization you wish to create is already available.

   curl --location 'https://api.asgardeo.io/o/{primary-org-id}/api/server/v1/organizations/check-name' \
   --header 'Authorization: Bearer {access token obtained for the B2B-Self-Service-Mgt-Application }' 
   --header 'Content-Type: application/json' \
   --data '{
   "name": "{organization-name}"
   }'
   

   If the organization name is available for use, the response will be "available": true, else it will be "available": false.

3. If the required organization name is available for use, use the following cURL to create the organization and assign the user created in step 1 as the organization's admin.

   curl --location 'https://api.asgardeo.io/o/{root-org-id}/api/server/v1/organizations' \
   --header 'Authorization: Bearer {access token obtained for the B2B-Self-Service-Mgt-Application  }' \
   --header 'Content-Type: application/json' \
   --data-raw '{
       "name": "{organization name}",
       "parentId": "{root-org-id}",
       "attributes": [
           {
               "key": "creator.id",
               "value": "{user-id obtained from step 1}"
           },
           {
               "key": "creator.username",
               "value": {username of the user created in step 1}"
           }
       ]
   }'
   

Now, you have created a new organization and assigned a user from the root organization as the admin of it. This admin will be maintained in the root organization.