API authorization for organizations

Asgardeo allows organizations to authorize user access to an application's API resources based on the API permissions, application roles, and groups assigned to the users. See API authorization for more information.

API resources are created and authorized for applications on the root organization. If the application consuming the API resources is shared with the organization, all application-specific configurations of API resources are inherited by the organization.

Prerequisites

You need to configure your API resources on the root organization

1. Register an API resource
2. Authorize the API resource to an app
3. Create application roles

Assign organization user groups to application roles

Application roles of an organization

The shared application will inherit the permission to role assignments from the application of the root organization.

Role-to-group assigning should be done separately for the organization, as the organization does not inherit the groups from the root organization.

Application roles are application-specific and inherited from the root organization's application.

You do not have permission to create new application roles, but you can assign these application roles to your organization groups.

organizations maintain the following three types of groups, and you can assign your application roles to any of these groups.

• Groups - A collection of organization users.
• External Groups - These groups are federated from connections on the organization. For example, groups federated from the Google connection.
• Invited User Groups - These are the user groups invited from the root organization to the organization.

Assign user groups to application roles

To assign application roles to user groups of the organization:

1. On the Asgardeo Console, switch to the organization.
2. Go to User Management > Roles > Application Roles and click Configure.
3. Expand the shared application and click + on the application role you wish to assign to a group.
4. Go to Groups and click + Assign Groups.
5. Select the group which should be assigned to the selected application role,
6. Click Assign to complete the role to group assigning.

Assign external groups to application roles

To assign application roles to External Groups:

Before you begin

To get started,

• You should register, configure, and create groups for a connection in your organization.
• You should add this connection to the sign-in flow of the application to which the application roles belong.

1. On the Asgardeo Console, switch to the organization.
2. Go to User Management > Roles > Application Roles and click Configure.
3. Expand the fragmented application and click + on the application role you wish to assign to a group.
4. Go to the External groups tab and expand the connection from which you select groups.
5. Select the group which should be assigned to the selected application role.
6. Click Assign Group to complete the role to group assigning.

Assign invited user groups to application roles

Asgardeo provides support for inviting users from the parent organization to manage organization operations. Currently, this invitation flow can be implemented using API calls.

To invite a root organization's user group and assign it to a role:

1. Create a group in the root organization and assign the users that should be invited.

2. Get the required access tokens to call the API.

3. Use the access token and the organization ID obtained after executing step 2 and execute the following cURL:

   curl --location --request PATCH 'https://api.authz-dv.cloudservices.wso2.com/o/<org-id>/applications/<shared-app-id>/roles/<role-name>/cross-org-group-mapping' \
   --header 'Content-Type: application/json' \
   --header 'Accept: application/json' \
   --header 'Authorization: Bearer <access-token>' \
   --data '{
       "added_groups": [
           {
               "name": "<userstore>/<group-name-in-root-org>",
               "organization": "<root-org-id>"
           }
       ],
       "removed_groups": []
   }'
   

   Replace the following variables in the above request.

   Request Parameter	Description
   org-id	The organization ID of the B2B organization you are inviting the user group to.
   shared-app-id	The application ID of the shared application in the organization.
   role-name	The role name of the organization to which you wish to assign the invited user group.
   access-token	The access token obtained for the organization.
   userstore	The user store to which the user group belongs. The primary user store of Asgardeo is DEFAULT.
   group-name-in-root-org	The name of the user group you wish to invite to the organization.
   root-org-id	The organization ID of the root organization.

Once the above cURL is executed successfully, the application role of the organization will be assigned to the invited user group from the organization.

To view the group-to-role assignment:

1. On the Asgardeo Console, switch to the organization.
2. Go to Roles > Application Roles and click Configure.
3. Expand the shared application and click + on the application role to which you assigned the invited user group.
4. Go to the Invited User Groups tab. You will now see the invited user group assigned to the application role.

Try it out

Follow the steps given below to try out the RBAC flow:

Note that we are using Asgardeo's B2B Guardio insurance application for this scenario.

To request scopes for the user:

1. Add the new scopes to the APIScope parameter of the config.js file of the sample application. You need to request these new scopes in addition to the OIDC scopes of your application.

   To get the scopes:

   1. On the Asgardeo Console, switch to the root organization.

   2. Go to Applications and select your application.

   3. Copy the scopes listed at the end of the API Authorization section

      

When you add scopes to the configuration file, add them as comma-separated values.

2. Access the application URL.

3. Try to log in as a user with a group and permission to access the API resource.

   Upon successful login, you will see the permission/scopes allowed for the user on the user consent page.

4. Click Allow. You will now be redirected to the application. You will be able to see the assigned permissions on the allowedScopes parameter of the authentication response.

If you are switching organizations

If the user switches the organization to another organization, the scopes will be updated according to the roles assigned to the user in the switched organization.