Grant Application and Delegate Permissions using an App Registration


This blog post came about because I wanted a way to create new Application Registrations and grant consent for the tenant, all programmatically. This is so I can use Devops pipelines to create and deploy my code without any human interaction or using a person account.

The AZ cli can grants permissions, but it does not seem to work for Admin consented permissions. I found the following post by Sam Coganhttps://samcogan.com/provide-admin-consent-fora-azure-ad-applications-programmatically/ saying that it was possible if you use REST API calls. This did work for me; however, it was just the Delegated permissions.

By reading through Sam’s post it helped me understand the connection between Application Registrations, Service Principals and Oauth2permission, and helped me on the quest of understand how to grant the Application permissions through appRoleAssignments.

I also want to credit Sahil Malik as I found his post https://winsmarts.com/how-to-grant-admin-consent-to-an-api-programmatically-e32f4a100e9d after I worked it all out myself, and was able to confirm that what I was doing was right.

At my Github project https://github.com/pmatthews05/CFAppOnlyGrantPermissions the README.md will walk you through how to set up and run the code. At the end of the README.md file you should have 2 Application Registration, where the Azure API Registration app would have created the second app (in my case CFCodeApp) for you. This code is idempotent. You can change the permissions for an existing Application Registration by providing it a different Permission.json file.

As the README.md file gives the instruction on how to run the code, I will not replicate it here. I will use the rest of this post to explain how the code works.

Permissions required for ‘Azure API Registration’

To allow the Azure API Registration to create new Application Registrations using AZ cli it requires to use both the legacy Azure Active Directory Graph and Microsoft Graph permissions. It seems that some of the commands in the az cli still points to https://graph.windows.net when it makes calls, according to some issue notes in the az cli git hub repository, it looks like this is in the process of being changed.

With Azure Active Directory Graph we need 2 permissions

  • Application.ReadWrite.All – This allows us to read and write the Application Registrations.
  • Directory.ReadWrite.All – This allows us to read the application registration permission list, and service principal information.

With Microsoft Graph we also need permission.

  • AppRoleAssignment.ReadWrite.All – This allows us to call the REST API to grant permissions and assign Role assignment permissions.

Steps in the code

  • Set-AppRegistration
  • Set-AppCredentials
  • Set-ServicePrincipalForAppId
  • Remove-CurrentAppPermissions
  • Set-DelegatePermissions
    • Remove-CurrentOauth2PermissionGrants
  • Set-ApplicationPermissions
    • Remove-CurrentServicePrincipalGrants

Please note, the snippets of code I am showing here in the blog, are showing the command(s) that are performing the main action, not the full function.

Set-AppRegistration

We need an App Registration to be created first. If the name already exists it just returns the existing App Registration

#Creates or updates an existing App Registration
az ad app create --display-name '$ApplicationName'
view raw appReg.ps1 hosted with ❤ by GitHub

Set-AppCredentials

#Creates a secret with a random password
az ad app credential reset --id $AppId --credential-description 'Registration' --end-date 2299-12-31
view raw appcredential.ps1 hosted with ❤ by GitHub

This will create a secret for the App Registration with a random secret with the description set to Registration. There are a couple of override parameters that I am not using, where you can give it your own Description, and provide your own SecureString secret. This returns the appCredentials that supply the appId, name, password and tenantId. In the script it outputs this to screen at the end, however, if using in production environment, you would probably want to put the secret value in a keyvault, without displaying to the user what the value is.

Set-ServicePrincipalForAppId

#Creates a Service Principal for a given Application Registration Id
az ad sp create --id $AppId
view raw servicePrincipal.ps1 hosted with ❤ by GitHub

All App Registrations require a Service Principal behind them. When you manually create an App Registration and assign permissions, it automatically creates a service principal for you. When you create an App Registration programmatically, it is your responsibility to also create the Service Principal. It is the Service Principal that defines the access policy and permissions for the user/application in the Azure AD tenant. A multi-tenant App Registration would have the same app Id in all tenants, but all have a different Service Principal which allows them access within that tenant. For example, in all tenants the AppId for the Microsoft Graph API is ‘00000003-0000-0000-c000-000000000000’ and in your tenant it has an associated Service Principal, which is a different object Id in your tenant compared to mine. When I finally understood this, it made more sense how this all ties together.

Reference: https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals

The above az command is not idempotent, and therefore a check to see if it already exists is required.

Remove-CurrentAppPermissions

To allow idempotency of my script, I wanted to ensure that it removes all existing permissions before adding them back in. This piece of code does not remove the permission from the service principal, and if you stop the code after this command, you will see that your API Permissions in the GUI would look like this.

