Roles are sets of users to whom you can assign application-access, administrative rights, and policies. Roles allow you to:

• Scale the process of application access. Rather than assign applications to users one-at-a-time, you can assign rights to access an application to a role, with a single operation, such that everyone in the role has access to the application.
• Delegate access and administration by creating roles with specific permissions. For example, delegate administrative rights for managing users, creating roles, creating and running reports, and so on.
• Automate user provisioning for applications by mapping roles to applications.

This topic demonstrates the process to create and define a role, which involves the following:

• Create a role: Use /SaasManage/StoreRole to create a role with a name and optional description. In addition, you can add parameters to add members to the role when you create it. You get back an identifier that you can pass to subsequent calls to access the role.
• Change role membership: You can add or remove users from any directory service that your tenant is using (Cloud user service, Active Directory, LDAP, etc.) and groups of users from a service, such as Active Directory, that supports groups. You can also nest roles by adding existing roles to the new role — members of the nested role inherit the rights and application-access assigned to the parent role. Use /Redrock/query to find available users, groups and roles. Use /Roles/UpdateRole to update role membership.
• Assign administrative permissions to the role: Identify Platform supports a set of administrative rights, or permissions, that control user access to specific functionality; for example, specific administrative rights control who can create and run reports, add users, create roles, etc. Use /SaasManage/AssignSuperRights to assign administrative rights to the role.

Identity Platform predefines the following roles:

• Everybody is available to facilitate user creation, simplify login access, and access to applications. As the name implies, all users are members of the Everybody role. The only exception to this are Centrify Directory Service users created using /CDirectoryService/CreateUser and explicitly passed the argument to prevent addition to this role. The Role API does not allow modification of this role.
• System Administrator contains all administrative privileges. You can't delete or modify this role, however, you can add and delete users.

📘

Although the API allows you to apply policies to roles to customize controls for specific groups of users, the current topic does not show how to do so.

To create, modify, or delete roles you must be a system administrator or have role-management permissions.

📘

This topic shows a sequence of calls to create a role, add members, and assign rights. The Manage Applications for Users topic shows how to assign application access to a role. Note that other than the first step, creating a role, the order is arbitrary. You could just as well assign rights or applications before adding members, and could also create a role with rights but no application access, or application access without rights.

Creating a role

Use /SaasManage/StoreRole to create the role. You can then add members, and permissions to define the role.

You pass a name and description for the role. The call returns a row-key string identifier for the role, which you should save for passing to calls to add members, assign permissions, and assign applications to the role.

📘

If you misplace the role ID, you can query the Role Table to retrieve a list of roles, which includes the Role ID for each returned role.

/SaasManage/StoreRole<p></p>
{
    "Name": "Report manager",
    "Description": "Create and run reports"
}

/SaasManage/StoreRole sample response

{
 "success": true,
 "Result": 
 {
    "_RowKey": "4fb10ae8_0e47_4035_a13f_a5bd2d9cb2f1"
 },
  "Message": null, "MessageID": null, "Exception": null, "ErrorID": null, "ErrorCode": null, "InnerExceptions": null
}

Note that /SaasManage/StoreRole provides optional parameters to add users, groups, or other roles to the new role. If you choose to add members at the same time that you create the role, you need to have on hand identifiers for the users, groups, and users to add. One way to get these identifiers is through calls to /Redrock/query as shown in the next section.

Updating a role

To update role membership, you need the role's identifier (which you saved when you created the role) and a list of valid users, groups, and roles.

Obtaining existing role member IDs

Call /Redrock/query on the User Table with a query similar to the following to get a list of user names and IDs:

/Redrock/Query
    {
    "Script":"Select UserName, ID  from  User ORDER BY Username COLLATE NOCASE"
    }

The query returns the name and ID for all users. Save the name or ID for any user who you want to add to the role — you can pass either one to /Roles/UpdateRole to add users to the role. For example, save 0ee88549-7c48-486d-a9f5-63cf9167890a ([email protected]) and d9fed598-7f16-4305-aaa8-97a9f5c12c00 (user1@ddog).

User table query response

