How to: Create a Role-based Application

  • Article

Most business applications have security features to prevent unauthorized users from reading, manipulating, or deleting data. In LightSwitch, you can make your application more secure by implementing authentication and authorization, through which users must identify themselves in order to access the application. You can also create user roles that have various levels of access to particular screens and data, and you can assign individual users to roles.

For example, a payroll application could allow employees to view, but not change, their payroll information. However, a payroll supervisor could be given permission to view and change the employee information. The employees would be assigned to the Employee role and the supervisor would be assigned to the Supervisor role.

Authentication

The first step in securing your application is to enable authentication. You can use either Forms authentication or Windows authentication. Forms authentication is managed by the application itself, and a user must supply a username and a password to access the application. In Windows authentication, the credentials that were used to log on to the computer where the application is run are used to authenticate the application user, and no additional username or password is required. In both cases, an application administrator maintains a list of authorized users; in Forms authentication, the administrator also maintains encrypted passwords.

To enable authentication

  1. In Solution Explorer, double-click the Properties node.

  2. In the Application Designer, click the Access Control tab.

  3. In the Select the type of authentication to use: list, click either Use Windows authentication or Use Forms authentication.

    If you select Use Windows authentication, click either Allow only users specified in the Users screen of your application or Allow any authenticated Windows user.

    The application will now require users to provide credentials in order to access the application.

To disable authentication

  1. In Solution Explorer, double-click the Properties node.

  2. In the Application Designer, click the Access Control tab.

  3. In the Select the type of authentication to use: list, click Do not enable authentication.

    The application will not require users to provide credentials in order to access the application, and any user can access every part of the application.

Permissions

The next step in securing your application is to create permissions. You can define permissions for screens, commands, data entities, and queries. First, define a permission object in the Application Designer. Then, you can reference the object in code, in one of the Can methods such as CanRun<ScreenName> or <QueryName>_CanExecute. Code in these methods typically checks whether the current user or role has the permission, and then displays the form or executes the query only if permission is validated.

To test your code, run the application as both a user who has the permission and as a user who does not. By setting debug permissions, you can impersonate a user when you test or debug the application.

To create a permission

  1. In Solution Explorer, double-click the Properties node.

  2. In the Application Designer, click the Access Control tab.

  3. In the Define permissions or select permissions to use for debugging grid, in the Name column, click <Add New Permission>, and then type a programmatic name for the permission.

    The name must begin with an alphabetical character, and it can only contain alphabetical or numeric characters, or underscores.

  4. In the Display Name column, type the name of the permission as you want it to appear in the screen that the application administrator will use to assign roles.

  5. In the Description column, type a description of the permission.

  6. Press ENTER.

To write code to set permissions for a screen

  1. In Solution Explorer, double-click a screen node to open the Screen Designer for that screen.

  2. In the Screen Designer, in the Write Code list, click CanRun<ScreenName>, where <ScreenName> is the name of the selected screen.

  3. In the Code Editor, in the CanRun<ScreenName> method, type the following code.

    If Current.User.HasPermission(Can_View_Products) Then
    result =  True
Else
    result = False
End If

    if (Current.User.HasPermission(Permissions.Can_View_Products)) 
{
    result = true;
} 
else 
{
    result = false;
}

    This code will be evaluated every time that the application starts.

    Note

    Notice that the example code checks for a permission named Can_View_Products. Wherever it appears, substitute the name of a permission that you have defined in your application.

To write code to set permissions for a command

  1. In Solution Explorer, double-click a screen node to open the Screen Designer for that screen.

  2. In the Screen Content Tree pane of the Screen Designer, expand a command node and select the command for which you want to write code.

  3. In the Screen Designer, in the Write Code list, click <ButtonName>_CanExecute, where <ButtonName> is the name of the selected command.

  4. In the Code Editor, in the <ButtonName>_CanExecute method, type the code you want.

    Note

    For an example of code, see "To write code to set permissions for a screen" earlier in this topic.

To write code to set permissions for an entity

  1. In Solution Explorer, double-click an entity node to open the Entity Designer for that entity.

  2. In the Entity Designer, in the Write Code list, click one of the <EntityName>_Can<Operation> methods, where <EntityName> is the name of the entity and <Operation> is the name of the operation for which you want to write code.

    Note

    The methods that are available vary by context. Some examples are CanDelete and CanUpdate.

  3. In the Code Editor, in the<EntityName>_Can<Operation> method, type the code you want.

    Note

    For an example of code, see "To write code to set permissions for a screen" earlier in this topic.

