Self-service approach¶

Self-service approach empowers organizations to take control of the onboarding process by enabling organizations to create their own organizations and onboard administrators. The root organization may support this through a self-service portal built using the Asgardeo APIs.

The following guides explain how you may create a self-service portal for your business.

Prerequisite

Create an administrator role in the root organization that provides authorization for organization APIs. To share it with organizations, ensure that it is associated with the B2B application shared with the relevant organization.

Set up the self-service portal¶

Follow the steps below to set up the application that acts as the self-service portal.

Create a standard based application selecting OAuth2.0/OpenID Connect as the protocol.
Select the application, go to its Shared Access tab and select Share with all organizations.
Go to the Protocol tab of the application and enable the following grant types
- Client Credential
- Organization Switch
Click Update to save the changes.

Note

Take note of the application's Client ID and Client Secret which will be required later.

Get an access token¶

To invoke the required APIs, the self-service application should receive an access token. Follow the steps below to receive an access token.

Provide authorization for the self-service application to consume the necessary APIs. To do so,

On the Asgardeo Console, go to Applications and select your self-service application.
In its API Authorization tab, grant the application authorization to the following scopes.

API Category	API	Scopes
Management API	Organization Management API `/api/server/v1/organizations`	Create Organizations View Organizations
Organization API	SCIM2 Roles API `/o/scim2/Roles`	Update Role View Role
Organization API	Application Management API `/o/api/server/v1/applications`	View Application
Organization API	SCIM2 Users API* `/o/scim2/Users`	Create User List Users
Management API	SCIM2 Users API** `/scim2/Users`	Create User View User

Note

* Only required if your admins are maintained within the organization.
** Only required if your admins are maintained in the root organization.

Get an access token for the self-service application using the following command.

curl -X POST https://api.asgardeo.io/t/{root-organization-name}/oauth2/token \
-u  '<client_id>:<client_secret>' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=internal_org_role_mgt_view internal_org_role_mgt_update internal_org_user_mgt_create internal_org_user_mgt_list internal_org_application_mgt_view internal_organization_view internal_organization_create internal_user_mgt_view internal_user_mgt_create'

Note

The access token expiration time is set to 3600 seconds by default. If you wish to modify this duration, you can do so in the Protocol section of the application.

Maintain organization admins¶

With self-service, you have the following two options to maintain administrators. Follow the appropriate guide that applies to your use case.

Maintain admins within the organization¶

By maintaining admins in the respective organizations, you can create an isolation between each organization as each admin is only authorized to manage a single organization. This approach is suitable when you want organizations to govern themselves with minimal interaction from the root organization. Additionally, this approach helps you maintain a separation between your B2C users (whose accounts exist in the root organization) and B2B users (whose accounts exist in the child organizations).

Warning

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

To create and maintain admins in the organization:

Use the following command to check the availability of your desired organization name.

curl --location 'https://api.asgardeo.io/t/{root-organization-name}/api/server/v1/organizations/check-name' \
--header 'Authorization: Bearer <access token>' \
--header 'Content-Type: application/json' \
--data '{"name": "<organization name>"}'

Note

The response returns "available": true for available organization names and "available": false for unavailable ones.

When you have confirmed the organization name availability, use the following command to create the organization.

curl --location 'https://api.asgardeo.io/t/{root-organization-name}/api/server/v1/organizations' \
--header 'Authorization: Bearer <access token>' \
--header 'Content-Type: application/json' \
--data '{"name": "<organization name>"}'

Note

Take note of the id parameter in the response. This is the ID of the organization and you will need it later.

Get an access token for the created organization by exchanging the access token obtained for the root organization. Use credentials of the shared OAuth2 application to execute the command.

Note

Learn more about the organization switch grant.

curl -X POST https://api.asgardeo.io/t/{root-organization-name}/oauth2/token \
-u '<client_id>:<client_secret>' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=organization_switch&token=<access token obtained for root organization>&switching_organization=<id of created organization>&scope=internal_org_role_mgt_view internal_org_role_mgt_update internal_org_user_mgt_create internal_org_user_mgt_list internal_org_application_mgt_view'

Create a user in the organization using the following command.

curl --location 'https://api.asgardeo.io/t/{root-organization-name}/o/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>"
    },
    "userName": "<customer-username>",
    "urn:scim:wso2:schema": { 
        "askPassword" : "true"
    }
}'

Note

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

Use the following command to get the id of the administrator role associated with the B2B application.

curl --location 'https://api.asgardeo.io/t/{root-organization-name}/o/scim2/v2/Roles?filter=displayName eq <admin-role-name> and audience.value eq <role-audience-value>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <access-token-obtained-for-the-organization>'

Find admin-role-name and role-audience-value

