mgmt, document on managed identity and RBAC (Azure#18783)

Author: weidongxu-microsoft

sdk/resourcemanager/azure-resourcemanager-authorization/src/main/java/com/azure/resourcemanager/authorization/models/BuiltInRole.java

@@ -147,6 +147,38 @@ public final class BuiltInRole extends ExpandableStringEnum<BuiltInRole> {
     /** A role that can manage websites, but not the web plans to which they are connected. */
     public static final BuiltInRole WEBSITE_CONTRIBUTOR = BuiltInRole.fromString("Website Contributor");
 
+    // Storage data related roles
+    /** Storage Account Key Operators are allowed to list and regenerate keys on Storage Accounts. */
+    public static final BuiltInRole STORAGE_ACCOUNT_KEY_OPERATOR_SERVICE_ROLE =
+        BuiltInRole.fromString("Storage Account Key Operator Service Role");
+    /** Allows for read, write and delete access to Azure Storage blob containers and data. */
+    public static final BuiltInRole STORAGE_BLOB_DATA_CONTRIBUTOR =
+        BuiltInRole.fromString("Storage Blob Data Contributor");
+    /** Allows for full access to Azure Storage blob containers and data, including assigning POSIX access control. */
+    public static final BuiltInRole STORAGE_BLOB_DATA_OWNER =
+        BuiltInRole.fromString("Storage Blob Data Owner");
+    /** Allows for read access to Azure Storage blob containers and data. */
+    public static final BuiltInRole STORAGE_BLOB_DATA_READER =
+        BuiltInRole.fromString("Storage Blob Data Reader");
+    /** Allows for read, write, and delete access to Azure Storage queues and queue messages. */
+    public static final BuiltInRole STORAGE_QUEUE_DATA_CONTRIBUTOR =
+        BuiltInRole.fromString("Storage Queue Data Contributor");
+    /** Allows for peek, receive, and delete access to Azure Storage queue messages. */
+    public static final BuiltInRole STORAGE_QUEUE_DATA_MESSAGE_PROCESSOR =
+        BuiltInRole.fromString("Storage Queue Data Message Processor");
+    /** Allows for sending of Azure Storage queue messages. */
+    public static final BuiltInRole STORAGE_QUEUE_DATA_MESSAGE_SENDER =
+        BuiltInRole.fromString("Storage Queue Data Message Sender");
+    /** Allows for read access to Azure Storage queues and queue messages. */
+    public static final BuiltInRole STORAGE_QUEUE_DATA_READER =
+        BuiltInRole.fromString("Storage Queue Data Reader");
+    /** Allows for read access to Azure File Share over SMB. */
+    public static final BuiltInRole STORAGE_FILE_DATA_SMB_SHARE_READER =
+        BuiltInRole.fromString("Storage File Data SMB Share Reader");
+    /** Allows for read, write, and delete access in Azure Storage file shares over SMB. */
+    public static final BuiltInRole STORAGE_FILE_DATA_SMB_SHARE_CONTRIBUTOR =
+        BuiltInRole.fromString("Storage File Data SMB Share Contributor");
+
     /**
      * Finds or creates a role instance based on the specified name.
      *

sdk/resourcemanager/azure-resourcemanager-authorization/src/test/java/com/azure/resourcemanager/authorization/RoleDefinitionTests.java

@@ -3,10 +3,14 @@
 
 package com.azure.resourcemanager.authorization;
 
+import com.azure.core.http.rest.PagedIterable;
 import com.azure.resourcemanager.authorization.models.RoleDefinition;
 import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 
+import java.util.Locale;
+
 public class RoleDefinitionTests extends GraphRbacManagementTest {
     @Test
     public void canGetRoleByRoleName() throws Exception {
@@ -17,4 +21,25 @@ public void canGetRoleByRoleName() throws Exception {
         Assertions.assertNotNull(roleDefinition);
         Assertions.assertEquals("Contributor", roleDefinition.roleName());
     }
+
+    @Test
+    @Disabled("Util to generate missing built-in role")
+    public void generateMissingRole() {
+        PagedIterable<RoleDefinition> roleDefinitions =
+            authorizationManager.roleDefinitions().listByScope("subscriptions/" + resourceManager.subscriptionId());
+
+        StringBuilder sb = new StringBuilder();
+
+        roleDefinitions.stream()
+            //.filter(r -> r.roleName().startsWith("Storage"))
+            .forEach(r -> {
+                String roleEnumName = r.roleName().toUpperCase(Locale.ROOT).replaceAll(" ", "_");
+
+                sb.append("/** ").append(r.description()).append(". */").append(System.lineSeparator())
+                    .append("public static final BuiltInRole ").append(roleEnumName).append(" =").append(System.lineSeparator())
+                    .append("    BuiltInRole.fromString(\"").append(r.roleName()).append("\");").append(System.lineSeparator());
+            });
+
+        System.out.print(sb.toString());
+    }
 }

sdk/resourcemanager/docs/RBAC.md

