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 theAuthRolesAdminService can be found here and has plenty of comments. Also the Example4's RolesController contains a fully working Roles admin methods / pages, but you have to log in as '[email protected]' or '[email protected]' to access all the features.

Here is a list of the various methods in the IAuthRolesAdminService, with example pages from Example4's RolesController.

Get a list of the roles

The QueryRoleToPermissions 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.

The method is good for putting up 'Role Admin' page in your application. The Index method / View in the Example4's RolesController. This lists all the roles, but also provides create, update and delete control over these roles - see the screenshot below from Example4's Roles\Index page.

Things to point out in this screenshot:

• There is a 'Create new Role` button top left.
• There are a 'Edit' and 'Delete' link on the right of each Role.
• 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

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

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

Things to point out in this screenshot:

• You can edit the Role's Description.
• 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.

NOTE: Add Role can be implemented in the same way as the edit Role feature, but you must provide a new, unique RoleName.

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 the Example4's RolesController I use both of these 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 service