To write code to set permissions for a query

  1. In Solution Explorer, double-click a query node to open the Entity Designer for that query.

  2. In the Query Designer, in the Write Code list, click one of the <QueryName>_CanExecute methods, where <QueryName> is the name of the query.

  3. In the Code Editor, in the <QueryName>_CanExecute method, type the code you want.

    Note

    For an example of code, see "To write code to set permissions for a screen" earlier in this topic.

To enable permissions for debugging

  1. In Solution Explorer, double-click the Properties node.

  2. In the Application Designer, click the Access Control tab.

  3. In the Define permissions or select permissions to use for debugging grid, select the permission that you want to enable for debugging and then select the Granted for debug option.

Publishing

The final step in securing your application is to publish it. When you publish for the first time, you must provide authentication information for a default administrator. When you publish again, you do not have to repeat this step.

To provide authentication information when you publish an application

  1. In the LightSwitch Publish Application Wizard, on the Specify Authentication configuration page, select the Should Authentication Information be deployed with the application? section and then click Yes, deploy Authentication information at this time.

  2. In the User Name: field, type a username.

    If you are using Windows authentication, this must be a valid Windows logon name that has the form domain\username.

  3. In the Full Name: field, type the full name of the user who will be the default administrator.

  4. In the Password: field, type a password.

    Note

    If you are using Windows authentication, the Password: and Confirm Password: fields do not appear .

  5. In the Confirm Password: field, type the password again.

    Make sure to remember the username and password because they will be required the first time that the application is run.

  6. Finish publishing the application.

Roles and Users

The application administrator must run the published application the first time. The administrator then uses the Roles screen and the Users screen to define roles, assign permissions to the roles, and assign roles to users. An administrator can access these screens in the running application at design time or when it is deployed. At design time, set a debug permission to access the screens. In a deployed application, anyone who has been granted the Security Administration permission can access the screens.

Note

To log on, application administrators must use the username and password that you specified when you published the application.

To define a role and assign permissions

  1. In an application that is running under administrator permissions, click the Roles menu to open the Roles screen.

  2. In the Roles pane, click the +… (Add) button.

  3. In the Add New Role dialog box, type a name for the role, and then click OK.

  4. In the Permissions pane, click the +… (Add) button.

    A new row appears in the Permissions grid.

  5. In the first column of the grid, select a permission on the drop-down list.

    The list contains all of the available permissions for your application. You can add as many permissions as you need, but for each one, you must click the +… (Add) button and select it.

  6. On the application toolbar, click Save to save your changes.

To add a user

  1. Click the Users menu under Administration to display the Users screen.

  2. In the Users pane, click the +… (Add) button.

  3. In the right pane, in the User Name: field, type a username.

    If you are using Windows authentication, this must be a valid username in the form of an alias (hsnyder), domain and alias (example\hsnyder), alias and domain (hsnyder@example.com), or fully qualified domain name and alias (northamerica.corp.example.com\hsnyder), and it must be less than 256 characters. If you are using Forms authentication, the username must be unique and must be less than 256 characters.

  4. In the Full Name: field, type the user’s full name.

    The information in the Full Name field is used only for display purposes. The typical format is given name followed by surname.

    Note

    For Windows authentication, the Full Name field is automatically populated based on the username and cannot be edited.

  5. In the Password: field, type a password.

    Note

    The Password: and Confirm Password: fields do not appear if you are using Windows authentication.

  6. In the Confirm Password: field, type the same password.

  7. In the Roles pane, click Add, and then in the Roles drop-down list, select a role.

    You can assign the user to multiple roles by repeating this step for each role.

  8. On the application toolbar, click Save to save the changes.

To remove a user

  1. Click the Users menu under Administration to display the Users screen.

  2. In the Users pane, select the user account that you want to remove and then click the X (delete) button.

    Note

    If a user is logged on an account that is deleted, the user can no longer save or access data on the server. The user tries to access data from the server, an Access Denied message will be displayed.

  3. On the application toolbar, click Save to save the changes.

See Also

Concepts

Security Considerations for LightSwitch

Other Resources

Projects: The Container for Your Application