Seeing the permissions separated at the bottom of the screen, now understanding the relationship between Application Registrations and Service Principal, it makes a lot more sense to me now. The service principal still has access at this point and calls to these API’s will still work.

#Get all permissions for the Application Registration
$currentPermissionCollection = @(az ad app permission list --id $AppId | ConvertFrom-Json)
#Remove the permissions (resourceAppId) for the Application Registration
$currentPermissionCollection | ForEach-Object {
$permission = $PSItem
if ($permission.Count -eq 0) { return }
$permission.resourceAppId | ForEach-Object{
$resourceAppId = $PSItem
az ad app permission delete --id $AppId --api $resourceAppId
}
}

The code gets a list of all the permissions assigned to the Application Registration, then loops through each resourceAppId (the objectId value of the API permission service principal e.g, Microsoft Graph, SharePoint)*2 and deletes the permission.

Set-DelegatePermissions

To ensure the code is idempotent the first thing I am doing is removing the delegate permission from the Service Principal. See the next section on how this works.

Now we need to assign the Application Registration permissions for the delegate permissions. We do this by providing the AppID of our Application Registration, the API Permission AppID (the appID of the API Permission service principal e.g, Microsoft Graph)*2 and the oauth2Permissions scope Id*4

#Get Graph APIServicePrinicpal information
$APIServicePrincipal = az ad sp list --query "[?appDisplayName=='Microsoft Graph'].{appId:appId,objectId:objectId}" --all | ConvertFrom-Json
#Get Directory.ReadWrite.All oauth2Permission
$delegatePermInfo = az ad sp show --id $($APIServicePrincipal.appId) --query "oauth2Permissions[?value=='Directory.ReadWrite.All']" | ConvertFrom-Json
#Add Permission (Scope means Delegate)
az ad app permission add --id $appId --api $($APIServicePrincipal.appId) --api-permissions $($delegatePermInfo.id)=Scope

Next, we need to assign the Application Registration associated Service Principal oauth2Permissions to grant these permissions to the tenant.

Using Graph API explorer, you can view all the delegate permissions in your tenant using the following URL:

https://graph.microsoft.com/v1.0/oauth2permissiongrants

To find all the permissions grants for your Application Registration you will need the Service Principal Object ID*1 and then use the following URL:

https://graph.microsoft.com/v1.0/oauth2permissiongrants?$filter=clientId eq ‘<servicePrincipalObjectId>’ and consentType eq ‘AllPrincipals’

{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#oauth2PermissionGrants",
"value": [
{
"clientId": "8xxxxxx-xxxx-xxxx-xxxx-xxxxxxxx8299",
"consentType": "AllPrincipals",
"id": "AxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxWry4",
"principalId": null,
"resourceId": "a2adb674-25ec-4bba-ba12-f6fc2f96af2e",
"scope": "User.Read Group.ReadWrite.All"
}
]
}
  • clientId: This is the Service Principal Object ID that is tied to your App Registration
  • consentType: Set to AllPrincipals when granted to the entire tenant, or Principal when granted to an individual user
  • id: The ID of the oauth2permissiongrants
  • principalId: This is set to null if using AllPrincipals, otherwise it will contain the objectID of the User that has been granted the permission
  • resourceId: This is the Serivce Principal Object ID value of the API Permission*2
  • scope: This is a string array of granted scope values for the given ResourceId. (e.g User.Read Directory.Read.All etc)

If the oauth2permissiongrants with the App Registration Service Principal Object ID and API Permission Service Principal Object ID (clientId and resourceId) doesn’t exist in your tenant, then you will need to POST a new oauth2permissiongrants, otherwise you will require to PATCH an existing oauth2permissiongrants/<id> with the new string array of scope values.

#Get a access Token
$tokenResponse = az account get-access-token --resource-type ms-graph | convertFrom-Json
$body = @{
clientId = $($servicePrincipal.objectId)
consentType = "AllPrincipals"
principalId = $null
resourceId = $($APIServicePrincipal.objectId)
scope = "User.Read Directory.ReadWrite.All"
startTime = "0001-01-01T00:00:00Z"
expiryTime = "2299-12-31T00:00:00Z"
}
$apiUrl = "https://graph.microsoft.com/v1.0/oauth2Permissiongrants"
Invoke-RestMethod -Uri $apiUrl -Headers @{Authorization = "Bearer $($tokenResponse.accessToken)" } -Method $method -Body $($body | ConvertTo-Json) -ContentType "application/json"

You must add a startTime and expiryTime, it does not matter what the datetime is, as long as expiryTime is later than the startTime.

Remove-CurrentOauth2PermissionGrants

To remove the permissions from the Service Principal for the Delegate Permissions, we need to remove the Oauth2PermissionGrants.

