Predefined Users, Roles and Permissions

This topic describes how to define built-in user accounts and their permissions, which should be created automatically when the application database is initialized.

Create an Administrative Account

Standard Authentication requires an Administrator role and an Administrator user associated with this role. These objects are automatically created using Active Directory authentication. To add these objects manually, do the following:

  • In the module project, reference the DevExpress.ExpressApp.Security.v18.2.dll assembly.
  • Edit the Updater.cs(Updater.vb) file located in the DatabaseUpdate folder of your module project. Override the ModuleUpdater.UpdateDatabaseAfterUpdateSchema method as follows:

    using DevExpress.Persistent.BaseImpl.PermissionPolicy;
    // ...
    public override void UpdateDatabaseAfterUpdateSchema() {
        base.UpdateDatabaseAfterUpdateSchema();
        PermissionPolicyRole adminRole = ObjectSpace.FindObject<PermissionPolicyRole>(
            new BinaryOperator("Name", SecurityStrategy.AdministratorRoleName));
        if (adminRole == null) {
            adminRole = ObjectSpace.CreateObject<PermissionPolicyRole>();
            adminRole.Name = SecurityStrategy.AdministratorRoleName;
            adminRole.IsAdministrative = true;
        }
        PermissionPolicyUser adminUser = ObjectSpace.FindObject<PermissionPolicyUser>(
            new BinaryOperator("UserName", "Administrator"));
        if (adminUser == null) {
            adminUser = ObjectSpace.CreateObject<PermissionPolicyUser>();
            adminUser.UserName = "Administrator";
            adminUser.SetPassword("");
            adminUser.Roles.Add(adminRole);
        }
        ObjectSpace.CommitChanges();
    }
    

PermissionPolicyUser and PermissionPolicyRole persistent objects represent users and roles.

Running the application now displays a login dialog at startup. You can log in as "Administrator" with an empty password (you can pass an alternate password to the SecurityUserBase.SetPassword method), add more users and roles at runtime, or specify more predefined users and roles in the Updater class code.

Set Permissions for Non-Administrative Roles

When the role is not administrative (IsAdministrative property is false), you need to grant required permissions to this role explicitly. You can specify permissions for Create, Read, Write and Delete data operations, and manage access to navigation items.

Permission Policy

First, you should set the Role's Permission Policy. The IPermissionPolicyRole.PermissionPolicy property specifies the Security System behavior when there are no explicitly specified permissions for a specific type, object or member. The available behaviors are listed in the SecurityPermissionPolicy enumeration (DenyAllByDefault, AllowAllByDefault and ReadOnlyAllByDefault).

defaultRole.PermissionPolicy = SecurityPermissionPolicy.AllowAllByDefault;

Access to Navigation Items

The Role's Navigation Permissions manage navigation item access. You can grant or deny permissions for a single navigation item or the whole navigation group using the PermissionSettingHelper.AddNavigationPermission method.

defaultRole.AddNavigationPermission(@"Application/NavigationItems/Items/Default/Items/MyDetails", SecurityPermissionState.Allow);

CRUD Access to all Objects of a Specific Type

To specify permissions for the create, read, update and delete (CRUD) operations with a certain business class, use the PermissionSettingHelper.AddTypePermission<T> method:

defaultRole.AddTypePermission<Contact>(SecurityOperations.Read, SecurityPermissionState.Deny);

The method parameters set is standard for all PermissionSettingHelper methods managing CRUD access:

  • The operations parameter is a string containing a semicolon-separated list of security operations. The SecurityOperations class provides string constants with operation names and their combinations.
  • The state parameter takes a SecurityPermissionState enumeration value (Allow or Deny) which specifies if access is granted or denied.
  • The T generic parameter specifies the business object type for which permissions are assigned.

To override the existing Type Permissions, use the PermissionSettingHelper.SetTypePermission<T> method. It searches for the specified type's first permission in the current role and updates it according to the specified parameters. If the corresponding type permission is not found, it is created.

defaultRole.SetTypePermission<Contact>(SecurityOperations.Read, SecurityPermissionState.Deny);

CRUD Access to an Object that Fits a Criteria

Object Permissions manage access to business object instances that fit a specified criterion. The PermissionSettingHelper.AddObjectPermission<T> method finds the given type's first type permission in the current role and adds the object permission to it. If the appropriate type permission is not found, the method creates it. The additional criteria parameter specifies which criteria expression the target object should match.

defaultRole.AddObjectPermission<PermissionPolicyUser>(SecurityOperations.Read, "[Oid] = CurrentUserId()", SecurityPermissionState.Allow);

CRUD Access to Business Class Properties

You can manage access to individual members of the business class using Member Permissions. The PermissionSettingHelper.AddMemberPermission<T> method finds the given type's first type permission in the current role and adds the member permission to it. If the appropriate type permission is not found, the method creates it. The members parameter is a string containing a semicolon-separated list of target member names, and the criteria parameter is a string containing the criteria expression that specifies the target objects. If the criteria are null (Nothing in VB), the member permission is applied to an object of the given type.

defaultRole.AddMemberPermission<Person>(SecurityOperations.Read, "Name", null, SecurityPermissionState.Allow);

You can also specify the criteria to apply member permissions to objects that fit this criteria:

defaultRole.AddMemberPermission<Person>(SecurityOperations.Read, "Name", "[Name] = 'John'", SecurityPermissionState.Allow);

Refer to the SecurityDemo sources for more examples on how to create predefined users and roles. This demo application is available in the %PUBLIC%\Documents\DevExpress Demos 18.2\Components\eXpressApp Framework\SecurityDemo folder by default.