Merge pull request #113357 from hansenms/personal/hansenms/azure-rbac2

Bringing Azure RBAC changes back

Author: American-Dipper

.openpublishing.redirection.json

@@ -51475,16 +51475,6 @@
       "redirect_url": "/azure/sql-database/sql-database-security-best-practice",
       "redirect_document_id": false
     },
-    {
-      "source_path": "articles/healthcare-apis/configure-azure-rbac.md",
-      "redirect_url": "/azure/healthcare-apis/azure-api-for-fhir-additional-settings",
-      "redirect_document_id": false
-    },
-    {
-      "source_path": "articles/healthcare-apis/configure-local-rbac.md",
-      "redirect_url": "/azure/healthcare-apis/azure-api-for-fhir-additional-settings",
-      "redirect_document_id": false
-    },
     {
       "source_path": "articles/media-services/previous/media-services-configure-tricaster-live-encoder.md",
       "redirect_url": "/azure/media-services",

articles/healthcare-apis/TOC.yml

@@ -22,7 +22,7 @@
 - name: Tutorials
   expanded: false
   items:
-  - name: Deploy javascript application
+  - name: Deploy JavaScript application
     expanded: false
     items:
     - name: 1. Initial setup and FHIR deployment
@@ -57,7 +57,11 @@
     expanded: false
     items:
     - name: Configure additional Azure API for FHIR settings
-      href: azure-api-for-fhir-additional-settings.md 
+      href: azure-api-for-fhir-additional-settings.md
+    - name: Configure Azure RBAC
+      href: configure-azure-rbac.md
+    - name: Configure Local RBAC
+      href: configure-local-rbac.md
     - name: Configure database settings
       href: configure-database.md
     - name: Configure CORS

articles/healthcare-apis/access-fhir-postman-tutorial.md

@@ -13,7 +13,7 @@ ms.date: 02/07/2019
 
 # Access Azure API for FHIR with Postman
 
-A client application would access an FHIR API through a [REST API](https://www.hl7.org/fhir/http.html). You may also want to interact directly with the FHIR server as you build applications, for example, for debugging purposes. In this tutorial, we will walk through the steps needed to use [Postman](https://www.getpostman.com/) to access an FHIR server. Postman is a tool often used for debugging when building applications that access APIs.
+A client application would access an FHIR API through a [REST API](https://www.hl7.org/fhir/http.html). You may also want to interact directly with the FHIR server as you build applications, for example, for debugging purposes. In this tutorial, we will walk through the steps needed to use [Postman](https://www.getpostman.com/) to access a FHIR server. Postman is a tool often used for debugging when building applications that access APIs.
 
 ## Prerequisites
 
@@ -103,9 +103,9 @@ If you inspect the access token with a tool like [https://jwt.ms](https://jwt.ms
 }
 ```
 
-In troubleshooting situations, validating that you have the correct audience (`aud` claim) is a good place to start. The managed Azure API for FHIR uses [identity object IDs](find-identity-object-ids.md) to restrict access to the service. Make sure that `oid` claim of the token contains an object ID from the list of allowed object IDs.
+In troubleshooting situations, validating that you have the correct audience (`aud` claim) is a good place to start. If your token is from the correct issuer (`iss` claim) and has the correct audience (`aud` claim), but you are still unable to access the FHIR API, it is likely that the user or service principal (`oid` claim) does not have access to the FHIR data plane. We recommend you [use Azure Role Based Access Control](configure-azure-rbac.md) to assign data plane roles to users. If you are using an external, secondary Azure Active directory tenant for your data plane, you will need to [configure local RBAC assignments](configure-local-rbac.md).
 
-It is also possible to [get a token for the Azure API for FHIR using the Azure CLI](get-healthcare-apis-access-token-cli.md).
+It is also possible to [get a token for the Azure API for FHIR using the Azure CLI](get-healthcare-apis-access-token-cli.md). If you are using a token obtained with the Azure CLI, you should use Authorization type "Bearer Token" and paste the token in directly.
 
 ## Inserting a patient
 

articles/healthcare-apis/azure-ad-hcapi-token-validation.md

@@ -99,9 +99,9 @@ Once the server has verified the authenticity of the token, the FHIR server will
 When using the Azure API for FHIR, the server will validate:
 
 1. The token has the right `Audience` (`aud` claim).
-1. The `oid` claim contains an identity object ID, which is in the list of allowed object IDs.
+1. The user or principal that the token was issued for is allowed to access the FHIR server data plane. The `oid` claim of the token contains an identity object ID, which uniquely identifies the user or principal.
 
-See details on [finding identity object IDs](find-identity-object-ids.md). 
+We recommend that the FHIR service be [configured to use Azure RBAC](configure-azure-rbac.md) to manage data plane role assignments. But you can also [configure local RBAC](configure-local-rbac.md) if your FHIR service uses an external or secondary Azure Active Directory tenant. 
 
 When using the OSS Microsoft FHIR server for Azure, the server will validate:
 

articles/healthcare-apis/azure-api-for-fhir-additional-settings.md

@@ -22,10 +22,12 @@ Throughput must be provisioned to ensure that sufficient system resources are av
 
 For more information on how to change the default settings, see [configure database settings](configure-database.md).
 
-## Find identity object IDs
-The fully managed Azure API for FHIR service is configured to allow access for only a pre-defined list of identity object IDs. When an application or user is trying to access the FHIR API, a bearer token must be presented. This bearer token will have certain claims (fields). In order to grant access to the FHIR API, the token must contain the right issuer (`iss`), audience (`aud`), and an object ID (`oid`) from a list of allowed object IDs. An identity object ID is either the object ID of a user or a service principal in Azure Active Directory.
+## Access control
 
-When you create a new Azure API for FHIR instance, you can configure a list of allowed object IDs. To configure this list, see our how-to-guide to [find identity object IDs](find-identity-object-ids.md).
+The Azure API for FHIR will only allow authorized users to access the FHIR API. You can configure authorized users through two different mechanisms. The primary and recommended way to configure access control is using [Azure Role Based Access Control (RBAC)](https://docs.microsoft.com/azure/role-based-access-control/), which is accessible through the **Access control (IAM)** blade. Azure RBAC only works if you want to secure data plane access using the Azure Active Directory tenant associated with your subscription. If you wish to use a different tenant, the Azure API for FHIR offers a local FHIR data plane access control mechanism. The configuration options are not as rich when using the local RBAC mechanism. For details, choose one of the following options:
+
+* [Azure RBAC for FHIR data plane](configure-azure-rbac.md). This is the preferred option when you are using the Azure Active Directory tenant associated with your subscription.
+* [Local FHIR data plane access control](configure-local-rbac.md). Use this option only when you need to use an external Azure Active Directory tenant for data plane access control. 
 
 ## Enable diagnostic logging
 You may want to enable diagnostic logging as part of your setup to be able to monitor your service and have accurate reporting for compliance purposes. For details on how to set up diagnostic logging, see our [how-to-guide](enable-diagnostic-logging.md) on how to set up diagnostic logging, along with some sample queries. 

articles/healthcare-apis/configure-azure-rbac.md

@@ -0,0 +1,54 @@
+---
+title: Configure Azure Role Based Access Control (RBAC) for Azure API for FHIR
+description: This article describes how to configure Azure RBAC for the Azure API for FHIR data plane
+author: hansenms
+ms.service: healthcare-apis
+ms.subservice: fhir
+ms.topic: reference 
+ms.date: 03/15/2020
+ms.author: mihansen
+---
+# Configure Azure RBAC for FHIR 
+
+In this article, you will learn how to use [Azure Role Based Access Control (RBAC)](https://docs.microsoft.com/azure/role-based-access-control/) to assign access to the Azure API for FHIR data plane. Azure RBAC is the preferred methods for assigning data plane access when data plane users are managed in the Azure Active Directory tenant associated with your Azure subscription. If you are using an external Azure Active Directory tenant, refer to the [local RBAC assignment reference](configure-local-rbac.md).
+
+## Confirm Azure RBAC mode
+
+To use Azure RBAC, your Azure API for FHIR must be configured to use your Azure subscription tenant for data plane and there should be no assigned identity object IDs. You can verify your settings by inspecting the **Authentication** blade of your Azure API for FHIR:
+
+:::image type="content" source="media/rbac/confirm-azure-rbac-mode.png" alt-text="Confirm Azure RBAC mode":::
+
+The **Authority** should be set to the Azure Active directory tenant associated with your subscription and there should be no GUIDs in the box labeled **Allowed object IDs**. You will also notice that the box is disabled and a label indicates that Azure RBAC should be used to assign data plane roles.
+
+## Assign roles
+
+To grant users, service principals or groups access to the FHIR data plane, click **Access control (IAM)**, then click **Role assignments** and click **+ Add**:
+
+:::image type="content" source="media/rbac/add-azure-rbac-role-assignment.png" alt-text="Add Azure RBAC role assignment":::
+
+In the **Role** selection, search for one of the built-in roles for the FHIR data plane:
+
+:::image type="content" source="media/rbac/built-in-fhir-data-roles.png" alt-text="Built-in FHIR data roles":::
+
+You can choose between:
+
+* FHIR Data Reader: Can read (and search) FHIR data.
+* FHIR Data Writer: Can read, write, and soft delete FHIR data.
+* FHIR Data Exporter: Can read and export (`$export` operator) data.
+* FHIR Data Contributor: Can perform all data plane operations.
+
+If these roles are not sufficient for your need, you can also [create custom roles](https://docs.microsoft.com/azure/role-based-access-control/tutorial-custom-role-powershell).
+
+In the **Select** box, search for a user, service principal, or group that you wish to assign the role to.
+
+## Caching behavior
+
+The Azure API for FHIR will cache decisions for up to 5 minutes. If you grant a user access to the FHIR server by adding them to the list of allowed object IDs, or you remove them from the list, you should expect it to take up to five minutes for changes in permissions to propagate.
+
+## Next steps
+
+In this article, you learned how to assign Azure RBAC roles for the FHIR data plane. Next learn about additional settings for the Azure API for FHIR:
+ 
+>[!div class="nextstepaction"]
+>[Additional settings Azure API for FHIR](azure-api-for-fhir-additional-settings.md)
+

articles/healthcare-apis/configure-local-rbac.md

@@ -0,0 +1,66 @@
+---
+title: Configure local Role Based Access Control (RBAC) for Azure API for FHIR
+description: This article describes how to configure the Azure API for FHIR to use an external Azure AD tenant for data plane
+author: hansenms
+ms.service: healthcare-apis
+ms.subservice: fhir
+ms.topic: reference 
+ms.date: 03/15/2020
+ms.author: mihansen
+---
+# Configure local RBAC for FHIR 
+
+This article explains how to configure the Azure API for FHIR to use an external, secondary Azure Active Directory tenant for managing data plane access. Use this mode only if it is not possible for you to use the Azure Active Directory tenant associated with your subscription.
+
+> [!NOTE]
+> If your FHIR service data plane is configured to use your primary Azure Active Directory tenant associated with your subscription, [use Azure RBAC to assign data plane roles](configure-azure-rbac.md).
+
+## Add service principal
+
+Local RBAC allows you to use an external Azure Active Directory tenant with your FHIR server. In order to allow the RBAC system to check group memberships in this tenant, the Azure API for FHIR must have a service principal in the tenant. This service principal will get created automatically in tenants tied to subscriptions that have deployed the Azure API for FHIR, but in case your tenant has no subscription tied to it, a tenant administrator will need to create this service principal with one of the following commands:
+
+Using the `Az` PowerShell module:
+
+```azurepowershell-interactive
+New-AzADServicePrincipal -ApplicationId 3274406e-4e0a-4852-ba4f-d7226630abb7
+```
+
+or you can use the `AzureAd` PowerShell module:
+
+```azurepowershell-interactive
+New-AzureADServicePrincipal -AppId 3274406e-4e0a-4852-ba4f-d7226630abb7
+```
+
+or you can use Azure CLI:
+
+```azurecli-interactive
+az ad sp create --id 3274406e-4e0a-4852-ba4f-d7226630abb7
+```
+
+## Configure local RBAC
+
+You can configure the Azure API for FHIR to use an external or secondary Azure Active Directory tenant in the **Authentication** blade:
+
+![Local RBAC Assignments](media/rbac/local-rbac-guids.png).
+
+In the authority box, enter a valid Azure Active Directory tenant. Once the tenant has been validated, the **Allowed object IDs** box should be activated and you can enter a list of identity object IDs. These IDs can be the identity object IDs of:
+
+* An Azure Active Directory user.
+* An Azure Active Directory service principal.
+* An Azure Active directory security group.
+
+You can read the article on how to [find identity object IDs](find-identity-object-ids.md) for more details.
+
+After entering the required object IDs, click **Save** and wait for changes to be saved before trying to access the data plane using the assigned users, service principals, or groups.
+
+## Caching behavior
+
+The Azure API for FHIR will cache decisions for up to 5 minutes. If you grant a user access to the FHIR server by adding them to the list of allowed object IDs, or you remove them from the list, you should expect it to take up to five minutes for changes in permissions to propagate.
+
+## Next steps
+
+In this article, you learned how to assign FHIR data plane access using an external (secondary) Azure Active Directory tenant. Next learn about additional settings for the Azure API for FHIR:
+ 
+>[!div class="nextstepaction"]
+>[Additional settings Azure API for FHIR](azure-api-for-fhir-additional-settings.md)
+

articles/healthcare-apis/fhir-oss-cli-quickstart.md

@@ -39,7 +39,7 @@ az group deployment create -g $servicename --template-uri https://raw.githubuser
 
 Obtain a capability statement from the FHIR server with:
 
-```console
+```azurecli-interactive
 metadataurl="https://${servicename}.azurewebsites.net/metadata"
 curl --url $metadataurl
 ```

articles/healthcare-apis/fhir-paas-cli-quickstart.md

@@ -30,15 +30,6 @@ Get a list of commands for HealthcareAPIs:
 az healthcareapis --help
 ```
 
-## Locate your identity object ID
-
-Object ID values are guids that correspond to the object IDs of specific Azure Active Directory users or service principals in the directory associated with the subscription. If you would like to know the object ID of a specific user, you can find it with a command like:
-
-```azurecli-interactive
-az ad user show --id [email protected] | jq -r .objectId
-```
-Read the how-to guide on [finding identity object IDs](find-identity-object-ids.md) for more details.
-
 ## Create Azure Resource Group
 
 Pick a name for the resource group that will contain the Azure API for FHIR and create it:
@@ -50,16 +41,14 @@ az group create --name "myResourceGroup" --location westus2
 ## Deploy the Azure API for FHIR
 
 ```azurecli-interactive
-az healthcareapis create --resource-group myResourceGroup --name nameoffhiraccount --kind fhir-r4 --location westus2 --access-policies-object-id "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+az healthcareapis create --resource-group myResourceGroup --name nameoffhiraccount --kind fhir-r4 --location westus2 
 ```
 
-where `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` is the identity object ID for a user or service principal that you would like to have access to the FHIR API.
-
 ## Fetch FHIR API capability statement
 
 Obtain a capability statement from the FHIR API with:
 
-```console
+```azurecli-interactive
 curl --url "https://nameoffhiraccount.azurehealthcareapis.com/metadata"
 ```
 

articles/healthcare-apis/fhir-paas-portal-quickstart.md

@@ -6,7 +6,7 @@ author: hansenms
 ms.service: healthcare-apis
 ms.subservice: fhir
 ms.topic: quickstart 
-ms.date: 02/07/2019
+ms.date: 03/15/2020
 ms.author: mihansen
 ---
 
@@ -26,34 +26,31 @@ Open the [Azure portal](https://portal.azure.com) and click **Create a resource*
 
 You can find Azure API for FHIR by typing "FHIR" into the search box:
 
-![Search for Healthcare APIs](media/quickstart-paas-portal/portal-search-healthcare-apis.png)
+:::image type="content" source="media/quickstart-paas-portal/portal-search-healthcare-apis.png" alt-text="Search for Healthcare APIs":::
 
 ## Create Azure API for FHIR account
 
 Select **Create** to create a new Azure API for FHIR account:
 
-![Create Azure API for FHIR account](media/quickstart-paas-portal/portal-create-healthcare-apis.png)
+:::image type="content" source="media/quickstart-paas-portal/portal-create-healthcare-apis.png" alt-text="Create Azure API for FHIR account":::
 
 ## Enter account details
 
 Select an existing resource group or create a new one, choose a name for the account, and finally click **Review + create**:
 
-![New healthcare api details](media/quickstart-paas-portal/portal-new-healthcareapi-details.png)
+:::image type="content" source="media/quickstart-paas-portal/portal-new-healthcareapi-details.png" alt-text="New healthcare api details":::
 
 Confirm creation and await FHIR API deployment.
 
-## Additional settings
+## Additional settings (optional)
 
-Click **Next: Additional settings** to configure the authority, audience, identity object IDs that should be allowed to access this Azure API for FHIR, enable SMART on FHIR if needed, and configure database throughput:
+You can also click **Next: Additional settings** to view the authentication settings. The default configuration for the Azure API for FHIR is to [use Azure RBAC for assigning data plane roles](configure-azure-rbac.md). When configured in this mode, the "Authority" for the FHIR service will be set to the Azure Active Directory tenant of the subscription:
 
-- **Authority:** You can specify different Azure AD tenant from the one that you are logged into as authentication authority for the service.
-- **Audience:** Best practice, and the default setting, is that the audience is set to the URL of the FHIR server. You can change that here. The audience identifies the recipient that the token is intended for. In this context, it should be set to something representing the FHIR API itself.
-- **Allowed object IDs:** You can specify identity object IDs that should be allowed to access this Azure API for FHIR. You can learn more on finding the object ID for users and service principals in the [Find identity object IDs](find-identity-object-ids.md) how-to guide.  
-- **Smart On FHIR proxy:** You can enable SMART on FHIR proxy. For details on how to configure SMART on FHIR proxy see tutorial [Azure API for FHIR SMART on FHIR proxy](https://docs.microsoft.com/azure/healthcare-apis/use-smart-on-fhir-proxy)  
-- **Provisioned throughput (RU/s):** Here you can specify throughput settings for the underlying database for your Azure API for FHIR. You can change this setting later in the Database blade. For more details, please see the [configure database settings](configure-database.md) page.
+:::image type="content" source="media/rbac/confirm-azure-rbac-mode-create.png" alt-text="Default Authentication settings":::
 
+Notice that the box for entering allowed object IDs is grayed out, since we use Azure RBAC for configuring role assignments in this case.
 
-![Configure allowed object IDs](media/quickstart-paas-portal/configure-audience.png)
+If you wish to configure the FHIR service to use an external or secondary Azure Active Directory tenant, you can change the Authority and enter object IDs for user and groups that should be allowed access to the server. For more information, see the [local RBAC configuration](configure-local-rbac.md) guide.
 
 ## Fetch FHIR API capability statement