DocumentDB – Access Control ”; Previous Next DocumentDB provides the concepts to control access to DocumentDB resources. Access to DocumentDB resources is governed by a master key token or a resource token. Connections based on resource tokens can only access the resources specified by the tokens and no other resources. Resource tokens are based on user permissions. First you create one or more users, and these are defined at the database level. Then you create one or more permissions for each user, based on the resources that you want to allow each user to access. Each permission generates a resource token that allows either read-only or full access to a given resource and that can be any user resource within the database. Users are defined at the database level and permissions are defined for each user. Users and permissions apply to all collections in the database. Let’s take a look at a simple example in which we will learn how to define users and permissions to achieve granular security in DocumentDB. We will start with a new DocumentClient and query for the myfirstdb database. private static async Task CreateDocumentClient() { // Create a new instance of the DocumentClient using (var client = new DocumentClient(new Uri(EndpointUrl), AuthorizationKey)) { database = client.CreateDatabaseQuery(“SELECT * FROM c WHERE c.id = ”myfirstdb””).AsEnumerable().First(); collection = client.CreateDocumentCollectionQuery(database.CollectionsLink, “SELECT * FROM c WHERE c.id = ”MyCollection””).AsEnumerable().First(); var alice = await CreateUser(client, “Alice”); var tom = await CreateUser(client, “Tom”); } } Following is the implementation for CreateUser. private async static Task<User> CreateUser(DocumentClient client, string userId) { Console.WriteLine(); Console.WriteLine(“**** Create User {0} in {1} ****”, userId, database.Id); var userDefinition = new User { Id = userId }; var result = await client.CreateUserAsync(database.SelfLink, userDefinition); var user = result.Resource; Console.WriteLine(“Created new user”); ViewUser(user); return user; } Step 1 − Create two users, Alice and Tom like any resource we create, we construct a definition object with the desired Id and call the create method and in this case we”re calling CreateUserAsync with the database”s SelfLink and the userDefinition. We get back the result from whose resource property we obtain the newly created user object. Now to see these two new users in the database. private static void ViewUsers(DocumentClient client) { Console.WriteLine(); Console.WriteLine(“**** View Users in {0} ****”, database.Id); var users = client.CreateUserQuery(database.UsersLink).ToList(); var i = 0; foreach (var user in users) { i++; Console.WriteLine(); Console.WriteLine(“User #{0}”, i); ViewUser(user); } Console.WriteLine(); Console.WriteLine(“Total users in database {0}: {1}”, database.Id, users.Count); } private static void ViewUser(User user) { Console.WriteLine(“User ID: {0} “, user.Id); Console.WriteLine(“Resource ID: {0} “, user.ResourceId); Console.WriteLine(“Self Link: {0} “, user.SelfLink); Console.WriteLine(“Permissions Link: {0} “, user.PermissionsLink); Console.WriteLine(“Timestamp: {0} “, user.Timestamp); } Step 2 − Call CreateUserQuery, against the database”s UsersLink to retrieve a list of all users. Then loop through them and view their properties. Now we have to create them first. So let”s say that we wanted to allow Alice read/write permissions to the MyCollection collection, but Tom can only read documents in the collection. await CreatePermission(client, alice, “Alice Collection Access”, PermissionMode.All, collection); await CreatePermission(client, tom, “Tom Collection Access”, PermissionMode.Read, collection); Step 3− Create a permission on a resource that is MyCollection collection so we need to get that resource a SelfLink. Step 4 − Then create a Permission.All on this collection for Alice and a Permission.Read on this collection for Tom. Following is the implementation for CreatePermission. private async static Task CreatePermission(DocumentClient client, User user, string permId, PermissionMode permissionMode, string resourceLink) { Console.WriteLine(); Console.WriteLine(“**** Create Permission {0} for {1} ****”, permId, user.Id); var permDefinition = new Permission { Id = permId, PermissionMode = permissionMode, ResourceLink = resourceLink }; var result = await client.CreatePermissionAsync(user.SelfLink, permDefinition); var perm = result.Resource; Console.WriteLine(“Created new permission”); ViewPermission(perm); } As you should come to expect by now, we do this by creating a definition object for the new permission, which includes an Id and a permissionMode, which is either Permission.All or Permission.Read, and the SelfLink of the resource that”s being secured by the permission. Step 5 − Call CreatePermissionAsync and get the created permission from the resource property in the result. To view the created permission, following is the implementation of ViewPermissions. private static void ViewPermissions(DocumentClient client, User user) { Console.WriteLine(); Console.WriteLine(“**** View Permissions for {0} ****”, user.Id); var perms = client.CreatePermissionQuery(user.PermissionsLink).ToList(); var i = 0; foreach (var perm in perms) { i++; Console.WriteLine(); Console.WriteLine(“Permission #{0}”, i); ViewPermission(perm); } Console.WriteLine(); Console.WriteLine(“Total permissions for {0}: {1}”, user.Id, perms.Count); } private static void ViewPermission(Permission perm) { Console.WriteLine(“Permission ID: {0} “, perm.Id); Console.WriteLine(“Resource ID: {0} “, perm.ResourceId); Console.WriteLine(“Permission Mode: {0} “, perm.PermissionMode); Console.WriteLine(“Token: {0} “, perm.Token); Console.WriteLine(“Timestamp: {0} “, perm.Timestamp); } This time, it”s a permission query against the user”s permissions link and we simply list each permission returned for the user. Let”s delete the Alice’s and Tom’s permissions. await DeletePermission(client, alice, “Alice Collection Access”); await DeletePermission(client, tom, “Tom Collection Access”); Following is the implementation for DeletePermission. private async static Task DeletePermission(DocumentClient client, User user, string permId) { Console.WriteLine(); Console.WriteLine(“**** Delete Permission {0} from {1} ****”, permId, user.Id); var query = new SqlQuerySpec { QueryText = “SELECT * FROM c WHERE c.id = @id”, Parameters = new SqlParameterCollection { new SqlParameter { Name = “@id”, Value = permId } } }; Permission perm = client.CreatePermissionQuery(user.PermissionsLink, query) .AsEnumerable().First(); await client.DeletePermissionAsync(perm.SelfLink); Console.WriteLine(“Deleted permission {0} from user {1}”, permId, user.Id); } Step 6 − To delete permissions, query by permission Id to get the SelfLink, and then using the SelfLink to delete the permission. Next, let’s delete the users themselves. Let’s delete both the users. await DeleteUser(client, “Alice”); await DeleteUser(client, “Tom”); Following is the implementation for DeleteUser. private async static Task DeleteUser(DocumentClient client, string userId) { Console.WriteLine(); Console.WriteLine(“**** Delete User {0} in {1} ****”, userId, database.Id); var query = new SqlQuerySpec { QueryText = “SELECT * FROM c WHERE c.id = @id”, Parameters = new SqlParameterCollection { new SqlParameter { Name = “@id”, Value = userId } } }; User user = client.CreateUserQuery(database.SelfLink, query).AsEnumerable().First(); await client.DeleteUserAsync(user.SelfLink); Console.WriteLine(“Deleted user {0} from database {1}”, userId, database.Id); } Step 7 − First