{"id":4476,"date":"2022-07-19T06:00:12","date_gmt":"2022-07-19T13:00:12","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/cosmosdb\/?p=4476"},"modified":"2022-07-19T08:21:12","modified_gmt":"2022-07-19T15:21:12","slug":"rbac-api-mongodb-preview","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/cosmosdb\/rbac-api-mongodb-preview\/","title":{"rendered":"Role-based access control in Azure Cosmos DB API for MongoDB: Now in preview"},"content":{"rendered":"<p>Role based access control (RBAC) is a much-needed capability in any database for enterprises. It lets you simplify your access control mechanism without added management. We have introduced <a href=\"https:\/\/docs.microsoft.com\/azure\/cosmos-db\/mongodb\/how-to-setup-rbac\" target=\"_blank\" rel=\"noopener\">RBAC in Azure Cosmos DB API for MongoDB<\/a>, which allows you to:<\/p>\n<ol>\n<li>Authorize your data requests with a fine-grained, role-based permission model<\/li>\n<li>Audit your diagnostic logs to retrieve the user identity for each database operation<\/li>\n<\/ol>\n<h4>How does it work?<\/h4>\n<p>API for MongoDB RBAC is built on concepts that are commonly found in other RBAC systems like <a href=\"https:\/\/docs.microsoft.com\/azure\/role-based-access-control\/overview\">Azure RBAC<\/a>, including:<\/p>\n<ul>\n<li>Role definition is a set of actions that one can perform using a given role. These actions map to database operations like read, write, etc. There are built-in roles like \u201c<em>read\u201d<\/em> and you can create custom roles as well<\/li>\n<li>User is the identity represented by a username and password<\/li>\n<li>The user is then mapped to a role through role assignment, this user can perform every action defined in the role definition of the mapped role<\/li>\n<\/ul>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2022\/06\/rbac_mongo.jpg\"><img decoding=\"async\" class=\" wp-image-4478 aligncenter\" src=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2022\/06\/rbac_mongo-300x126.jpg\" alt=\"Image rbac mongo\" width=\"439\" height=\"184\" srcset=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2022\/06\/rbac_mongo-300x126.jpg 300w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2022\/06\/rbac_mongo.jpg 428w\" sizes=\"(max-width: 439px) 100vw, 439px\" \/><\/a><\/p>\n<h4>How to get started?<\/h4>\n<p>Using RBAC is a simple 4 step process.<\/p>\n<h5>1. Enable RBAC on Azure Cosmos DB API for MongoDB<\/h5>\n<p>To use RBAC in API for MongoDB, you need to enable this capability in your Azure Cosmos DB account.<\/p>\n<p><sub>Azure CLI<\/sub><\/p>\n<pre class=\"prettyprint\" style=\"padding-left: 80px;\">az cloud set -n AzureCloud\r\naz login\r\naz account set --subscription &lt;your subscription ID&gt;\r\n\r\naz cosmosdb update -n &lt;account_name&gt; -g &lt;azure_resource_group&gt; --capabilities EnableMongoRoleBasedAccessControl<\/pre>\n<h5>2. Create user definition<\/h5>\n<p>Create user definition with built-in read role definition. There are other built-in roles defined by the system, <a href=\"https:\/\/docs.microsoft.com\/azure\/cosmos-db\/mongodb\/how-to-setup-rbac#built-in-roles\">you can check them out here.<\/a><\/p>\n<p><sub>Azure CLI<\/sub><\/p>\n<pre style=\"padding-left: 40px;\">#!\/bin\/bash\r\n\r\naccount_name=&lt;YOUR_DB_ACCOUNT&gt;\r\nrg=&lt;YOUR_RG&gt;\r\ndb=&lt;YOUR_DB_NAME&gt;\r\nusername=&lt;YOUR_USERNAME&gt;\r\npassword=&lt;YOUR_PASSWORD&gt;\r\n\r\nprintf '{\r\n \u00a0\u00a0 \"Id\": \"'\"$db.$username\"'\",\r\n \u00a0\u00a0 \"UserName\": \"'\"$username\"'\",\r\n \u00a0\u00a0 \"Password\": \"'\"$password\"'\",\r\n \u00a0\u00a0 \"DatabaseName\": \"'\"$db\"'\",\r\n \u00a0\u00a0 \"CustomData\": \"some_random_info\",\r\n \u00a0\u00a0 \"Mechanisms\": \"SCRAM-SHA-256\",\r\n \u00a0\u00a0 \"Roles\": [{\r\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"Role\": \"read\",\r\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"Db\": \"'\"$db\"'\"\r\n \u00a0\u00a0 }]\r\n\u00a0}'&gt;create_user.json\r\n\r\naz cosmosdb mongodb user definition create --account-name $account_name --resource-group $rg --body @create_user.json<\/pre>\n<h5>3. Test RBAC<\/h5>\n<p>You are now ready to use your account using RBAC. Authenticate the client using the username and password provided in creating the user.<\/p>\n<p><sub>Python<\/sub><\/p>\n<pre class=\"prettyprint\" style=\"padding-left: 80px;\">from pymongo import MongoClient\r\n\r\nclient = MongoClient(\"mongodb:\/\/&lt;USERNAME&gt;:&lt;PASSWORD&gt;@&lt;YOUR_HOSTNAME&gt;:10255\/?ssl=true&amp;replicaSet=globaldb&amp;retrywrites=false&amp;maxIdleTimeMS=120000\", username=\"&lt;YOUR_USER&gt;\", password=\"&lt;YOUR_PASSWORD&gt;\", authSource='&lt;YOUR_DATABASE&gt;', authMechanism='SCRAM-SHA-256', appName=\"&lt;YOUR appName FROM CONNECTION STRING IN AZURE PORTAL&gt;\")\r\n\r\ndb = client[\u201c&lt;your_database_name&gt;\u201d]\r\ncol = db[\u201c&lt;your_collection_name&gt;\u201d]\r\n\r\nfor doc in col.find({}):\r\n   print(doc)<\/pre>\n<h5>4. Audit your requests<\/h5>\n<p>Users can audit the operation performed on the database by enabling diagnostics logging. See, <a href=\"https:\/\/docs.microsoft.com\/en-us\/azure\/cosmos-db\/cosmosdb-monitor-resource-logs\">Monitor Azure Cosmos DB data by using Azure Diagnostic settings | Microsoft Docs<\/a><\/p>\n<p>Select <strong>MongoRequests <\/strong>table in the diagnostics logs settings, this table contains <strong>UserId <\/strong>column against each request. This column would be blank for accounts not using RBAC.<\/p>\n<p><a href=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2022\/07\/diagnostics.jpg\"><img decoding=\"async\" class=\" wp-image-4544 aligncenter\" src=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2022\/07\/diagnostics-300x157.jpg\" alt=\"Image diagnostics\" width=\"603\" height=\"316\" srcset=\"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2022\/07\/diagnostics-300x157.jpg 300w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2022\/07\/diagnostics-1024x537.jpg 1024w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2022\/07\/diagnostics-768x403.jpg 768w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2022\/07\/diagnostics-1536x805.jpg 1536w, https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-content\/uploads\/sites\/52\/2022\/07\/diagnostics-2048x1074.jpg 2048w\" sizes=\"(max-width: 603px) 100vw, 603px\" \/><\/a><\/p>\n<p>Use below query to find out the users performing the requests.<\/p>\n<p><sub>KQL (Kusto Query Language)<\/sub><\/p>\n<pre style=\"padding-left: 40px;\">CDBMongoRequests\r\n| where OperationName == \"Find\"\r\n| project DatabaseName, CollectionName, UserId, TimeGenerated<\/pre>\n<p>&nbsp;<\/p>\n<h4>Next steps<\/h4>\n<h5><\/h5>\n<h5>Create custom role definitions<\/h5>\n<p>You can create a new role definition if you need to define custom set of permissions. <a href=\"https:\/\/docs.microsoft.com\/azure\/cosmos-db\/mongodb\/how-to-setup-rbac#azure-cli-rbac-commands\">Checkout full list of Azure CLI commands here<\/a>.<\/p>\n<p><sub>Azure CLI<\/sub><\/p>\n<pre style=\"padding-left: 40px;\">#!\/bin\/bash\r\n\r\naccount_name=&lt;YOUR_DB_ACCOUNT&gt;\r\nrg=&lt;YOUR_RG&gt;\r\ndb=&lt;YOUR_DB_NAME&gt;\r\nrole_name=&lt;YOUR_ROLE_NAME&gt;\r\ncollection_name=&lt;COLLECTION_NAME&gt;\r\n\r\nprintf '{\r\n \u00a0\u00a0 \"Id\": \"'\"$db.$role_name\"'\",\r\n \u00a0\u00a0 \"RoleName\": \"'\"$role_name\"'\",\r\n \u00a0\u00a0 \"Type\": \"CustomRole\",\r\n \u00a0\u00a0 \"DatabaseName\": \"'\"$db\"'\",\r\n \u00a0\u00a0 \"CustomData\": \"some_random_info\",\r\n \u00a0\u00a0 \"Privileges\":[\r\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 {\r\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"Resource\":{\r\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"Db\":\u00a0 \"'\"$db\"'\",\r\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"Collection\": \"'\"$collection_name\"'\"\r\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 },\r\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"Actions\": [\r\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"insert\",\r\n \u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\"find\"\r\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 ]\r\n \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 }\r\n \u00a0\u00a0 ],\r\n \u00a0\u00a0 \"Roles\":[]\r\n\u00a0}'&gt;create_role.json\r\n\r\naz cosmosdb mongodb role definition create --account-name $account_name --resource-group $rg --body @create_role.json<\/pre>\n<h5><\/h5>\n<h5>Enforcing RBAC as the only authentication method<\/h5>\n<p>Disable any other auth mechanism for Azure Cosmos DB by updating the ARM template. Add the following property in your existing template or create a new one.<\/p>\n<p><sub>JSON<\/sub><\/p>\n<pre class=\"prettyprint\" style=\"padding-left: 40px;\">\"resources\": [\r\n    {\r\n        \"type\": \" Microsoft.DocumentDB\/databaseAccounts\",\r\n        \"properties\": {\r\n            \"disableLocalAuth\": true,\r\n        },\r\n    },\r\n ]<\/pre>\n<p>&nbsp;<\/p>\n<h4>Learn more<\/h4>\n<p>The granularity of this permission model lets you control very precisely what a client is allowed to do. Moreover, you can always come back to audit logs and identify what operation was issued by which user in case of any dilemma.<\/p>\n<ul>\n<li>To find out more about current capabilities, limitations, and code samples <a href=\"https:\/\/docs.microsoft.com\/azure\/cosmos-db\/mongodb\/how-to-setup-rbac\" target=\"_blank\" rel=\"noopener\">check out our official documentation<\/a>.<\/li>\n<li>Discover additional features and capabilities about\u00a0<a href=\"https:\/\/aka.ms\/AAgza1u\" target=\"_blank\" rel=\"noopener\">Azure Cosmos DB<\/a>\u00a0and\u00a0<a href=\"https:\/\/aka.ms\/AAgzqws\" target=\"_blank\" rel=\"noopener\">get started for free<\/a>.<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"<p>Role based access control (RBAC) is a much-needed capability in any database for enterprises. It lets you simplify your access control mechanism without added management. We have introduced RBAC in Azure Cosmos DB API for MongoDB, which allows you to: Authorize your data requests with a fine-grained, role-based permission model Audit your diagnostic logs to [&hellip;]<\/p>\n","protected":false},"author":90111,"featured_media":4478,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[15,667],"tags":[],"class_list":["post-4476","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-mongodb-api","category-security"],"acf":[],"blog_post_summary":"<p>Role based access control (RBAC) is a much-needed capability in any database for enterprises. It lets you simplify your access control mechanism without added management. We have introduced RBAC in Azure Cosmos DB API for MongoDB, which allows you to: Authorize your data requests with a fine-grained, role-based permission model Audit your diagnostic logs to [&hellip;]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/4476","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/users\/90111"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/comments?post=4476"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/posts\/4476\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media\/4478"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/media?parent=4476"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/categories?post=4476"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/cosmosdb\/wp-json\/wp\/v2\/tags?post=4476"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}