Using the SecurityData service in LightSwitch

  • Article

In this blog post, I’m going to describe how LightSwitch developers can programmatically access the security data contained in a LightSwitch application.  Having access to this data is useful for any number of reasons.  For example, you can use this API to programmatically add new users to the application.

This data is exposed in code as entities, just like with your own custom data.  So it’s an easy and familiar API to work with.  And it’s available from both client or server code.

First I’d like to describe the security data model.  Here’s a UML diagram describing the service, entities, and supporting classes:

image

SecurityData

This is the data service class that provides access to the security entities as well as a few security-related methods.  It is available from your DataWorkspace object via its SecurityData property.

SecurityData is a LightSwitch data service and behaves in the same way as the data service that gets generated when you add a data source to LightSwitch.  It exposes the same type of query and save methods.  It just operates on the built-in security entities instead of your entities.

Some important notes regarding having access to your application’s security data:
In a running LightSwitch application, users which do not have the SecurityAdministration permission are only allowed to read security data; they cannot insert, update, or delete it.  In addition, those users are only able to read security data that is relevant to themselves.  So if a user named Bob, who does not have the SecurityAdministration permission, queries the UserRegistrations entity set, he will only see a UserRegistration with the name of Bob.  He will not be able to see that there also exists a UserRegistration with the name of Kim since he is not logged in as Kim.  Similarly with roles, if Bob queries the Roles entity set, he can see that a role named SalesPerson exists because he is assigned to that role.  But he cannot see that a role named Manager exists because he is not assigned to that role.

Users which do have the SecurityAdministration permission are not restricted in their access to security data.  They are able to read all stored security data and have the ability to modify it.

In addition to entity sets, SecurityData also exposes a few useful methods:

  • ChangePassword
    This method allows a user to change their own password.  They need to supply their old password in order to do so.  If the oldPassword parameter doesn’t match the current password or the new password doesn’t conform to the password requirements, an exception will be thrown.  This method is only relevant when Forms authentication is being used.  This method can be called by any user; they do not require the SecurityAdministration permission.
  • GetWindowsUserInfo
    This method validates and resolve a Windows account name into a normalized value and retrieve the full name (display name) of that user.  As an example, let’s say that you passed “kim@contoso.com” as the parameter to this operation, it would return back a WindowsUserInfo object with the FullName property set to “Kim Abercrombie” and the NormalizedUserName property set to “contoso\kim”.  If the service is unable to resolve the username parameter to a known account, an exception will be thrown.  This method is only relevant when Windows authentication is being used.  This method can only be called by users that have the SecurityAdministration permission.
  • IsValidPassword
    This method checks whether the supplied password meets the password requirements of the application.  This happens automatically when attempting to add a new user or updating their password but this method allows the caller to preemptively check the password which can be useful for validation UI purposes.  This method is only relevant when Forms authentication is being used.  This method can only be called by users that have the SecurityAdministration permission.

UserRegistration

The UserRegistration entity represents a user that has access to the application.  (In VS 11, it can also represent an Active Directory security group when Windows authentication is being used).  When using Forms authentication, all the UserRegistration properties (UserName, FullName, Password) are required.  When using Windows authentication, only the UserName property is required; FullName is populated dynamically based on the UserName and Password is irrelevant.

Here is some example code using the UserRegistration entity:

C#:

 // Create a new UserRegistration (Windows authentication)
UserRegistration user = this.DataWorkspace.SecurityData.UserRegistrations.AddNew();
user.UserName = "contoso\\kim";
this.DataWorkspace.SecurityData.SaveChanges();

// Create a new UserRegistration (Forms authentication)
UserRegistration user = this.DataWorkspace.SecurityData.UserRegistrations.AddNew();
user.UserName = "kim_abercrombie";
user.FullName = "Kim Abercrombie";
user.Password = "mysecretpassword!";
this.DataWorkspace.SecurityData.SaveChanges();

// Iterate through all UserRegistrations
foreach (UserRegistration user in this.DataWorkspace.SecurityData.UserRegistrations)
{
}

// Find a specific UserRegistration (Windows authentication)
UserRegistration user = this.DataWorkspace.SecurityData.UserRegistrations_Single("contoso\\kim");

// Find a specific UserRegistration (Forms authentication)
UserRegistration user = this.DataWorkspace.SecurityData.UserRegistrations_Single("kim_abercrombie");

VB:

 ' Create a new UserRegistration (Windows authentication)
Dim user As UserRegistration = Me.DataWorkspace.SecurityData.UserRegistrations.AddNew()
user.UserName = "contoso\\kim"
Me.DataWorkspace.SecurityData.SaveChanges()

' Create a new UserRegistration (Forms authentication)
Dim user As UserRegistration = Me.DataWorkspace.SecurityData.UserRegistrations.AddNew()
user.UserName = "kim_abercrombie"
user.FullName = "Kim Abercrombie"
user.Password = "mysecretpassword!"
Me.DataWorkspace.SecurityData.SaveChanges()

' Iterate through all UserRegistrations
For Each user As UserRegistration In Me.DataWorkspace.SecurityData.UserRegistrations
Next

' Find a specific UserRegistration (Windows authentication)
Dim user As UserRegistration = Me.DataWorkspace.SecurityData.UserRegistrations_Single("contoso\\kim")

' Find a specific UserRegistration (Forms authentication)
Dim user As UserRegistration = Me.DataWorkspace.SecurityData.UserRegistrations_Single("kim_abercrombie")