Unfortunately, with App Only permissions you cannot delete an oauth2permissiongrants. You require to access the directory as a person to delete. I found that by setting the scope to empty string, gives the same desired effect as removing them.

#Get all Permission for the Service prinipal ObjectId.
$exisitingCollection = az ad app permission list-grants --filter "clientId eq '$($ServicePrincipalObjectId)' and consentType eq 'AllPrincipals'" | ConvertFrom-Json
#Get a access Token
$tokenResponse = az account get-access-token --resource-type ms-graph | convertFrom-Json
$existingCollection | ForEach-Object {
$existing = $PSItem
#Get the PermissionGrant
$apiUrlPatch = "https://graph.microsoft.com/v1.0/oauth2Permissiongrants/$($existing.objectId)"
$body = @{
scope = ""
}
#Patch with an empty scope.
Invoke-RestMethod -uri $apiUrlPatch -Headers @{Authorization = "Bearer $(tokenResponse.accessToken)"} -Method $PATCH -Body $($body | ConvertTo-Json) -ContentType "application/json"
}

Please Note: I am using Invoke-RestMethod instead of az rest because I have not been able to get it to work without an error message.

Set-ApplicationPermissions

To ensure the code is idempotent the first thing I am doing is removing the application permission grants from the Service Principal. See the next section on how this works.

Now we need to assign the Application Registration permissions for the application permissions. We do this by providing the AppID of our Application Registration, the API Permission AppID (the appID of the API Permission service principal e.g, Microsoft Graph)*2 and the AppRoles scope Id*3

#Get Graph APIServicePrinicpal information
$APIServicePrincipal = az ad sp list --query "[?appDisplayName=='Microsoft Graph'].{appId:appId,objectId:objectId}" --all | ConvertFrom-Json
#Get Directory.ReadWrite.All appRolesPermission
$appRolePermInfo = az ad sp show --id $($APIServicePrincipal.appId) --query "appRoles[?value=='Directory.ReadWrite.All']" | ConvertFrom-Json
#Add Permission (Role means Application)
az ad app permission add --id $appId --api $($APIServicePrincipal.appId) --api-permissions $($appRolePermInfo.id)=Role

Next, we need to assign the Application Registration associated Service Principal AppRoleAssignments to grant these permissions to the tenant.

Using Graph API explorer, you can view all the Application Role Grants for your Application Registration. You will need the Service Principal Object ID*1 and then use the following URL:

https://graph.microsoft.com/v1.0/servicePrincipals//appRoleAssignments

"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#servicePrincipals('862b7a01-7bb3-4540-ae4e-a2a84c7d8299&#39;)/appRoleAssignments",
"value": [
{
"id": "AxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxCw",
"deletedDateTime": null,
"appRoleId": "57xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx04",
"createdDateTime": "2020-06-18T10:45:50.700178Z",
"principalDisplayName": "CFCodeApp",
"principalId": "86xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx99",
"principalType": "ServicePrincipal",
"resourceDisplayName": "Windows Azure Active Directory",
"resourceId": "5cxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx27"
},
{
"id": "AxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxA8",
"deletedDateTime": null,
"appRoleId": "33xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx0d",
"createdDateTime": "2020-06-18T09:50:01.3746638Z",
"principalDisplayName": "CFCodeApp",
"principalId": "86xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx99",
"principalType": "ServicePrincipal",
"resourceDisplayName": "Microsoft Graph",
"resourceId": "a2xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx2e"
},
{
"id": "AxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxHI",
"deletedDateTime": null,
"appRoleId": "7axxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx61",
"createdDateTime": "2020-06-18T09:49:51.3226179Z",
"principalDisplayName": "CFCodeApp",
"principalId": "86xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx99",
"principalType": "ServicePrincipal",
"resourceDisplayName": "Microsoft Graph",
"resourceId": "a2xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx2e"
}
]
}

Unlike the Oauth2PermissionGrants, where there is only one entry per clientid and resourceId which contains all the scopes, with AppRoleAssignments there is an entry for each scope, and it uses the appRoleId scope Id*3 instead of the scope string value.

  • id: The ID of the appRoleAssignment
  • principalId: The Service Principal Object ID that is tied to your App Registration
  • resourceId: This is the Serivce Principal Object ID value of the API Permission*2
  • appRoleId: This is the scope Id*3
#Get a access Token
$tokenResponse = az account get-access-token --resource-type ms-graph | convertFrom-Json
$body = @{
principalId = $ServicePrincipal.objectId
resourceId = $APIServicePrincipal.objectId
appRoleId = $appPermInfo.id
}
$appRoleAssignmentUrl = "https://graph.microsoft.com/v1.0/servicePrincipals/$($ServicePrincipal.objectId)/appRoleAssignments"
Invoke-RestMethod -Uri $appRoleAssignmentUrl -Headers @{Authorization = "Bearer $($tokenResponse.accessToken)" } -Method POST -Body $($body | ConvertTo-Json) -ContentType "application/json"