{
      "success": true,
      "Result": {
        "IsAggregate": false,
        "Count": 44,
        "Columns": [
          {
            "Name": "ID",
            "IsHidden": false,
            "DDName": "ID",
            "Title": "ID",
            "DDTitle": "ID",
            "Description": "Row Identifier (primary key)",
            "Type": 12,
            "Format": null,
            "Width": 0,
            "TableKey": "Primary",
            "ForeignKey": null
          },
          {
            "Name": "Username",
            "IsHidden": false,
            "DDName": "Username",
            "Title": "Username",
            "DDTitle": "Username",
            "Description": "User name.",
            "Type": 12,
            "Format": null,
            "Width": 0,
            "TableKey": "Alternate",
            "ForeignKey": null
          }
        ],
        "FullCount": 44,
        "Results": [
          {
            "Entities": [
              {
                "Type": "User",
                "Key": "e7ed3e73-d115-44f3-9553-4bcc1a4ecc05",
                "IsForeignKey": false
              }
            ],
            "Row": {
              "ID": "e7ed3e73-d115-44f3-9553-4bcc1a4ecc05",
              "Username": "[email protected]"
            }
          },
          {
            "Entities": [
              {
                "Type": "User",
                "Key": "1ee22405-59b8-49a9-b64b-5b13aee592ce",
                "IsForeignKey": false
              }
            ],
            "Row": {
              "ID": "1ee22405-59b8-49a9-b64b-5b13aee592ce",
              "Username": "admin@abc1234"
            }
          },
           
      ...
        
       {
            "Entities": [
              {
                "Type": "User",
                "Key": "0ee88549-7c48-486d-a9f5-63cf9167890a",
                "IsForeignKey": false
              }
            ],
            "Row": {
              "ID": "0ee88549-7c48-486d-a9f5-63cf9167890a",
              "Username": "[email protected]"
            }
          {
            "Entities": [
              {
                "Type": "User",
                "Key": "d9fed598-7f16-4305-aaa8-97a9f5c12c00",
                "IsForeignKey": false
              }
            ],
            "Row": {
              "ID": "d9fed598-7f16-4305-aaa8-97a9f5c12c00",
              "Username": "[email protected]"
            }
          }
        ],
        "ReturnID": ""
      },
      "Message": null, "MessageID": null, "Exception": null, "ErrorID": null, "ErrorCode": null, "InnerExceptions": null
    }

Adding and removing role member IDs

The following example calls /Roles/UpdateRole to add two users and a role to an existing role, and an existing user is removed from the role.

Note: You can specify names or UUIDs for the members to add or delete.

/roles/UpdateRole
{
    "Name":"971d1...",
    "Description":"Run reports",
    "Users":
        {
        "Add":
        [user2@mk, 
        auser@mk]
        },
        "Delete":
        [qauser3@mk],
    "Roles":
        {
        "Add":
        ["4fb10a.."]
        }
}

Assigning rights to the role

Identify Platform supports a set of administrative rights, or permissions, that control users access to specific functionality; for example, administrative rights control who can create and run reports, add users, create roles, etc. You assign administrative rights to users through roles. You don't assign permissions directly to users, but rather assign permissions to roles to which you add users.

Identity Platform provides a predefined role, System Administrator, that contains all administrative privileges. The Centrify User Service account that initially signed up for a cloud-service tenant is automatically added to the System Administrator role. You can't modify or delete this role, however, you can add or remove members from the role.

Administrative rights: The following table lists the administrative rights and the permissions that each right grants. In addition, it shows the library file that defines the permission. The /SaasManage/AssignSuperRights function, which you use to add administrative rights to a role, requires you to pass the definition file to add a specific right. The last column of this table shows the association between each right and the library file that defines it.

Call /SaasManage/AssignSuperRights to assign specific rights to the role. Individual rights are defined in JSON-formatted library files.

The following sample shows how to add a single right, Report Management, to the role that you created previously. You pass the role UUID, and for each permission to add, the path to the library file that defines the permission.

If you don't know the paths to the files that define the permissions to add, you can run the following query to find them:

/Redrock/Query
    {
    "Script":"@/lib/get_superrights.js(excludeRight:'')",
    "Args": 
        {"PageNumber":1,"PageSize":10000,"Limit":10000,"SortBy":"","direction":"False","Caching":-1}
    }

Call /SaasManage/AssignSuperRights and pass the role ID and the path to the report management permission file:

/SaasManage/AssignSuperRights

[{
    'Role': '4fb10ae8_0e47_4035_a13f_a5bd2d9cb2f1',
    'Path': '/lib/rights/reportman.json'
}]

Response

{
    "success":true,
    "Result":null,
    "Message":null,"MessageID":null,"Exception":null,"ErrorID":null,"ErrorCode":null,"InnerExceptions":null
}

See Also

• Manage Access to Applications