Manage access based on roles

You can manage user access to your application based on their role, where the role determines which permissions to give the user. For example, an automotive company can provide suppliers access to data that they don't expose to consumers.

Role-based access control provides effective access management, and better security (see Role-based access control).

Step 1: Plan your strategy

Before implementing access controls, you'll need to decide on a strategy that makes sense for your business. Start by analyzing your business needs, and then define roles by grouping end-users based on common responsibilities.

Next, define permissions for each role—which may include permissions to modify data (e.g., read, write, full access), permission to access your applications, and permissions inside the application itself.

Step 2: Create roles

Create the roles that will be assigned to end-users to control their access, such as partner and customer. For each role, send a request like the one below, passing a friendly name for the role as role_name. The request will return an autogenerated role ID (role_id) that uniquely identifies the role in your tenant and in API requests.

curl -i -X POST \
  'https://api.transmitsecurity.io/cis/v1/roles' \
  -H 'Authorization: Bearer 91827321837bdfjf' \
  -H 'Content-Type: application/json' \
  -d '{
    "role_name": "partner"
  }'

Step 3: Assign permissions

Once roles are created, you can assign each role the relevant permissions using a request like the one below. The role_id is the identifier returned upon role creation (step 2), and the permissions array contains a list of permissions to add to this role.

curl -i -X PUT \
  'https://api.transmitsecurity.io/cis/v1/roles/{role_id}/permissions' \
  -H 'Authorization: Bearer 91827321837bdfjf' \
  -H 'Content-Type: application/json' \
  -d '{
    "permissions": [
      "read:customer-profile"
    ]
  }'

Step 4: Assign roles to users

Assign the roles to your end-users using a request like the one below. The role_id is the identifier returned in Step 2 upon role creation, and entity_ids contains the user IDs (user_id) to assign the role to.

curl -i -X POST \
  'https://api.transmitsecurity.io/cis/v1/roles/{role_id}/assignments' \
  -H 'Authorization: Bearer 91827321837bdfjf' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_ids": [
      "YlGZru-O7j3Ep79S2e8OU",
      "ek5Pvb4eccm1KPW8jlN6p"
    ],
    "entity_type": "User"
  }'

Step 5: Get user's roles

Now that your RBAC model is set up, you can start using it by fetching assigned roles for a given user when needed. Use one of the following methods to retrieve a list of user's roles:

• Obtain roles upon user authentication
• Retrieve roles directly
• Request roles in id_token

Obtain roles upon user authentication

You can obtain roles upon each successful user authentication. The user's roles (by role_id) are returned in the access token. For example:

{
  "tid": "",
  "app_name": "Acme",
  "app_id": "8flFllgrd1Wqiru4IGai0",
  "external_account_id": null,
  "roles": [
    "smP3MD65l7hKXG6qJ-S5d"
  ],
  "jti": "IJMTqbmijVG7_LsJz-y5U",
  "sub": "bb8dc75.8AEM5PpWyJBH6opzIOrJ2.transmit",
  "iat": 1658056533,
  "exp": 1658060133,
  "scope": "offline_access",
  "client_id": "bb8dc75.8AEM5PpWyJBH6opzIOrJ2.transmit",
  "iss": "https://userid.security",
  "aud": "userid-api"
}

Retrieve roles directly

You can also retrieve roles for a user directly by sending a request like the one below, using the app-level access token for authorization. Use the {entity_id} path parameter to specify the user_id.

curl -i -X GET \
  'https://api.transmitsecurity.io/cis/v1/roles/assignments/{entity_id}' \
  -H 'Authorization: Bearer 91827321837bdfjf'

Request roles in id_token

You can request roles as a part of the authentication flow. To do it, add the claims object to the request body as shown in the example below. As a result, id_token will contain a list of roles.

curl -i -X POST \
  'https://api.transmitsecurity.io/cis/v1/auth/otp/sms' \
  -H 'Authorization: Bearer 91827321837bdfjf' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+16175551212",
    "create_new_user": true,
    "redirect_uri": "https://domain.com/verify",
    "claims": {
      "id_token": {
        "roles": null
      }
    }
  }'

Step 6: Get role's permissions

To determine the user's access, you'll need to know the permissions corresponding to their roles. Their effective permissions will be the union of permissions for all the roles. To get permissions, do one of the following:

• Fetch permissions for a role
• Request effective permissions in id_token

Fetch permissions for a role

For each role, you can fetch the permission by sending a request like the one below, using the app-level access token for authorization. Use the {role_id} path parameter to specify the role.

curl -i -X GET \
  'https://api.transmitsecurity.io/cis/v1/roles/{role_id}' \
  -H 'Authorization: Bearer 91827321837bdfjf'

Request effective permissions in id_token

You can request permissions as a part of the authentication flow. To do it, add the claims object to the request body as shown in the example below. As a result, id_token will contain a list of permissions.

curl -i -X POST \
  'https://api.transmitsecurity.io/cis/v1/auth/otp/sms' \
  -H 'Authorization: Bearer 91827321837bdfjf' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+16175551212",
    "create_new_user": true,
    "redirect_uri": "https://domain.com/verify",
    "claims": {
      "id_token": {
        "permissions": null
      }
    }
  }'

Step 7: Unassign role from user

When needed, you can unassign a role from a user by sending a request like the one below, using an app-level access token for authorization. The relevant role ID and user ID are specified in the path using {role_id} and {entity_id}, respectively.

curl -i -X DELETE \
  'https://api.transmitsecurity.io/cis/v1/roles/{role_id}/assignments/{entity_id}' \
  -H 'Authorization: Bearer 91827321837bdfjf'