Remove-CurrentServicePrincipalGrants

To remove the permission from the Service Principal for the Application Role permissions, we need to remove the AppRoleAssignments ID’s for the service principal

#Get a access Token
$tokenResponse = az account get-access-token --resource-type ms-graph | convertFrom-Json
#Get all App Role Assignment Permission for the Service prinipal ObjectId.
$apiUrl = "https://graph.microsoft.com/v1.0/servicePrincipals/$ServicePrincipalObjectId/appRoleAssignments"
$appRoleAssignmentCollection = @(Invoke-RestMethod -Uri $apiUrl -Headers @{Authorization = "Bearer $($tokenResponse.accessToken)" } -Method GET -ContentType "application/json").value
$appRoleAssignmentCollection | ForEach-Object {
$appRoleAssignment = $PSItem
$deleteApiUrl = "$apiUrl/$($appRoleAssignment.id)"
Invoke-RestMethod -Uri $deleteApiUrl -Headers @{Authorization = "bearer $($tokenResponse.accessToken)" } -Method Delete -ContentType "application/json"
}

Please Note: I am using Invoke-RestMethod instead of az rest because I have not been able to get it to work without an error message.

Conclusion

That is it. In the Data folder of the github project there is an examplePermission.json file. As you can see that the JSON format is very flexible to add more or remove permissions. The name can be the appDisplayName or the AppId of the API Permission.

Run the Add-RegistrationAndGrantPermissions.ps1 script passing in the name of your App Registration you wish to create / update and your custom permission file. The script will run fine with user logged in, or an App Only with the correct permissions.

Please feel free to use/enhance the github project.

Footnotes

*1 How to find your Service Principal Object ID of your Application Registration

Using the GUI, the quickest way to find your Service Principal Object ID is to first go to the overview of the Application Registration. Then on the right-hand side of the screen, click the name of your Application Registration where Manage application in local directory is.

This will take you to the Service Principal information in your tenant. It is here you can get the ObjectID.

*2 How to find the Service Principal Object Id for the Permission API.

You may already know that Microsoft Graph API appId is 00000003-0000-0000-c000-000000000000, this is the same on all tenants, but the service principal object ID is different in each tenant. This is the resourceId. To find out what the objectID is in your tenant run the following script.

az ad sp list --query "[?appId=='00000003-0000-0000-c000-000000000000'].{appDisplayName:appDisplayName,appId:appId,objectId:objectId}" --all --output table
AppDisplayName AppId ObjectId
---------------- ------------------------------------ ------------------------------------
Microsoft Graph 00000003-0000-0000-c000-000000000000 axxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxe
....

Remove “?appId== ‘00000003-0000-0000-c000-000000000000′” between the [ ] and it will list all for your tenant.

*3 How to find the Application Role Id of a Permission API Scope.

For each Permission API such as Microsoft Graph API, there are Application Role. No matter what tenant you are in, the id of them is always the same. The below example gets the Application Scope of Directory.Read.All from the Permission API Microsoft Graph.

az ad sp show --id '00000003-0000-0000-c000-000000000000' --query "appRoles[?value=='Directory.Read.All']"

Output:

[
{
"allowedMemberTypes": [
"Application"
],
"description": "Allows the app to read data in your organization's directory, such as users, groups and apps, without a signed-in user.",
"displayName": "Read directory data",
"id": "7ab1d382-f21e-4acd-a863-ba3e13f7da61",
"isEnabled": true,
"value": "Directory.Read.All"
}
]

*4 How to find the oAuth2Permission Id of a Permission API Scope.

For each Permission API such as Microsoft Graph API, there are oauth2Permissions. No matter what tenant you are in, the id of them is always the same. The below example gets the Delegation Scope of Directory.Read.All from the Permission API Microsoft Graph.

az ad sp show --id '00000003-0000-0000-c000-000000000000' --query "oauth2Permissions[?value=='Directory.Read.All']"

Output:

[
{
"adminConsentDescription": "Allows the app to read data in your organization's directory, such as users, groups and apps.",
"adminConsentDisplayName": "Read directory data",
"id": "06da0dbc-49e2-44d2-8312-53f166ab848a",
"isEnabled": true,
"type": "Admin",
"userConsentDescription": "Allows the app to read data in your organization's directory.",
"userConsentDisplayName": "Read directory data",
"value": "Directory.Read.All"
}
]