Roles admin service

The AuthP library contains a IAuthRolesAdminService service that contains various admin features for managing AuthP's Roles. This page describes these admin features and give you some examples of how they might be used in an application.

NOTE: the code for the AuthRolesAdminService can be found here and has plenty of comments.

How Roles are used depends on whether your application is using AuthP's multi-tenant feature. Multi-tenant applications can use the Role's RoleType parameter to provide versioning of your multi-tenant applications - see the article Multi-tenant apps with different versions can increase your profits for more on this.

NOTE: A multi-tenant application doesn't have to use multi-tenant Roles feature. In the AuthP repo there are two examples of multi-tenant applications: Example3 (single-level multi-tenant) and Example4 (hierarchical multi-tenant). Only Example3 uses the full suite of the multi-tenant Roles feature. see this section of the Roles Explained document which explains the different type of Roles.

There are two example implementations of the Roles admin. The first isn't a multi-tenant application, while the second is using AuthP's multi-tenant feature:

1. Example1's Pages/AuthRoles Razor Pages, which isn't a multi-tenant application. NOTE: You do not need to log in to access the admin services.
2. Example3's RolesController and its views, which is a multi-tenant application. NOTE: You must log in as '[email protected]' to access all the admin features, and as '[email protected]' to see what an tenant admin can do.

All the methods come from an instance of the IAuthRolesAdminService provided by DI.

Get a list of the roles

The QueryRoleToPermissions method returns an IQueryable<RoleWithPermissionNamesDto>, which you can use for showing the Roles, with the names of the Permission in that Role. Because is an IQueryable you can filter, page, etc. if you need to.

Not using multi-tenant Roles feature.

If your application isn't a multi-tenant application, or you don't want to use the you can call the QueryRoleToPermissions method without a parameter - see this example from Example1's ListRoles Page.

AuthRolesList = await
    _authRolesAdmin.QueryRoleToPermissions().ToListAsync();

And the output would look like this (Note the black "Permission1 , Permission2" is a tool tip shown by hovering / clicking the '#Permissions' column for a Role you want to see.

Using multi-tenant Roles feature.

If you want to display in any multi-tenant application you MUST provide the UserId of the logged in user. That's because the Roles can differ between tenants. The QueryRoleToPermissions uses the UserId to work out a) if the user is an app user (no tenant), in which case you can see all the Roles, or b) if the user is a tenant user it will only show the Roles available in the user's tenant. The code below was taken from Example3's RolesController and it provides the UserId of the logged in user.

var userId = User.GetUserIdFromUser();
var permissionDisplay = await
    _authRolesAdmin.QueryRoleToPermissions(userId)
        .OrderBy(x => x.RoleType)  
        .ToListAsync();

The the screenshot below is from Example3's Roles\Index page. The big change is the addition of a RoleType column to the display

Things to point out in this screenshot:

• If you are the app admin a Create new Role` button is shown (tenant admin user's aren't allowed to create a Role.
• There are a 'Edit' and 'Delete' link on the right of each Role if you are the app admin. Again tenant admin user's aren't allowed to Edit or Delete Roles.
• If you hover / click the '#Permissions' column for a Role it will show you a tool tip with a list of the Permissions in the Role.

Add/Update a Role

Add and update are very similar so they are described together. The two methods are:

• UpdateRoleToPermissionsAsync(string roleName, IEnumerable<string> permissionNames, string description = null)
• CreateRoleToPermissionsAsync(string roleName, IEnumerable<string> permissionNames, string description = null)

NOTE: Tenant admin user aren't allowed to create or update a Role. Only app admin users are allowed to create / update Roles.

The display shown depends on whether you are using using multi-tenant roles or not.

Not using multi-tenant roles

In this case you don't need to set or display the RoleType. The screenshot below is taken from Example4, which doesn't use RoleTypes, and doesn't show the RoleType Roles\Edit page (non-tenant applications would be the same).

Using tenant roles

Tenant Roles allow you to provide different versions of Multi-tenant apps with different versions can increase your profits. The screenshot below is taken from Example3, which uses tenant roles, so it a) displays the Role's RoleType, and b) allows you to change the Role's RoleType.

If your application uses tenant roles, then a few things are different:

• When you create a new Role, you can set its RoleType (see Roles explained -> different Role types).
• You can change the RoleType of a Role, but there are restrictions - see this table which defines what you can and can't do.

NOTE: The selecting / deselecting of each Permission is done by a JavaScript method called TogglePermissionSelect. This method is in the wwwroot/js/site.js file in Example 1, 3, 4, and 5.

Delete a Role

Deleting a Role can effect a user so there are two methods:

• QueryUsersUsingThisRole(string roleName): this returns a IQueryable<AuthUser> result, which you can use to find want AuthUsers are using a Role before you decide to delete it.
• DeleteRoleAsync(string roleName, bool removeFromUsers): This deletes the Role with the given roleName. It contains a check if any AuthUsers are using that 'RoleName` and:
  • If the removeFromUsers is true, then deletes the links from the deleted Role and to an AuthUser.
  • If the removeFromUsers is true, then it returns an error.

In Example1's Pages/AuthRoles implementation there is a simple "are you sure you want to delete this" page. But the Example4's RolesController I uses the QueryUsersUsingThisRole method to provide information to the admin user who wants to delete a Role. The screenshot below is an example taken from Example4's Roles\Delete page.

As you can see this lists all the users that Role and asks for a confirmation before it will delete the Role. But if the Role isn't used by any AuthUsers you can just click the Delete button.

List the Permissions in your application

Sometimes it useful to list the Permissions in your application, and the GetPermissionDisplay(bool excludeFilteredPermissions, string groupName = null) will return the PermissionDisplay. The two parameters are:

• excludeFilteredPermissions: If true it will exclude any permissions where the [Display] attribute has its AutoGenerateFilter is set to true. This can be used to not show some of the more powerful Permissions to a normal admin person shouldn't add to a user - see Filtering out advanced Permissions for a more detailed explanation.
• groupName: If its null, then you see all the Permissions, but if you provide a string value the method will only show the Permissions with that GroupName.

The screenshot below is an example taken from Example4's Roles\ListPermissions page.

Additional resources

• Permissions explained
• Setup Permissions
• Bulk Load admin