@@ -0,0 +1,122 @@
+# Introduction to Managed Identity and Role-Based Access Control (RBAC)
+
+[Managed identity][managed_identity] and [role-based access control][rbac] are commonly used together for identity and access management.
+
+Managed identity provides an identity for the Azure resource in Azure Active Directory, and uses it to obtain Azure AD token.
+RBAC enforces the role, scope, and access control of that managed identity. 
+
+They are useful in scenarios of enabling Azure virtual machine or web app to either manage Azure resource, or access data in Azure resource.
+
+The role of Owner is required for assigning role to managed identity. It can be configured from Azure Active Directory blade in Portal, or by Azure CLI.
+
+## Managing Azure resource
+
+Sample code to enable system-assigned managed identity to a virtual machine, and give it the role of contributor to a resource group.
+```java
+virtualMachine.update()
+    .withSystemAssignedManagedServiceIdentity()
+    .withSystemAssignedIdentityBasedAccessTo(resourceGroup.id(), BuiltInRole.CONTRIBUTOR)
+    .apply();
+```
+
+It allows code running in this particular virtual machine to manage other Azure resource on the target resource group.
+
+Managed identity can be enabled with similar code on Azure web app.
+
+SDK will support managed identity on Azure Kubernetes in the future.
+
+## Accessing data in Azure resource
+
+### Storage account
+
+Sample code to enable system-assigned managed identity to a web app, and give it the role of blob data contributor to a storage account.
+```java
+webApp.update()
+    .withSystemAssignedManagedServiceIdentity()
+    .withSystemAssignedIdentityBasedAccessTo(storageAccount.id, BuiltInRole.STORAGE_BLOB_DATA_CONTRIBUTOR)
+    .apply();
+```
+
+It allows code running in this particular web app to access blob data in the target storage account.
+
+### Key vault
+
+RBAC on key vault is in preview. SDK will support this feature in the future.
+
+For now, SDK supports access policies for key vault.
+
+Sample code to allow access of secret to user-assigned managed identity.
+```java
+vault.update()
+    .defineAccessPolicy()
+        .forObjectId(identity.principalId())
+        .allowSecretPermissions(SecretPermissions.GET)
+        .attach()
+    .apply();
+```
+
+For system-assigned managed identity, use e.g. `virtualMachine.systemAssignedManagedServiceIdentityPrincipalId()` in place of `identity.principalId()`.
+
+## Accessing Azure Active Directory
+
+SDK provides limited support for accessing Azure Active Directory, generally only for querying applications, users, groups, and service principals.
+
+This requires additional permission from Azure Active Directory, which can be configured from Azure Active Directory blade in Portal, or by Azure CLI.
+
+Since 2.2.0, SDK switched from [Azure Active Directory Grpah API][aad_graph] to [Microsoft Graph API][microsoft_graph].
+
+Permission required (since 2.2.0):
+- Access application and service principal: Microsoft Graph, Application permission, [Application.Read.All](https://docs.microsoft.com/graph/api/application-list?view=graph-rest-1.0&tabs=http#permissions)
+- Access user: Microsoft Graph, Application permission, [User.Read.All](https://docs.microsoft.com/graph/api/user-list?view=graph-rest-1.0&tabs=http#permissions)
+- Access group: Microsoft Graph, Application permission, [Group.Read.All](https://docs.microsoft.com/graph/api/group-list?view=graph-rest-1.0&tabs=http#permissions)
+
+Sample code to assign role of contributor to another service principal.
+```java
+azure.accessManagement().roleAssignments().define(UUID.randomUUID().toString())
+    .forServicePrincipal("<service-principal-name>")
+    .withBuiltInRole(BuiltInRole.CONTRIBUTOR)
+    .withSubscriptionScope("<subscriptionId>")
+    .create();
+```
+
+For dedicated Java SDK for Microsoft Graph API, please use [Microsoft Graph SDK for Java](https://github.com/microsoftgraph/msgraph-sdk-java).
+
+## Types of managed identity and authentication
+
+As we know, there are 2 types of managed identities. Their usage in authentication is slightly different.
+
+Here is sample code when using [Azure Identity library][azure_identity].
+
+For system-assigned managed identity, one can use it without providing client ID:
+```java
+TokenCredential credential = new ManagedIdentityCredentialBuilder().build();
+```
+
+For user-assigned managed identity, one need to provide a client ID of the identity:
+```java
+TokenCredential credential = new ManagedIdentityCredentialBuilder().clientId("<clientId>").build();
+```
+
+If the user-assigned managed identity is managed by this SDK (`azure-resourcemanager-msi`), the client ID can be found via `Identity.clientId()`.
+
+## Chaining managed identity and service principal in authentication
+
+For application that deploys to Azure resource, but still need to debug in local machine, one can use a `ChainedTokenCredential` to concatenate 2 credentials.
+
+In below sample code, `ManagedIdentityCredential` will take effect when deployed to Azure resource.
+When debugging in local machine, as fallback, `EnvironmentCredential` will pick up configure from system environment, and authenticate via a different [service principal][service_principal], likely with access only to development resource.
+```java
+TokenCredential credential = new ChainedTokenCredentialBuilder()
+    .addLast(new ManagedIdentityCredentialBuilder().build())
+    .addLast(new EnvironmentCredentialBuilder().build())
+    .build();
+```
+
+For more details on authentication methods, please refer to [Azure Identity][azure_identity].
+
+[managed_identity]: https://docs.microsoft.com/azure/active-directory/managed-identities-azure-resources/overview
+[rbac]: https://docs.microsoft.com/azure/role-based-access-control/overview
+[microsoft_graph]: https://docs.microsoft.com/graph/overview
+[aad_graph]: https://docs.microsoft.com/azure/active-directory/develop/active-directory-graph-api
+[service_principal]: https://docs.microsoft.com/azure/active-directory/develop/app-objects-and-service-principals
+[azure_identity]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/identity/azure-identity