User Groups Details

Learn how to leverage user groups to provide specific authorisation to your users into your application.

User Groups provide a mechanism to give authorisation or access privileges to the users accessing your application. It helps developers efficiently manage specific types of users in their application and authorise them upon their login to the application.

Default User Groups

After successfully creating the first Login Configuration in a project, the system will automatically create a default user group called all_users. Affinidi Login will use this group to add users who successfully log in to your application automatically. Using the all_users group, you will have the visibility of all the users’ DIDs that have logged in to your application.

Additionally, you cannot delete this default user group, including the users inside the all_users group.

Suppose you have multiple applications and only want the all_users group to contain a list of users from a specific application; in that case, you should create a separate project for each application.

Viewing Users in the Default User Group

There are two ways to view the list of users in the default group:

  1. Go to  Affinidi Login page, click on the Actions dropdown menu, then click View all users option.

  2. Using Affinidi CLI by running the following command:

affinidi login list-users-in-group --group-name="all_users"

How to Use User Groups

In this scenario, we want to ensure that only specific users have the ability to update records or access a particular resource; for that, we will create a User Group named user_group_update and assign users to this group. Once a user successfully authenticates through Affinidi Login to your application, the access_token will have the additional scope (scp) for the user group. Subsequently, your application must evaluate this user group to provide the relevant privileges.

For the purpose of assigning users to distinct User Groups, their Decentralised Identifier (DID) or User ID is required. This identifier is associated with their Vault at the time of account registration. The DID value can be found either in the user’s profile in their Vault or in the all_users group of your project after the user successfully logged in to your application.

Getting User DID or User ID

To add the user to the User Group, you have to get their DID or User ID, which is the user’s unique identifier in the application. To obtain this information, you can do the following:

Manually from the Affinidi Vault user profile.

DID information is available within the Affinidi Vault’s Profile page, generated upon successful registration.

Using the default all_users group

Affinidi Login automatically adds the user to the all_users default group whenever a user successfully logs in to your application. You can view the list of DIDs in the all_users group by going to the  Affinidi Login or using CLI by running the command:

affinidi login list-users-in-group --group-name=all_users

Switch to another project if you want to see the list of users for that project.

Programmatically with idToken from Affinidi Login.

When a user login to your application through Affinidi Login flow, the idToken that the Affinidi Login return contains the DID information, which is also the user’s SUB. Based on your business logic, you can parse this value from the idToken and add the user to specific User Groups.

See the example code below on how to extract DID information from idToken:

// parse the idToken sent by Affinidi Login through callback URL
const idToken = JSON.parse(Buffer.from(context.id_token.split('.')[1], 'base64').toString());

// get the DID info of the user through SUB
const userSUB = idToken.sub;

// get the DID info of the user from custom property
const userDID = idToken.custom.find(d => d.did).did;

In the application, when parsing the idToken sent to the callback URL from Affinidi Login, you can add the code above to extract the SUB or DID information of the user. The SUB property represents the DID information of the user. At the same time, the custom property also contains the DID information of the user.

Go to this guide to find out more about idToken sent by Affinidi Login.

How to Create Groups and Add Users

There are two ways to create groups and add users to it. One way is through Affinidi CLI, and the other is through  Affinidi Portal.

Expand the section below for your preferred method:

Using Affinidi CLI

Here are the steps to Create a User Group in CLI.

  1. Log in to Affinidi CLI by running:
affinidi start
  1. Once you have successfully logged in, create the User Group by running:
affinidi login create-group --name="regular_user"
  • --name is the name of the user group to be created.

Sample response:

  "ari": "ari:identity:ap-southeast-1:5e732511-b52a-4a55-8031-2133bd6e15e3:group/regular_user",
  "groupName": "regular_user",
  "projectId": "5e732511-b52a-4a55-8031-2133bd6e15e3",
  "creationDate": "2023-09-18T09:42:49.145Z"

Here are the steps to add a User to a Group.

  1. To add a user, get the user’s DID either from the idToken sent to your application by Affinidi Login or from the user’s Vault. To add the user:
affinidi login add-user-to-group \
--group-name="regular_user" --user-sub="did:key..."
  • --group-name is the name of the target user group.
  • --user-sub is the user’s DID that you want to add into the Group. This can be found in the Profile of the user in the Vault.

Sample response:

  "ari": "ari:identity:ap-southeast-1:5e732511-b52a-4a55-8031-2133bd6e15e3:group/regular_user/user/e309353aa1f5caddb1eeb0b40213e4327aafe62cb894aacbe36259209d25b259",
  "projectId": "5e732511-b52a-4a55-8031-2133bd6e15e3",
  "groupAri": "ari:identity:ap-southeast-1:5e732511-b52a-4a55-8031-2133bd6e15e3:group/regular_user",
  "groupName": "regular_user",
  "sub": "did:key:...",
  "id": "e309353aa1f5caddb1eeb0b40213e4327aafe62cb894aacbe36259209d25b259",
  "creationDate": "2023-09-18T09:49:58.611Z"

Learn more on how to manage your User Groups using Affinidi CLI.

Using Affinidi Portal

Here are the steps to create a User Group in Affinidi Portal.

Create new User Group
  1. Go to  Affinidi Login under the Services section.

  2. Click on the Create Group and provide the group name.

  3. Once you click on Submit, the User Group is immediately created.

You can update the existing user groups to add more users.

Here are the steps to add a User to a Group in Affinidi Portal.

Add a User to User Group
  1. Go to  Affinidi Login under the Services section.

  2. Click on the target User Group where you want to add the user. This should open the User Group page.

  3. In the User Group Page, you can see the list of users (if there’s any). To add a new user, click on the ADD USERS button.

  4. Specify the DID of the user in the form and click Submit.

  1. You should now see that a new entry has been added in the User Group page.
Add a User to User Group

After adding the user to the group and once the user logs in to your application, the JWT access_token generated following successful authentication through Affinidi Login appears as follows:

  "aud": [
  "client_id": "<AUTH.CLIENT_ID>",
  "exp": 1694513885,
  "ext": {},
  "iat": 1694506685,
  "iss": "https://<PROJECT_ID>",
  "jti": "d87b1d8c-fa60-4977-b983-ceb5dba86a7f",
  "nbf": 1694506685,
  "scp": [
  "sub": "did:key..."

Depending on your requirements, you can use this group to provide access to your application accordingly.