Merge pull request #106796 from CaitlinV39/personal/cavoeg/aadupdates

updated with aad updates and fixed a few small bugs

Author: megvanhuygen

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

@@ -38,7 +38,7 @@ Using Postman, do a `GET` request to `https://fhir-server-url/metadata`:
 
 ![Postman Metadata Capability Statement](media/tutorial-postman/postman-metadata.png)
 
-The metadata URL for Azure API for FHIR is `https://MYACCOUNT.azurehealthcareapis.com`. That endpoint should be accessible without authentication.
+The metadata URL for Azure API for FHIR is `https://MYACCOUNT.azurehealthcareapis.com/metadata`. In this example, the FHIR server URL is `https://fhirdocsmsft.azurewebsites.net` and the capability statement of the server is available at `https://fhirdocsmsft.azurewebsites.net/metadata`. That endpoint should be accessible without authentication.
 
 If you attempt to access restricted resources, you should get an "Authentication failed" response:
 
@@ -65,6 +65,7 @@ You will need to some details:
 | Access Token URL      | `https://login.microsoftonline.com/{TENANT ID}/oauth2/token`                                                      |                            |
 | Client ID             | `XXXXXXXX-XXX-XXXX-XXXX-XXXXXXXXXXXX`                                                                            | Application ID             |
 | Client Secret         | `XXXXXXXX`                                                                                                        | Secret client key          |
+| Scope | `<Leave Blank>` |
 | State                 | `1234`                                                                                                            |                            |
 | Client Authentication | Send client credentials in body                                                                                 |                 
 

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

