Add authorization (RBAC) documentation (#550)

README.md

@@ -44,6 +44,7 @@ Follow the [Development Setup Instructions](docs/development/setup.md) to deploy
 
 - [Configure Medical Imaging Server for DICOM server settings](docs/how-to-guides/configure-dicom-server-settings.md)
 - [Enable Authentication and retrieve an OAuth token](docs/how-to-guides/enable-authentication-with-tokens.md)
+- [Enable Authorization](docs/how-to-guides/enable-authorization.md)
 - [Pull Changes from Medical Imaging Server for DICOM with Change Feed](docs/how-to-guides/pull-changes-from-change-feed.md)
 - [Sync DICOM metadata to FHIR](docs/how-to-guides/sync-dicom-metadata-to-fhir.md)
 
@@ -68,6 +69,7 @@ Follow the [Development Setup Instructions](docs/development/setup.md) to deploy
 - [Exception handling](docs/development/exception-handling.md)
 - [Tests](docs/development/tests.md)
 - [Identity Server Authentication](docs/development/identity-server-authentication.md)
+- [Roles](docs/development/roles.md)
 
 ## Contributing
 

docs/development/roles.md

@@ -0,0 +1,36 @@
+# Roles in Microsoft Imaging Server for DICOM
+
+The medical imaging server uses a role-based access control system. The access control model is based on the following concepts:
+
+- **Data Actions** refer to specific allowed or disallowed operations that can be performed on a imaging server's data. Examples include `read`, `write`, and `delete`.
+- **Role definitions** or simply **roles**, are named collections of actions that are allowed be performed. They apply to a set of **scopes**.
+- **Scopes** define the subset of data to which a role definition applies. Currently, only the root scope (`/`) is supported, which means that role definitions apply to all the data in the imaging server.
+- **Role assignments** grants a role definition to an identity (user, group, or service principal).
+
+The set of data actions that can be part of a role definition are:
+
+- `*` allows all data actions
+- `read` is required for reading and searching resources.
+- `write`is required for creating or updating resources.
+- `delete` is required for deleting resources.
+
+Roles are defined in the [roles.json](../../src/Microsoft.Health.Dicom.Web/roles.json) file. Administrators can customize them if desired. A role definition looks like this:
+
+``` json
+{
+    "name": "globalWriter",
+    "dataActions": [
+        "*"
+    ],
+    "notDataActions": [
+        "delete"
+    ],
+    "scopes": [
+        "/"
+    ]
+}
+```
+
+This role allows all data actions except `delete`. Note that if a user is part of this role and another role that allows `delete`, they will be allowed to perform the action.
+
+Role assignments are done in the identity provider. In Azure Active Directory, you define app roles on the imaging server's app registration. The app role names must correspond to the names of the roles defined in `roles.json`. Then you assign identities (users, groups, or service principals) to the app roles.

docs/how-to-guides/enable-authorization.md

@@ -0,0 +1,60 @@
+# Azure Active Directory Authorization
+
+This How-to Guide shows you how to configure the authorization settings for the Medical Imaging Server for DICOM through Azure. To complete this configuration, you will:
+
+1. **Update a resource application in Azure AD**: This resource application will be a representation of the Medical Imaging Server for DICOM that can be used to authorization and obtain tokens. The application registration will need to be updated to create appRoles. 
+1. **Assign the application roles in Azure AD**: Client application registrations, users, and groups need to be assigned the roles defined on the application registration.
+1. **Provide configuration to your Medical Imaging Server for DICOM**: Once the resource application is updated, you will set the authorization settings of your Medical Imaging Server for DICOM App Service.
+
+## Prerequisites
+
+1. **Complete the authentication configuration**: Instructions for enabling authentication can be found in the [Azure Active Directory Authentication](enable-authentication-with-tokens.md) article.
+
+## Authorization Settings Overview
+
+The current authorization settings exposed in configuration are the following:
+
+```json
+
+{
+  "DicomServer" : {
+    "Security": {
+      "Authorization": {
+        "Enabled": true,
+        "RolesClaim": "role",
+        "Roles": [
+            <DEFINED IN ROLES.JSON>
+        ]
+      }
+    }
+  }
+}
+```
+
+| Element                    | Description |
+| -------------------------- | --- |
+| Authorization:Enabled      | Whether or not the server has any authorization enabled. |
+| Authorization:RolesClaim   | Identifies the jwt claim that contains the assigned roles. This is set automatically by the `DevelopmentIdentityProvider`. |
+| Authorization:Roles        | The defined roles. The roles are defined via the `roles.json`. [Additional information can be found here](../development/roles.md) |
+
+## Authorization setup with Azure AD
+
+### Azure AD Instructions
+
+#### Creating App Roles
+The instructions for adding app roles to an AAD application can be found [in this documentation article](https://docs.microsoft.com/azure/active-directory/develop/howto-add-app-roles-in-azure-ad-apps). This documentation also optionally shows you how to assign an app role to an application.
+
+The app roles created need to match the name of the roles found in the `roles.json`. 
+
+#### Assigning Users to App Role
+This can be accomplished [via the Azure Portal](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-assign-users) or [via a PowerShell cmdlet](https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/assign-user-or-group-access-portal#assign-users-and-groups-to-an-app-using-powershell).
+
+### Provide configuration to your Medical Imaging Server for DICOM
+1. Make sure that you have deployed the `roles.json` to your web application
+1. Update the configuration to have the following two settings
+    * `DicomServer:Security:Authorization:Enabled` = `true`
+    * `DicomServer:Security:Authorization:RolesClaim` = `"role"`
+
+## Summary
+
+In this How-to Guide, you learned how to configure the authorization settings for the Medical Imaging Server for DICOM through Azure.