Updated documentation on app registrations (#155)

* Updated documentation on app registrations

* Response to PR review

docs/BashDeployment.md

@@ -42,6 +42,12 @@ The information required to use the application registration will be returned:
 }
 ```
 
+The Azure CLI based bash scripts provided in this repository lack some functionality for defining application [roles](Roles.md) that are used for access control. 
+
+To define API application roles, locate your application registration in the portal and [add any roles](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps#declare-roles-for-an-application) you would like to define on your FHIR api. [Assign those roles to users](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps#assign-users-and-groups-to-roles) in your Azure Active Directory.
+
+If you would like your client application registration to act as a service account, you can grant the application privileges (roles). Please consult the [documentation on application permissions](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis).
+
 ## Deploying the FHIR Server Template
 
 Use the provided template to deploy the FHIR server:

docs/DefaultDeployment.md

@@ -13,7 +13,7 @@ The FHIR server supports token based (JWT) authorization. If authorization is en
 
 To use the FHIR server with AAD authentication, two Azure Active Directory (AAD) Applications must be registered, one for the FHIR server itself and one for each client accessing the FHIR server. Please refer to the AAD documentation for details on the [Web application to Web API scenario](https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-scenarios#web-application-to-web-api).
 
-Both AAD Applications can be registered using the Azure Portal. Please refer to the [AAD Application registration documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-v1-integrate-apps-with-azure-ad).
+Both AAD Applications can be registered using the Azure Portal. Please refer to the [AAD Application registration documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-v1-integrate-apps-with-azure-ad) and the [portal application registration notes in this repository](PortalAppRegistrations.md).
 
 You can also register the AAD Applications using the [AzureAD PowerShell module](https://docs.microsoft.com/en-us/powershell/module/azuread/). This repository includes a PowerShell module with some wrapper functions that help with the AAD Application registration process.
 

docs/PortalAppRegistration.md

@@ -0,0 +1,30 @@
+# Azure Active Directory Application Registrations
+
+The Microsoft FHIR Server for Azure uses Azure Active Directory (AAD) for OAuth authentication/authorization. In order to deploy the server and applications interacting with the server, you need to create AAD application registrations and manage application roles that are used for role based acces control.
+
+This document explains how to create these application registrations using the Azure Portal.
+
+## Application Registration for FHIR Server API
+
+Please consult the Azure Active Directory Documentation for details on the steps below:
+
+1. [Register an AAD Application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-v1-add-azure-ad-app)
+2. [Add application roles to the application](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps). You should add at least one role, say `admin`.
+
+Make a note of the application id and/or the identifier URI of the of the API application. This will be used as the `audience` when deploying the FHIR server.  
+
+## Grant User API Roles
+
+Now that you have defined API roles in your application registration, you can [assign those roles to specific users](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps#assign-users-and-groups-to-roles).
+
+## Client Application Registration
+
+For each application that will access the FHIR API, create a client application registration:
+
+1. [Register an AAD Application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-v1-add-azure-ad-app)
+2. [Add Redirect URIs](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis#add-redirect-uris-to-your-application) for your application.
+3. [Add a client secret](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis#add-credentials-to-your-web-application).
+4. [Add API Permissions](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-access-web-apis#add-permissions-to-access-web-apis). Here you should search for the name of the API application you created above and add any delegated privileges (scopes) that you would like the application to obtain on behalf of the user. If you would like the client application to act as a service client, pick the roles you would like the application to have in the application permission settings. After saving the settings hit the "Grant permissions" button if you have assigned roles to the application (required admin permissions).
+
+Make a note of the client application id, and the client secret. 
+