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 uses the Role's RoleType parameter to provide - see this section of the Roles Explained document which explains the different type of Roles.

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 Example uses the full suite of the multi-tenant Roles feature.

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 'AppAdmin@g1.com' to access all the admin features, and as 'admin@4uInc.com' 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.

The screenshot below is an example taken from Example4's Roles\Edit page (Example1's version is the same).

Things to point out in this screenshot:

• You can edit the Role's Description.
• If your application is using the multi-tenant RoleType feature then a RoleType dropdown will be shown on an create or update.
• You add/remove the Permissions in the Role by toggling the Select / Selected by clicking on the button to the right of the Permission information.
• The "Add Role" works the same way as the Edit, but you need to provide a RoleName and call the CreateRoleToPermissionsAsync method instead of UpdateRoleToPermissionsAsync

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 both Example1 and Example4.

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