Application identities provide a useful method of deploying SharePoint applications. This article describes how to configure an application using the Azure CLI which can be used for deployments across multiple tenants.
At Watford Consulting we build bespoke software solutions to solve our clients’ specific needs.
If we build a solution based on SharePoint it will need to be deployed to the SharePoint Application Catalog in the client’s Microsoft 365 tenant. To do this an Administrator would log into SharePoint, navigate to the application catalog, copy the solution files to the catalog and the trigger a deployment process to make the new version of the application available for regular users.
Our agile approach to software development is to deliver frequent incremental improvements in functionality. To deliver more frequently we need to streamline as much of the manual work involved in the delivery as possible, such as automating the deployment of an application to the SharePoint Application Catalog.
Going further, we want to avoid the use of (service) user accounts to perform deployments. With user accounts, a script is configured with a username and password and performs the deployment steps as that user.
With adoption of Multi-Factor Authentication (MFA) becoming more widespread, the use of an account protected by only password is often prohibited by IT Policy. Instead we want to make use of Application Identities when performing automated software deployments.
Prerequisites
Register the application and add permissions
Log into the home tenant where you want your application to be registered:
az login --tenant <tenant id>
Run the following script to register the application in your tenant:
#!/bin/bash
# Register the deployment application with the current tenent.
# The application ID will be written to file .appId
###################################################################################
set -e
az ad app create --display-name "Deployment Tools" \
--available-to-other-tenants true \
--query appId --output tsv > .appId
echo "Successfully registered application with ID: $(cat .appId)"
Notice that the application is registered with –available-to-other-tenants set as true.
This will allow us to authenticate as the application with credentials stored in our home tenant, but will be able to access resources – e.g. the SharePoint Application Catalog – in other tenants if appropriate permissions are granted.
Run the following script to add the permissions the application will need to deploy to SharePoint:
# Give the deployment tools application permission to access the Graph and SharePoint API.
# The application ID will be read from file .appId
# The API identifier was found here: https://docs.microsoft.com/en-us/troubleshoot/azure/active-directory/verify-first-party-apps-sign-in.
# The individual API Permissions were found by running commands similar to: az ad sp show --id 00000003-0000-0ff1-ce00-000000000000
###################################################################################
set -e
APP_ID=$(cat .appId)
# Check whether an API permission has already been added to the application. If the permission is missing, add it.
# $1 - The API identifier
# $2 - The API permission
function ensureApiPermission() {
local apiId=$1
local apiPermission=$2
local apiPermissionFound=$(az ad app permission list --id $APP_ID --query "[?resourceAppId=='${apiId}'].resourceAccess[].id" --output tsv | grep $apiPermission)
if [ "$apiPermissionFound" != "$apiPermission" ]; then
echo "Adding permission $apiPermission to application $APP_ID"
az ad app permission add --id $APP_ID \
--api $apiId \
--api-permissions "$apiPermission=Role"
fi
}
# Grant SharePoint API Sites.FullControl.All
ensureApiPermission "00000003-0000-0ff1-ce00-000000000000" "678536fe-1083-478a-9c59-b99265e6b0d3"
# Grant Graph API Sites.Read.All
ensureApiPermission "00000003-0000-0000-c000-000000000000" "332a536c-c7ef-4017-ab91-336970924f0d"
The SharePoint Sites.FullControl.All permission will allow the application to modify and publish SharePoint apps to the application catalog.
In the future we’ll explore using the Sites.Selected permission instead to reduce the permissions needed to carry out a deployment.
The Graph API Sites.Read.All permission allows the Microsoft 365 CLI to search the graph for the root SharePoint site’s URL.
Set the authentication certificate
The application can be configured with both secrets and certificates for use during authentication, but access to SharePoint APIs does not work with secrets.
Create a certificate for the application, saved in PEM format. Run the following script, passing the path to the PEM file as the first argument:
# Set a certificate on the deployment tools application.
#
# The application ID will be read from file .appId
#
# Args:
# $1 - Path to certificate PEM file.
###################################################################################
set -e
APP_ID=$(cat .appId)
az ad app credential reset --id $APP_ID --cert "@$1" --append
Create and consent the application's corresponding Service Principal
The application has been registered in its home tenant, configured with the permissions it will need and assigned a certificate for authentication.
The next step is to create a Service Principal in any tenant where the deployment application is intended to be used. Admin consent will need to be granted to the service principal to allow use of the permissions requested in the application registration.
Log in to the tenant where the deployment application will be used:
az login --tenant <tenant id>
Run the following script to create the service principal corresponding to the application:
#!/bin/bash
# Create a service principal for the deployment application.
# The application ID will be read from file .appId
###################################################################################
set -e
APP_ID=$(cat .appId)
SERVICE_PRINCIPAL_OBJECT_ID=$(az ad sp create --id $APP_ID --query objectId --output tsv)
echo "Successfully created service principal with object ID: $SERVICE_PRINCIPAL_OBJECT_ID"
The permissions requested by the application need to be consented to by an administrator. Unfortunately this has cannot be done using the Azure CLI.
To consent to the permissions requested, access the Azure Active Directory blade in the Azure Portal and search for the registered application’s ID. If you have been using the scripts, this can be read from file .appId. You should find the service principal listed as an Enterprise Application.
From the overview of the enterprise application, select Permissions.
On the Permissions screen click the Grant admin consent button, review the displayed information about the requested permissions and then click the Accept button.
The deployment application, registered in your home tenant, can now be used to deploy to the SharePoint Application Catalog in the target tenant.