Role

The Role entity represents a grouping of users with common characteristics.  Examples of roles in an application include “Sales Person” and “Manager”.  You can then configure your application security around these roles.

Here is some example code using the Role entity:

C#:

 // Create a new role
Role role = this.DataWorkspace.SecurityData.Roles.AddNew();
role.Name = "Manager";
this.DataWorkspace.SecurityData.SaveChanges();

// Iterate through all Roles
foreach (Role role in this.DataWorkspace.SecurityData.Roles)
{
}

// Find a specific role
Role role = this.DataWorkspace.SecurityData.Roles_Single("Manager");

VB:

 ' Create a new role
Dim role As Role = Me.DataWorkspace.SecurityData.Roles.AddNew()
role.Name = "Manager"
Me.DataWorkspace.SecurityData.SaveChanges()

' Iterate through all Roles
For Each role As Role In Me.DataWorkspace.SecurityData.Roles
Next

' Find a specific role
Dim role As Role = Me.DataWorkspace.SecurityData.Roles_Single("Manager")

 

RoleAssignment

The RoleAssignment entity represents a mapping between a Role and a UserRegistration.  It is how you define that a user belongs to a role.

Here is some example code using the RoleAssignment entity:

C#

 // Assign Kim to the Manager role
UserRegistration user = this.DataWorkspace.SecurityData.UserRegistrations_Single("contoso\\kim");
Role role = this.DataWorkspace.SecurityData.Roles_Single("Manager");
RoleAssignment roleAssignment = user.RoleAssignments.AddNew();
roleAssignment.Role = role;
this.DataWorkspace.SecurityData.SaveChanges();

// Find which roles Kim is assigned to
UserRegistration user = this.DataWorkspace.SecurityData.UserRegistrations_Single("contoso\\kim");
foreach (RoleAssignment roleAssignment in user.RoleAssignments)
{
    Role role = roleAssignment.Role;
}

VB:

 ' Assign Kim to the Manager role
Dim user As UserRegistration = Me.DataWorkspace.SecurityData.UserRegistrations_Single("contoso\\kim")
Dim role As Role = Me.DataWorkspace.SecurityData.Roles_Single("Manager")
Dim roleAssignment As RoleAssignment = user.RoleAssignments.AddNew()
roleAssignment.Role = role
Me.DataWorkspace.SecurityData.SaveChanges()

' Find which roles Kim is assigned to
Dim user As UserRegistration = Me.DataWorkspace.SecurityData.UserRegistrations_Single("contoso\\kim")
For Each roleAssignment As RoleAssignment In user.RoleAssignments
    Dim role As Role = roleAssignment.Role
Next

 

Permission

The Permission entity represents an action that a logged in user is permitted to do within the application.  Examples of permissions in an application include “CanRejectSalesOrder” and “CanUpdateInventory”.  Permissions are different than the rest of the security data because they are read-only.  The permissions that are available map to the permissions that were defined within the Access Control tab of the application properties of a LightSwitch project:

image 

Here is some example code using the Permission entity:

C#:

 // Iterate through all Permissions
foreach (Permission permission in this.DataWorkspace.SecurityData.Permissions)
{
}

// Find a specific Permission
Permission permission = this.DataWorkspace.SecurityData.Permissions_Single(Permissions.CanRejectSalesOrder);

VB:

 ' Iterate through all Permissions
For Each permission As Permission In Me.DataWorkspace.SecurityData.Permissions
Next

' Find a specific Permission
Dim permission As Permission = Me.DataWorkspace.SecurityData.Permissions_Single(Permissions.CanRejectSalesOrder)

 

RolePermission

The RolePermission entity represents a mapping between a Role and a Permission.  It is how you define that a permission is assigned to a role.

Here is some example code using the RolePermission entity:

C#:

 // Assign CanRejectSalesOrder permission to Manager role
Role role = this.DataWorkspace.SecurityData.Roles_Single("Manager");
Permission permission = this.DataWorkspace.SecurityData.Permissions_Single(Permissions.CanRejectSalesOrder);
RolePermission rolePermission = role.RolePermissions.AddNew();
rolePermission.Permission = permission;
this.DataWorkspace.SecurityData.SaveChanges();

// Find which permissions are assigned to the Manager role
Role role = this.DataWorkspace.SecurityData.Roles_Single("Manager");
foreach (RolePermission rolePermission in role.RolePermissions)
{
    Permission permission = rolePermission.Permission;
}

VB:

 ' Assign CanRejectSalesOrder permission to Manager role
Dim role As Role = Me.DataWorkspace.SecurityData.Roles_Single("Manager")
Dim permission As Permission = Me.DataWorkspace.SecurityData.Permissions_Single(Permissions.CanRejectSalesOrder)
Dim rolePermission As RolePermission = role.RolePermissions.AddNew()
rolePermission.Permission = permission
Me.DataWorkspace.SecurityData.SaveChanges()

' Find which permissions are assigned to the Manager role
Dim role As Role = Me.DataWorkspace.SecurityData.Roles_Single("Manager")
For Each rolePermission As RolePermission In role.RolePermissions
    Dim permission As Permission = rolePermission.Permission
Next

 

Conclusion

Using the SecurityData service and the entities it exposes, you can accomplish all kinds of interesting scenarios that require dynamic management of your application’s security data.  I hope you’ve found this blog post helpful in your work.  Happy coding.