Refer to the following details related to the administrator role:

admin-role-name Name of the administrator role associated with your B2B application.

role-audience-value

For B2B applications with an application audience type, provide the application id. Use the following command to get the application id:

curl --location 'https://api.asgardeo.io/t/{root-organization-name}/o/api/server/v1/applications?filter=name eq <B2B-application-name>'
--header 'Authorization: Bearer <access-token-obtained-for-the-organization>'

If the B2B application's audience is organization, provide the organization id. Learn more about role audiences in manage roles.

Assign the user created in step 4 to the administrator role of your B2B application by using the following command.

curl --location --request PATCH 'https://api.asgardeo.io/t/{root-organization-name}/o/scim2/v2/Roles/{admin-role-id}' \
--header 'Authorization: Bearer <access-token-obtained-for-the-organization>' \
--header 'Content-Type: application/json' \
--data '{
    "Operations": [
        {
          "op": "add",
          "path": "users",
          "value": [
            {
              "value": "<user-id obtained from step 4>"
            }
          ]
        }
    ]
}'

Maintain admins in the root organization¶

By maintaining organization admins in the root organization, you may enable organization admins to create and manage many organizations using a single identity. The system treats organization admins as B2C users within the root organization.

Warning

Since your organization admins are created in the root organization, separating B2B and B2C users will be complex.

To create and maintain admins in the root organization:

Create a user in the root organization (root) using Asgardeo's System for Cross-domain Identity Management (SCIM) APIs.

curl --location 'https://api.asgardeo.io/t/{root-organization-name}/scim2/Users' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer { access token }' \
--data-raw '{
    "emails": [
        {
            "primary": true,
            "value": "<customer-email>"
        }
    ],
    "name": {
        "familyName": "<customer-family-name>",
        "givenName": "<customer-given-name>"
    },
    "userName": "<customer-username>",
    "urn:scim:wso2:schema": { 
        "askPassword" : "true"
    }
}'

Note

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

Use the following command to check the availability of your desired organization name.

curl --location 'https://api.asgardeo.io/t/{root-organization-name}/api/server/v1/organizations/check-name' \
--header 'Authorization: Bearer <access token>'  \
--header 'Content-Type: application/json' \
--data '{"name": "<organization name>"}'

Note

The response returns "available": true for available organization names and "available": false for unavailable ones.

When the name check confirms organization name availability, use the following command to create the organization and assign the user created in step 1 as the admin of that organization.

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

Get an access token for the created organization by exchanging the access token obtained for the root organization. Use credentials of the shared OAuth2 application to execute the command.

Note

Learn more about the organization switch grant.

curl -X POST https://api.asgardeo.io/t/{root-organization-name}/oauth2/token \
-u  '<client_id>:<client_secret>' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=organization_switch&token=<access token obtained for root organization>&switching_organization=<created organization id>&scope=internal_org_role_mgt_view internal_org_role_mgt_update internal_org_user_mgt_create internal_org_user_mgt_list internal_org_application_mgt_view'

The system creates a shadow user account in the new organization for the organization creator. Get the shadow account's user id using the following command.

curl --location 'https://api.asgardeo.io/t/{root-organization-name}/o/scim2/Users?filter=userName eq <username of the user created in step 1>' \
--header 'Authorization: Bearer <access-token-obtained-for-the-organization>' \
--header 'Content-Type: application/json'

Use the following command to get the id of the administrator role defined for your B2B application.

curl --location 'https://api.asgardeo.io/t/{root-organization-name}/o/scim2/v2/Roles?filter=displayName eq <admin-role-name> and audience.value eq <role-audience-value>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <access-token-obtained-for-the-organization>'

Find admin-role-name and role-audience-value

Refer to the following details related to the B2B application's administrator role:

admin-role-name Name of the administrator role associated with your B2B application.

role-audience-value

For B2B applications with an application audience type, provide the application id. Use the following command to get the application id:

curl --location 'https://api.asgardeo.io/t/{root-organization-name}/o/api/server/v1/applications?filter=name eq <B2B-application-name>'
--header 'Authorization: Bearer <access-token-obtained-for-the-organization>'

If the B2B application's audience is organization, provide the organization id. Learn more about role audiences in manage roles.

Assign the shadow account to the administrator role of your B2B application by using the following command.

curl --location --request PATCH 'https://api.asgardeo.io/t/{root-organization-name}/o/scim2/v2/Roles/<admin-role-id>' \
--header 'Authorization: Bearer <access-token-obtained-for-the-organization>' \
--header 'Content-Type: application/json' \
--data '{
    "Operations": [
        {
          "op": "add",
          "path": "users",
          "value": [
            {
              "value": "<user-id obtained from step 4>"
            }
          ]
        }
    ]
}'