Microsoft Assent (a.k.a Approvals) as a platform provides the "one stop shop" solution for approvers via a model that brings together disparate different approval requests in a consistent and ultra-modern model. Approvals delivers a unified approvals experience for any approval on multiple form factors - Website, Outlook Actionable email, Teams. It consolidates approvals across organization's line of business applications, building on modern technology and powered by Microsoft Azure. It serves as a showcase for solving modern IT scenarios using the latest technologies.

• Payload Receiver Service API - Accepts payload from tenant system.
• Audit Processor - Azure Function that logs the payload data into Azure Cosmos DB.
• Primary Processor - Azure Function that processes the payload pushed by payload receiver service API to service bus.
• Notification Processor - Azure Function that sends email notifications to Approvers/ Submitters as per configurations.
• WatchdogProcessor - as per configurations from tenant sends reminder email notifications to Approvers for pending approvals as per configurations from tenant.
• Core Services API - Set of Web APIs to support the Approvals UI.

These instructions will get the project up and running in Azure.

Before running the project on local machine/ or deploy the following things needs to be setup on Azure:

• Azure Subscription
• Microsoft Entra ID App (along with secret)

Apart from these keep the following items handy as it would be required during deployment:

• Microsoft Entra ID App's ClientId for Authentication in case of API
• Microsoft Entra ID App's Secret for Authentication in case of API
• Assign a default user_impersonation scope for the Microsoft Entra ID app (with Admin Consent only)
• Microsoft Entra ID App's resource/AAP ID URI used for generating token (audience)
• TenantId for Authentication in case of API
• Issuer Url for Authentication : https://sts.windows.net/{IdentityProviderTenantId}
• Custom Application Name which would be used to create AppServices/Functions (resource_name_prefix)
• Custom Resource Group Name where all the resources will be deployed
• Location/code to deploy the Azure Resources (e.g. Central US/centralus. Powershell Command: Get-AzureRmLocation |Format-Table)

A step by step series of that explains how to get the components deployed in Azure

Step 1: Download the ARM template (template.json) from the source (scripts)

Step 2: Go to Azure Portal and search/select the service 'Deploy a custom template"

Step 3: Select 'Build your own template in the editor' and paste the content of 'template.json' in the editor

Step 4: Save and go the next step. Select the subscription, resource group & location.
Update the settings to update any of the parameter values if required and click on purchase

Note : If there is any failure, try re-deploying again before proceeding for any troubleshooting.

It might have happened that some of the resources which got created may be already present in your subscription. In that case, you can continue to use the same and delete the newly created resources. (e.g. Storage Account, Application Insights, ServiceBus - In case of ServiceBus make sure to create the Topics in your exisiting ServiceBus namespace before deleting).

The following table will help in deciding which components can be cleaned-up.

Once all the components are deployed, go to the below components, copy the access keys and store that in Azure App Configuration. The secrets needs to be stored in Azure Key vault and a respective Key Vault reference of the same can be added in Azure App Configuration as required.

Step 1: Download the configuration file (AppCofiguration.json) from the samples folder

Step 2: Add/update the values for the following keys in the JSON

Step 3: Go to the App Configuration service on Azure Portal and select the resource
where the configuration needs to be imported.

Step 4: Go to 'Operations' -> 'Import/Export'

Step 5: Select 'Import' in the toggle button and
choose 'Configuration file' from the dropdown 'Source service'.

Step 6: In the 'For language' drop down select 'Other'

Step 7: Choose 'Json' as the value from the 'File type' dropdown and
select the 'AppConfiguration.json' updated in the previous step file from the File Explorer.

Step 8: The configuration should be fetched successfully and the UI should show options to save/apply
Select the 'Label' under which the configurations needs to be added (e.g., DEV) and click 'Apply'

• For all the components created above please add their respective system assigned managed identity in the 'Access policies' section of the KeyVault.
• Please select the 'Configure from template' option to be Secret Management and assign just the Get and List permission
• For the Function Apps add/update the below AppSetting keys:

  APPINSIGHTS_INSTRUMENTATIONKEY

  This is an instrumentation key of Application Insights which was created from ARM Template.

  AzureAppConfigurationUrl

  This would be Azure App Configuration's endpoint URL.

  AppConfigurationLabel

  This would be Azure App Configuration's label value corresponding to the environment the App service is running for.

  AzureWebJobsStorage

  This would be Key vault Reference to storage account's connection string.

  AzureWebJobsDashboard

  This would be Key vault Reference to storage account's connection string.

  ComponentName

  Name of the component which could be name of the component like ApprovalsPrimaryProcessor or ApprovalsNotificationProcessor.

  FUNCTIONS_EXTENSION_VERSION : ~3

  SubscriptionName

  The Service Bus Topic's subscription name which is to be listened by the function app for new messages.

