Merge pull request #105228 from hansenms/personal/hansenms/resource-app-updates

Remove resource app registration for managed service

Author: v-albemi

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

@@ -24,9 +24,9 @@ A client application would access an FHIR API through a [REST API](https://www.h
 
 In order to use Postman, the following details are needed:
 
-- Your FHIR server URL, for example, `https://MYFHIRSERVICE.azurewebsites.net` or `https://MYACCOUNT.azurehealthcareapis.com`
-- The identity provider `Authority` for your FHIR server, for example, `https://login.microsoftonline.com/{TENANT-ID}`
-- The configured `audience`. For Azure API for FHIR this is `https://azurehealthcareapis.com` and for the open source FHIR server for Azure, it would be set in the [Azure AD resource application registration](register-resource-azure-ad-client-app.md).
+- Your FHIR server URL, for example `https://MYACCOUNT.azurehealthcareapis.com`
+- The identity provider `Authority` for your FHIR server, for example, `https://login.microsoftonline.com/.{TENANT-ID}`
+- The configured `audience`. This is is usually the URL of the FHIR server, e.g. `https://MYACCOUNT.azurehealthcareapis.com` or just `https://azurehealthcareapis.com`.
 - The `client_id` (or application ID) of the [client application](register-confidential-azure-ad-client-app.md) you will be using to access the FHIR service.
 - The `client_secret` (or application secret) of the client application.
 
@@ -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)
 
-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.
+The metadata URL for Azure API for FHIR is `https://MYACCOUNT.azurehealthcareapis.com`. That endpoint should be accessible without authentication.
 
 If you attempt to access restricted resources, you should get an "Authentication failed" response:
 
@@ -61,7 +61,7 @@ You will need to some details:
 | Token Name            | MYTOKEN                                                                                                         | A name you choose          |
 | Grant Type            | Authorization Code                                                                                              |                            |
 | Callback URL          | `https://www.getpostman.com/oauth2/callback`                                                                      |                            |
-| Auth URL              | `https://login.microsoftonline.com/{TENANT-ID}/oauth2/authorize?resource=<audience>` | `audience` is `https://azurehealthcareapis.com` for Azure API for FHIR and `https://MYFHIRSERVICE.azurewebsites.net` for OSS FHIR server |
+| Auth URL              | `https://login.microsoftonline.com/{TENANT-ID}/oauth2/authorize?resource=<audience>` | `audience` is `https://MYACCOUNT.azurehealthcareapis.com` for Azure API for FHIR |
 | 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          |