@@ -113,7 +113,7 @@ Consult details on how to [define roles on the FHIR server](https://github.com/m
 A FHIR server may also validate that an access token has the scopes (in token claim `scp`) to access the part of the FHIR API that a client is trying to access. Currently, the Azure API for FHIR and the FHIR server for Azure do not validate token scopes.
 
 ## Next steps
-Now that you know how to walk through token validation, you can complete the tutorial to create a javascript application and read FHIR data.
+Now that you know how to walk through token validation, you can complete the tutorial to create a JavaScript application and read FHIR data.
 
 >[!div class="nextstepaction"]
 >[Web application tutorial](tutorial-web-app-fhir-server.md)

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

@@ -49,4 +49,4 @@ In this how-to guide, you set up additional settings for the Azure API for FHIR.
 Next check out the series of tutorials to create a web application that reads FHIR data.
 
 >[!div class="nextstepaction"]
->[Deploy javascript application](tutorial-web-app-fhir-server.md)
+>[Deploy JavaScript application](tutorial-web-app-fhir-server.md)

articles/healthcare-apis/fhir-app-registration.md

@@ -1,5 +1,5 @@
 ---
-title: Register the applications for Azure API for FHIR
+title: Register the Azure Active Directory apps for Azure API for FHIR
 description: This tutorial explains which applications need to be registered for Azure API for FHIR and FHIR Server for Azure.
 services: healthcare-apis
 ms.service: healthcare-apis
@@ -34,13 +34,14 @@ In order for an application to interact with Azure AD, it needs to be registered
 
 In this overview, you've gone through the types of application registrations you may need in order to work with a FHIR API.
 
-Based on the decisions you made above, please see the how-to-guides to register your applications
+Based on your setup, please see the how-to-guides to register your applications
 
 * [Register a resource application](register-resource-azure-ad-client-app.md)
 * [Register a confidential client application](register-confidential-azure-ad-client-app.md)
 * [Register a public client application](register-public-azure-ad-client-app.md)
+* [Register a service application](register-service-azure-ad-client-app.md)
 
-Once this is complete, you can deploy the Azure API for FHIR.
+Once you have registered your applications, you can deploy the Azure API for FHIR.
 
 >[!div class="nextstepaction"]
 >[Deploy Azure API for FHIR](fhir-paas-powershell-quickstart.md)

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

@@ -47,7 +47,7 @@ Confirm creation and await FHIR API deployment.
 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:
 
 - **Authority:** You can specify different Azure AD tenant from the one that you are logged into as authentication authority for the service.
-- **Audience:** You can specify audience, that is different from https:\//azurehealthcareapis.com.
+- **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.

articles/healthcare-apis/get-healthcare-apis-access-token-cli.md

@@ -26,10 +26,10 @@ az login
 
 ## Obtain a token
 
-The Azure API for FHIR uses a `resource`  or `Audience` with URI `https://azurehealthcareapis.com`. You can obtain a token and store it in a variable (named `$token`) with the following command:
+The Azure API for FHIR uses a `resource`  or `Audience` with URI equal to the URI of the FHIR server `https://<FHIR ACCOUNT NAME>.azurehealthcareapis.com`. You can obtain a token and store it in a variable (named `$token`) with the following command:
 
 ```azurecli-interactive
-token=$(az account get-access-token --resource=https://azurehealthcareapis.com | jq -r .accessToken)
+token=$(az account get-access-token --resource=https://<FHIR ACCOUNT NAME>.azurehealthcareapis.com | jq -r .accessToken)
 ```
 
 ## Use with Azure API for FHIR

articles/healthcare-apis/register-confidential-azure-ad-client-app.md

@@ -1,6 +1,6 @@
 ---
 title: Register a confidential client app in Azure AD - Azure API for FHIR
-description: Register a confidential client application in Azure Active Directory that authenticates on a user’s behalf and requests access to resource applications.
+description: Register a confidential client application in Azure Active Directory that authenticates on a user's behalf and requests access to resource applications.
 services: healthcare-apis
 author: hansenms
 ms.service: healthcare-apis
@@ -48,9 +48,7 @@ Next add API permissions:
 
 3. Select appropriate resource API:
 
-    For the Azure API for FHIR (managed service), click **APIs my organization uses** and search for "Azure Healthcare APIs".
-    
-    For the Open Source FHIR server for Azure, select your [FHIR API Resource Application Registration](register-resource-azure-ad-client-app.md):
+    For the Azure API for FHIR (managed service), click **APIs my organization uses** and search for "Azure Healthcare APIs". For the Open Source FHIR server for Azure, select your [FHIR API Resource Application Registration](register-resource-azure-ad-client-app.md):
 
     ![Confidential client. My APIs](media/how-to-aad/portal-aad-register-new-app-registration-CONF-CLIENT-API-MyApis.png)
 

articles/healthcare-apis/register-resource-azure-ad-client-app.md

@@ -14,6 +14,8 @@ ms.author: mihansen
 
 In this article, you'll learn how to register a resource (or API) application in Azure Active Directory. A resource application is an Azure Active Directory representation of the FHIR server API itself and client applications can request access to the resource when authenticating. The resource application is also known as the *audience* in OAuth parlance.
 
+## Azure API for FHIR
+
 If you are using the Azure API for FHIR, a resource application is automatically created when you deploy the service. As long as you are using the Azure API for FHIR in the same Azure Active Directory tenant as you are deploying your application, you can skip this how-to-guide and instead deploy your Azure API for FHIR to get started.
 
 If you are using a different Azure Active Directory tenant (not associated with your subscription), you can import the Azure API for FHIR resource application into your tenant with 
@@ -29,7 +31,11 @@ or you can use Azure CLI:
 az ad sp create --id 4f6778d8-5aef-43dc-a1ff-b073724b9495
 ```
 
-## App registrations in Azure portal
+## FHIR Server for Azure
+
+If you are using the open source FHIR Server for Azure, follow the steps below to register a resource application.
+
+### App registrations in Azure portal
 
 1. In the [Azure portal](https://portal.azure.com), on the left navigation panel, click **Azure Active Directory**.
 
@@ -39,13 +45,13 @@ az ad sp create --id 4f6778d8-5aef-43dc-a1ff-b073724b9495
 
 3. Click the **New registration**.
 
-## Add a new application registration
+### Add a new application registration
 
 Fill in the details for the new application. There are no specific requirements for the display name, but setting it to the URI of the FHIR server makes it easy to find:
 
 ![New application registration](media/how-to-aad/portal-aad-register-new-app-registration-NAME.png)
 
-## Set identifier URI and define scopes
+### Set identifier URI and define scopes
 
 A resource application has an identifier URI (Application ID URI), which clients can use when requesting access to the resource. This value will populate the `aud` claim of the access token. It is recommended that you set this URI to be the URI of your FHIR server. For SMART on FHIR apps, it is assumed that the *audience* is the URI of the FHIR server.
 
@@ -59,7 +65,7 @@ A resource application has an identifier URI (Application ID URI), which clients
 
 ![Audience and scope](media/how-to-aad/portal-aad-register-new-app-registration-AUD-SCOPE.png)
 
-## Define application roles
+### Define application roles
 
 The Azure API for FHIR and the OSS FHIR Server for Azure use [Azure Active Directory application roles](https://docs.microsoft.com/azure/architecture/multitenant-identity/app-roles) for role-based access control. To define which roles should be available for your FHIR Server API, open the resource application's [manifest](https://docs.microsoft.com/azure/active-directory/active-directory-application-manifest/):
 

articles/healthcare-apis/register-service-azure-ad-client-app.md

@@ -36,9 +36,7 @@ Follow the steps below to create a new service client.
 
 You will need to grant the service client application roles. 
 
-1. Open the **API permissions** and select your [FHIR API Resource Application Registration](register-resource-azure-ad-client-app.md):
-
-    > If you are using the Azure API for FHIR, you will add a permission to the Azure Healthcare APIs by searching for Azure Healthcare APIs under **APIs my organization uses**.
+1. Open the **API permissions** and select your [FHIR API Resource Application Registration](register-resource-azure-ad-client-app.md). If you are using the Azure API for FHIR, you will add a permission to the Azure Healthcare APIs by searching for Azure Healthcare APIs under **APIs my organization uses**.
 
     ![Azure portal. Service Client API Permissions](media/how-to-aad/portal-aad-register-new-app-registration-SERVICE-CLIENT-API-PERMISSIONS.png)
 

articles/healthcare-apis/tutorial-web-app-fhir-server.md

@@ -11,8 +11,8 @@ author: caitlinv39
 ms.date: 01/03/2020
 ---
 
-# Deploy javascript app to read data from FHIR service
-In this tutorial, you will deploy a small javascript app, which reads data from a FHIR service. The steps in this tutorial are:
+# Deploy JavaScript app to read data from FHIR service
+In this tutorial, you will deploy a small JavaScript app, which reads data from a FHIR service. The steps in this tutorial are:
 1. Deploy a FHIR server
 1. Register a public client application
 1. Test access to the application
@@ -31,7 +31,6 @@ Before starting this set of tutorials, you will need the following items:
 The first step in the tutorial is to get your Azure API for FHIR setup correctly.
 
 1. Deploy the [Azure API for FHIR](fhir-paas-portal-quickstart.md)
-    1. On the Additional Settings tab, set the **Audience** to https://\<FHIR-SERVER-NAME>.azurehealthcareapis.com.
 1. Once you have your Azure API for FHIR deployed, configure the [CORS](configure-cross-origin-resource-sharing.md) settings by going to your Azure API for FHIR and selecting CORS. 
     1. Set **Origins** to *
     1. Set **Headers** to *