• Apart from above seeting, below AppSetting keys should also be added to Watchdog function:

  Schedule

  A CRON expression or a TimeSpan value (0 */5 * * * *).

• For the Azure App Services add/update the below AppSetting keys:

  APPINSIGHTS_INSTRUMENTATIONKEY

  This is an instrumentation key of Application Insights which was created from ARM Template.

  AzureAppConfigurationUrl

  This would be Azure App Configuration's endpoint URL.

  AppConfigurationLabel

  This would be Azure App Configuration's label value corresponding to the environment the App service is running for.

  ComponentName

  Name of the component which could be name of the component like ApprovalsCoreServicesAPI or ApprovalsPayloadServiceAPI.

  ValidAppIds This is Microsoft Entra ID App's ClientIds which are authorized to access this component (; separated).

   Note: The connection string should be the KeyVault url
   i.e. Enter the value in this format: @Microsoft.KeyVault(SecretUri=<keyvault Secret Identifier url for AzureAppConfigurationConnectionString>)
  

• Setup Authentication for APIs and Function Apps

  • Update the Reply Urls section of the Microsoft Entra ID App created earlier with the URLs of the App Services and FunctionApps (HttpTriggered) URLs suffixed with '/auth/login/aad/callback'
  • In the 'Authentication' section of the AppServices / FunctionApps (HttpTriggered),
    • Add or update the Authentication values (ClientId/Secret/Issuer/Audience)
    • Select 'Return HTTP 302 Found (Redirect to identity provider)' for the option 'Unauthenticated requests'

• Permissions needed needed for System assigned Managed Identity of below Azure Components

  • Payload Receiver Service API:

    • App Configuration Data Reader
    • Azure Service Bus Data Sender
    • Cosmos DB Built-in Data Contributor
    • Key Vault Secrets User
    • Storage Blob Data Contributor
    • Storage Table Data Contributor

  • Audit Processor:

    • App Configuration Data Reader
    • Azure Service Bus Data Owner
    • Cosmos DB Built-in Data Contributor
    • Key Vault Secrets User
    • Storage Blob Data Contributor
    • Storage Table Data Contributor

  • Primary Processor:

    • App Configuration Data Reader
    • Azure Service Bus Data Owner
    • Cosmos DB Built-in Data Contributor
    • Key Vault Secrets User
    • Storage Blob Data Contributor
    • Storage Table Data Contributor

  • Notification Processor:

    • App Configuration Data Reader
    • Azure Service Bus Data Owner
    • Cosmos DB Built-in Data Contributor
    • Key Vault Secrets User
    • Storage Blob Data Contributor
    • Storage Table Data Contributor

  • Watchdog Processor:

    • App Configuration Data Reader
    • Cosmos DB Built-in Data Contributor
    • Key Vault Secrets User
    • Storage Blob Data Contributor
    • Storage Table Data Contributor

  • Core Services API:

    • App Configuration Data Reader
    • Cosmos DB Built-in Data Contributor
    • Key Vault Secrets User
    • Storage Blob Data Contributor
    • Storage Table Data Contributor

  Note: As of today only way to assign Cosmos DB Built-in Data Contributor is via the PowerShell or az cli below is the command fot the same:

      az cosmosdb sql role assignment create --account-name "Cosmosdb account name" --resource-group "Name of resource group where cosmosdb exists" --scope "/" --principal-id "System assigned identity to to which this Role Assignment is being granted" --role-definition-id "00000000-0000-0000-0000-000000000002"
  

  For more information please read: Configure role-based access control for your Azure Cosmos DB account with Azure AD | Microsoft Learn

Deploy the code in these new components using Azure DevOps (Build and Release pipelines)

The deployment might fail sometimes due to locked files. Try restarting the service, before redeploying. If the issue persists, add the following AppSettings in the service configuration

    "MSDEPLOY_RENAME_LOCKED_FILES": "1"

See the SETUP.md file for details

This project is licensed under the MIT License - see the LICENSE file for details

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.