@@ -82,9 +82,9 @@ In this case, there are no patients in the database and the search is empty.
 
 If you inspect the access token with a tool like [https://jwt.ms](https://jwt.ms), you should see content like:
 
-```json
+```jsonc
 {
-  "aud": "https://azurehealthcareapis.com",
+  "aud": "https://MYACCOUNT.azurehealthcareapis.com",
   "iss": "https://sts.windows.net/{TENANT-ID}/",
   "iat": 1545343803,
   "nbf": 1545343803,

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

@@ -11,12 +11,9 @@ author: matjazl
 ms.date: 10/13/2019
 ---
 
-# Register the applications for Azure API for FHIR
+# Register the Azure Active Directory apps for Azure API for FHIR
 
-You have several configuration options to choose from when you're setting up the environment for Azure API for FHIR, or FHIR Server for Azure. You need to ask yourself the following questions:
-* Are you using or planning to use SMART on FHIR?
-* Are you deploying the managed service version (platform as a service), or the open source software (OSS) version?
-* Are you using the same Azure Active Directory (Azure AD) tenant to secure access to the Azure subscription and FHIR server?
+You have several configuration options to choose from when you're setting up the Azure API for FHIR or the FHIR Server for Azure (OSS). For open source, you'll need to create your own resource application registration. For Azure API for FHIR, this resource application is created automatically.
 
 ## Application registrations
 
@@ -25,27 +22,17 @@ In order for an application to interact with Azure AD, it needs to be registered
 1. Resource application registrations.
 1. Client application registrations.
 
-**Resource applications** are representations in Azure AD of an API or resource that is secured with Azure AD, specifically it would be the Azure API for FHIR. In order to secure the Azure API for FHIR with Azure AD you will need to [register a resource application](register-resource-azure-ad-client-app.md) in Azure AD. This resource application will have an identifier URI. It is recommended that this URI be the same as the URI of the FHIR server. This URI should then be configured as the required `Audience` for the FHIR server. A client application can request access to this FHIR server when it requests a token.
+**Resource applications** are representations in Azure AD of an API or resource that is secured with Azure AD, specifically it would be the Azure API for FHIR. A resource application for Azure API for FHIR will be created automatically when you provision the service, but if you're using the open-source server, you'll need to [register a resource application](register-resource-azure-ad-client-app.md) in Azure AD. This resource application will have an identifier URI. It's recommended that this URI be the same as the URI of the FHIR server. This URI should be used as the `Audience` for the FHIR server. A client application can request access to this FHIR server when it requests a token.
 
-*Client applications* are registrations of the clients that will be requesting tokens. Often in OAuth 2.0, we distinguish between at least 3 different types of applications:
+*Client applications* are registrations of the clients that will be requesting tokens. Often in OAuth 2.0, we distinguish between at least three different types of applications:
 
-1. **Confidential clients**, also known as web apps in Azure AD. These are clients that will use [authorization code flow](https://docs.microsoft.com/azure/active-directory/develop/v1-protocols-oauth-code) to obtain a token on behalf of a signed in user presenting valid credentials. They are called confidential clients because they are able to hold a secret and will present this secret to Azure AD when exchanging the authentication code for a token. Since confidential clients are able to authenticate themselves using the client secret, they are trusted more than public clients and can have longer lived tokens and be granted a refresh token. Read the details on how to [register a confidential client](register-confidential-azure-ad-client-app.md). Note that is important to register the reply url at which the client will be receiving the authorization code.
-1. **Public clients**. These are clients that cannot keep a secret. Typically this would be a mobile device application or a single page javascript application, where a secret in the client could be discovered by a user. Public clients also use authorization code flow, but they are not allowed to present a secret when obtaining a token and they may have shorter lived tokens and no refresh token. Read the details on how to [register a public client](register-public-azure-ad-client-app.md).
+1. **Confidential clients**, also known as web apps in Azure AD. Confidential clients are applications that use [authorization code flow](https://docs.microsoft.com/azure/active-directory/develop/v1-protocols-oauth-code) to obtain a token on behalf of a signed in user presenting valid credentials. They are called confidential clients because they are able to hold a secret and will present this secret to Azure AD when exchanging the authentication code for a token. Since confidential clients are able to authenticate themselves using the client secret, they are trusted more than public clients and can have longer lived tokens and be granted a refresh token. Read the details on how to [register a confidential client](register-confidential-azure-ad-client-app.md). Note that is important to register the reply url at which the client will be receiving the authorization code.
+1. **Public clients**. These are clients that cannot keep a secret. Typically this would be a mobile device application or a single page JavaScript application, where a secret in the client could be discovered by a user. Public clients also use authorization code flow, but they are not allowed to present a secret when obtaining a token and they may have shorter lived tokens and no refresh token. Read the details on how to [register a public client](register-public-azure-ad-client-app.md).
 1. Service clients. These clients obtain tokens on behalf of themselves (not on behalf of a user) using the [client credentials flow](https://docs.microsoft.com/azure/active-directory/develop/v1-oauth2-client-creds-grant-flow). They typically represent applications that access the FHIR server in a non-interactive way. An example would be an ingestion process. When using a service client, it is not necessary to start the process of getting a token with a call to the `/authorize` endpoint. A service client can go straight to the `/token` endpoint and present client ID and client secret to obtain a token. Read the details on how to [register a service client](register-service-azure-ad-client-app.md)
 
-## Decision flow for Azure API for FHIR and FHIR server for Azure 
-
-If you're using Azure API for FHIR (the managed service), use the decision flow shown in the following flowchart:
-
-![Flowchart showing the Azure API for FHIR decision flow](media/tutorial-0/flow-azure-api-for-fhir.png "Azure API for FHIR flow")
-
-If you're deploying FHIR Server for Azure (the OSS version), use this decision flow:
-
-![Flowchart showing the FHIR Server for Azure decision flow](media/tutorial-0/flow-fhir-server-azure.png "FHIR Server for Azure")
-
 ## Next steps
 
-In this overview, you've gone through the decision flow on how to register applications based on the version of the FHIR service you're deploying.
+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
 

articles/healthcare-apis/find-identity-object-ids.md

@@ -24,7 +24,7 @@ When you create a new Azure API for FHIR instance, you can configure a list of a
 
 These object IDs can either be IDs for specific users or service principals in your Azure Active Directory.
 
-## Find user object ID using PowerShell
+## Find user object ID
 
 If you have a user with user name `[email protected]`, you can locate the users `ObjectId` using the following PowerShell command:
 
@@ -38,7 +38,7 @@ or you can use the Azure CLI:
 az ad user show --upn-or-object-id [email protected] | jq -r .objectId
 ```
 
-## Find service principal object ID using PowerShell
+## Find service principal object ID
 
 Suppose you have registered a [service client app](register-service-azure-ad-client-app.md) and you would like to allow this service client to access the Azure API for FHIR, you can find the object ID for the client service principal with the following PowerShell command:
 

articles/healthcare-apis/media/tutorial-0/flow-azure-api-for-fhir.png

@@ -48,7 +48,9 @@ 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/media/tutorial-0/flow-fhir-server-azure.png

@@ -14,7 +14,7 @@ ms.author: mihansen
 
 In this article, you'll learn how to register a public application in Azure Active Directory.  
 
-Client application registrations are Azure Active Directory representations of applications that can authenticate and ask for API permissions on behalf of a user. Public clients are applications such as mobile applications and single page javascript applications that can't keep secrets confidential. The procedure is similar to [registering a confidential client](register-confidential-azure-ad-client-app.md), but since public clients can't be trusted to hold an application secret, there's no need to add one.
+Client application registrations are Azure Active Directory representations of applications that can authenticate and ask for API permissions on behalf of a user. Public clients are applications such as mobile applications and single page JavaScript applications that can't keep secrets confidential. The procedure is similar to [registering a confidential client](register-confidential-azure-ad-client-app.md), but since public clients can't be trusted to hold an application secret, there's no need to add one.
 
 ## App registrations in Azure portal
 
@@ -38,7 +38,11 @@ Client application registrations are Azure Active Directory representations of a
 
 Similarly to the [confidential client application](register-confidential-azure-ad-client-app.md), you'll need to select which API permissions this application should be able to request on behalf of users:
 
-1. Open the **API permissions**. 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** (image below). If you are referencing a different Resource Application, select your [FHIR API Resource Application Registration](register-resource-azure-ad-client-app.md) that you created previously under **My APIs**:
+1. Open the **API permissions**.
+
+    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** (image below).
+    
+    If you are referencing a different Resource Application, select your [FHIR API Resource Application Registration](register-resource-azure-ad-client-app.md) that you created previously under **My APIs**:
 
     ![Azure portal. New public API permissions - Azure API for FHIR Default](media/public-client-app/api-permissions.png)
 

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

@@ -16,6 +16,19 @@ In this article, you'll learn how to register a resource (or API) application in
 
 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 
+PowerShell:
+
+```azurepowershell-interactive
+New-AzADServicePrincipal -ApplicationId 4f6778d8-5aef-43dc-a1ff-b073724b9495
+```
+
+or you can use Azure CLI:
+
+```azurecli-interactive
+az ad sp create --id 4f6778d8-5aef-43dc-a1ff-b073724b9495
+```
+
 ## App registrations in Azure portal
 
 1. In the [Azure portal](https://portal.azure.com), on the left navigation panel, click **Azure Active Directory**.

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

@@ -38,6 +38,8 @@ 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**.
+
     ![Azure portal. Service Client API Permissions](media/how-to-aad/portal-aad-register-new-app-registration-SERVICE-CLIENT-API-PERMISSIONS.png)
 
 2. Select the application roles you from the ones that are defined on the resource application:

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

@@ -26,15 +26,13 @@ This tutorial describes how to use the proxy to enable SMART on FHIR application
 
 ## Configure Azure AD registrations
 
-SMART on FHIR requires that `Audience` has an identifier URI equal to the URI of the FHIR service. The standard configuration of the Azure API for FHIR uses an `Audience` value of `https://azurehealthcareapis.com`. 
+SMART on FHIR requires that `Audience` has an identifier URI equal to the URI of the FHIR service. The standard configuration of the Azure API for FHIR uses an `Audience` value of `https://azurehealthcareapis.com`. However, you can also set a value matching the specific URL of your FHIR service (for example `https://MYFHIRAPI.azurehealthcareapis.com`). This is required when working with the SMART on FHIR proxy.
 
-Suppose that the URI for your Azure API for FHIR is `https://MYFHIRAPI.azurehealthcareapis.com`. You need to configure a [resource application registration](register-resource-azure-ad-client-app.md) with that identifier URI.
-
-After you set up a resource application, you also need a client application registration. Most SMART on FHIR applications are single-page JavaScript applications. So you should follow the instructions for configuring a [public Azure AD client application](register-public-azure-ad-client-app.md).
+You will also need a client application registration. Most SMART on FHIR applications are single-page JavaScript applications. So you should follow the instructions for configuring a [public Azure AD client application](register-public-azure-ad-client-app.md).
 
 After you complete these steps, you should have:
 
-- A resource application with the identifier URI `https://MYFHIRAPI.azurehealthcareapis.com`, where `MYFHIRAPI` is the name of your Azure API for FHIR instance.
+- A FHIR server with rge audience set to `https://MYFHIRAPI.azurehealthcareapis.com`, where `MYFHIRAPI` is the name of your Azure API for FHIR instance.
 - A public client application registration. Make a note of the application ID for this client application.
 
 ## Enable the SMART on FHIR proxy