Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

After you have published the SCIM microservice app to Azure, run the following PowerShell script to assign Graph API and Azure REST API permissions to the app service managed identity.

Set Graph API Permissions

As the service principal is the identity that the Azure AD SCIM app service runs as it calls Microsoft Graph, you need to assign the service principal permissions required for your use case. You assign these permissions using the Azure CLI, which is a command-line tool that use to connect to Azure and execute administrative commands on Azure resources.

To assign permissions to the service principal, you need to complete the following tasks:

  1. Install Azure CLI on your machine (if not already installed). For instructions, see Install the Azure CLI for Windows | Microsoft Docs.

  2. Sign in to your tenant with Azure CLI using .

  3. Open an administrative command prompt or PowerShell session and set assign permissions to the service principal for your use case.

  4. Create an application in Azure AD and associate it with the certificate you generated in EmpowerID.

Install Azure CLI

If Azure CLI is not installed on your machine, please see Microsoft’s instructions for doing so here: Install the Azure CLI for Windows | Microsoft Docs. Once you install the CLI, sign in to your tenant with the Azure CLI using the credentials of a user with adequate permissions to execute the permissions script in Azure AD (owner at the tenant level).grant the service principal the appropriate access in Azure by running the permissions script shown in the Set Graph API Permissions section of this article.

Set Graph API Permissions

To set Graph API permissions, sign in to your tenant with the Azure CLI using the credentials of a user with adequate permissions to execute the script in Azure AD (owner at the tenant level) and then execute the script against the tenant. run the below script in either an administrative command prompt or PowerShell session. The script

Permissions follow the least-privilege principle and include the following for managing Azure Licenses:

Table 1: Permissions needed to manage Azure licenses in EmpowerID

Graph API / Permissions name

Access Granted by Permissions

Used By

AuditLog.Read.All

Read audit log data

App Service Managed Identity

Group.Read.All

Read group data

App Service Managed Identity

GroupMember.ReadWrite.All

Read and write group memberships

App Service Managed Identity

User.Read.All

Read user profile

App Service Managed Identity

Reports.Read.All

Read report data

App Service Managed Identity

Organization.Read.All

Read organization information

App Service Managed Identity

Policy.Read.lAll

Policy.ReadWrite.ConditionalAccess

Domain.Read.All

In addition to adding the permissions, you need to enter values for the below parameters:

  • webApp — Name of the app service you created for the Azure AD SCIM microservice

Tip

When running the script, be sure to authenticate to Azure as a user with adequate permissions to execute it in Azure AD (owner at the tenant level).

Code Block
languagepowershell
$webApp="<Web-App-Name>"
$sprincipal_id=$(az resource list -n $webApp --query [*].identity.principalId --out tsv)
$graphResourceId=$(az ad sp list --display-name "Microsoft Graph" --query [0].objectId --out tsv)
$uri="https://graph.microsoft.com/v1.0/servicePrincipals/$sprincipal_id/appRoleAssignments"
$PermissionsToAdd = @("RoleManagement.ReadWrite.Directory","Directory.ReadWrite.All","Organization.Read.All", "User.Read.All", "Group.Read.All", "GroupMember.ReadWrite.All", "Reports.Read.All", "AuditLog.Read.All","Policy.Read.All","Policy.ReadWrite.ConditionalAccess","Application.Read.All","Domain.Read.All")

$PermissionsToAdd | foreach {

    $appRoleId=$(az ad sp list --display-name "Microsoft Graph" --query "[0].appRoles[?value=='$($_)' && contains(allowedMemberTypes, 'Application')].id" --output tsv)
    $body="{'principalId':'$sprincipal_id','resourceId':'$graphResourceId','appRoleId':'$appRoleId'}"
    az rest --method post --uri $uri --body $body --headers "Content-Type=application/json"
}

Page Properties
hiddentrue

Set Azure REST API Permissions

If you are managing Azure roles and management groups in EmpowerID, in addition to setting the above permissions for license management via PowerShell, you need to add the below permissions scoped to the appropriate Azure subscription(s) you want to manage in EmpowerID. These permissions allow EmpowerID to call the relevant Azure REST API endpoints needed to manage Azure roles and management groups.

Table 2: Permissions needed to manage Azure roles in EmpowerID

...

SCIM Endpoint

Azure REST API / Permissions name

Access Granted by Permissions

Used By

...

Microsoft.ManagedIdentity/userAssignedIdentities/write

User Assigned Identities - Create

App service managed identity

...

/v1/{0}/roleAssignment

Microsoft.Authorization/roleAssignments/write

Role Assignments - Create

App service managed identity

...

/v1/{0}/roleAssignment/{1}

Microsoft.Authorization/roleAssignments/read

Role Assignments - Delete

App service managed identity

...

/v1/classicadministrator/{0}

Microsoft.Authorization/classicAdministrators/read

Classic Administrators - List

App service managed identity

...

Microsoft.ManagedIdentity/userAssignedIdentities/read

User Assigned Identities - List By Resource Group / Subscription

App service managed identity

...

v1/{0}:{1}/managedidentities/{2}

Microsoft.ManagedIdentity/userAssignedIdentities/delete

User Assigned Identities - Delete

App service managed identity

...

v1/{0}:{1}/managedidentities/{2}

Microsoft.ManagedIdentity/userAssignedIdentities/write

User Assigned Identities - Create Or Update (UPDATE)

App service managed identity

...

Microsoft.Authorization/roleAssignments/read

Role Assignments - Get

App service managed identity

...

/v1/{0}/roleAssignment/{1}

Microsoft.Authorization/roleAssignments/delete

Role Assignments - Delete

App service managed identity

...

Microsoft.Authorization/roleAssignments/write

Role Assignments - Create

App service managed identity

...

Microsoft.Authorization/roleDefinitions/read

Role Definitions - Get

App service managed identity

...

/v1/ManagementGroup/roleDefinition/{0}

Microsoft.Authorization/roleDefinitions/write

Role Definitions - Create

App service managed identity

...

Microsoft.Authorization/roleDefinitions/delete

Role Definitions - Delete

App service managed identity

...

/v1/ManagementGroup/roleDefinition/{0}

Microsoft.Authorization/roleDefinitions/write

Role Definitions - Update

App service managed identity

...

Microsoft.ManagedIdentity/userAssignedIdentities/read

User Assigned Identities - List By Resource Group / Subscription

App service managed identity

...

/v1/managementgroups/{0}

Microsoft.Management/managementGroups/read

Management Groups - Get

App service managed identity

...

Microsoft.Management/managementGroups/read

Management Groups - Get

App service managed identity

...

Microsoft.Resources/subscriptions/resourceGroups/read

Resource Groups - List

App service managed identity

...

/v1/{0}/resources

Microsoft.Resources/subscriptions/resources

Resources - List

App service managed identity

...

Microsoft.Authorization/roleAssignments/read

Role Assignments - List

App service managed identity

...

/v1/{0}/roleDefinition

Microsoft.Authorization/roleDefinitions/read

Role Definitions - List

App service managed identity

...

Microsoft.Resources/tenant/read

Tenants - List

App service managed identity

...

Microsoft.Resources/subscriptions/read

Subscriptions

App service managed identity

...

v1/{0}/SubscriptionUsages

Usage Details - List

Microsoft.Consumption/usageDetails/read

App service managed identity

The permissions needed to manage Azure licenses have been added to the script's PermissionsToAdd parameter, shown below. To add permissions for role management, add the permission name from the Azure REST API / Permissions name column of Table 2: Permissions needed to manage Azure roles in EmpowerID.

In addition to adding the permissions, you need to enter values for the below parameters:

...

  • webApp — Name of the app service you created for the Azure AD SCIM microservice

  • appServiceObjectID — Object ID of the Azure AD SCIM app service you created. This can be found on the Identities blade on the app service.

Tip

...

When running the script, be sure to authenticate to Azure as a user with adequate permissions to execute it in Azure AD (owner at the tenant level).

Code Block
languagepowershell
###############
## GRAPH API ##
###############
Param(
    $tenantId = "",
    $appServiceObjectID = "", 
    $PermissionsToAdd = @("Organization.Read.All", "User.Read.All", "Group.Read.All", "GroupMember.ReadWrite.All", "Reports.Read.All", "AuditLog.Read.All")
)

# Install AzureAD module if not installed
if (-Not(Get-Module -ListAvailable -Name AzureAD)) {
    try {
        Install-Module AzureAD -Force
    }
    catch {
        if ($_.Exception.Message.Contains("Administrator rights")) {
            Write-Host "You must run the script with administrator rights"
            
        }
        else {
            Write-Error $_.Exception.Message
        }
        
    }
}


if (Get-Module -ListAvailable -Name AzureAD) {
    # Check if connected to the target Azure AD Tenant
    try { 
        $tenantDetail = Get-AzureADTenantDetail 
    } 
    catch [Microsoft.Open.Azure.AD.CommonLibrary.AadNeedAuthenticationException] 
    { 
        Write-Host "You're not connected."; 
        Connect-AzureAD -TenantId $tenantId;
        $tenantDetail = Get-AzureADTenantDetail 
    }

    if ($tenantDetail.ObjectId -ne $tenantId) {
        Write-Host "You're not connected to the tenant: " $tenantId; 
        Connect-AzureAD -TenantId $tenantId;
    }


    # Managed Identity for the SCIM App Service | Found in App Service -> Identity 
    $ManagedIdentitiesServicePrincipal = Get-AzureADServicePrincipal -Filter "ObjectId eq `'$appServiceObjectID`'"
    if ($ManagedIdentitiesServicePrincipal -eq $null) {
        throw "Managed Identity for the app service is not found. `nApp Service Object ID: $appServiceObjectID "
    }

    # Resource Name : Microsoft Graph | Resource URI : https://graph.microsoft.com | Application ID : 00000003-0000-0000-c000-000000000000
    $GraphAppId = "00000003-0000-0000-c000-000000000000"
    $GraphServicePrincipal = Get-AzureADServicePrincipal -Filter "appId eq '$GraphAppId'"

    # Permissions
    foreach ($PermissionToAdd in $PermissionsToAdd) {
        $AppRole = $GraphServicePrincipal.AppRoles | Where-Object {$_.Value -eq $PermissionToAdd.Trim() -and $_.AllowedMemberTypes -contains "Application"}
        if ($AppRole -eq $null) {
            Write-Error "Invalid Permission `nPermission name: $PermissionToAdd"
        }
        else {
            # Assigns a Graph API service principal to an application role
            try {
                New-AzureAdServiceAppRoleAssignment -ObjectId $ManagedIdentitiesServicePrincipal.ObjectId -PrincipalId $ManagedIdentitiesServicePrincipal.ObjectId -ResourceId $GraphServicePrincipal.ObjectId -Id $AppRole.Id -ErrorAction Stop
            }
            catch {
                if ($_.Exception.ErrorContent.Message.Value.Contains("Permission being assigned already")) {
                    Write-Host "`""$AppRole.DisplayName"`"" " Permission is already assigned on the app service"
                }
                else {
                    Write-Error $_
                }
            }
        }
    }
}

true
Page Properties
hidden

To set the Azure REST API Permissions for the target subscription, do the following:

  1. In Azure, navigate to the target subscription and select Access control (IAM) from the Azure navbar.

  2. On the Access Control (IAM) page, click Add and select Add custom role.

  3. Under Basics, enter a Custom role name.

  4. Select the Permissions tab and click Add permissions.

  5. Search for Microsoft.ManagedIdentity and click the Microsoft Managed Identity tile.

  6. For Actions, under Microsoft.ManagedIdentity/userAssignedIdentities, select the following:

    • Read : Get User Assigned Identity

    • Write : Create/Update User Assigned Identity

    • Delete : Delete User Assigned Identity

  7. Click Add.

  8. Back on the Create a custom role page, click Add permissions again and then search for Microsoft.Authorization.

  9. Click the Microsoft Authorization tile and then add the below permissions:

    • Microsoft.Authorization/roleAssignments

      • Read : Get role assignment

      • Write : Create role assignment

      • Delete : Delete role assignment

    • Microsoft.Authorization/roleDefinitions

      • Read : Get role definition

      • Write : Create or update custom role definition

      • Delete : Delete custom role definition

  10. Click Add.

  11. Back on the Create a custom role page, click Add permissions again and then search for Microsoft.Authorization.

  12. Click the Microsoft Management tile and select Read : List Groups under Microsoft.Management/managementGroups.

  13. Click Add.

  14. Back on the Create a custom role page, click Add permissions again and then search for Microsoft.Resources.

  15. Click the Microsoft Resources tile and then select the following permissions:

    • Microsoft.Resources/subscriptions/resourcegroups

      • Read : Get Resource Group

    • Microsoft.Resources/subscriptions/resources

      • Read : Get Subscription Resources

    • Microsoft.Resources/tenant

      • Read : Get Tenants

  16. Click Add.

  17. Back on the Create a custom role page, select the Assignable scopes tab and verify the scope.

  18. Click Review + Create.

  19. Review the permissions and then click Create.

  20. Click OK to close the “created custom role” message.


    Now that you have created the custom role with the needed permissions, you need to assign the Azure AD SCIM microservice to the role.

  21. On the Access control (IAM) page, click Add > Add role assignment.

  22. In the Add role assignment pane that appears, enter the following:

    • Role – Select the custom role you just created

    • Assign access to – App Service

    • Subscription – Target subscription

    • Select – The SCIM app service you created earlier.

  23. Click Save to add the role assignment.

  24. On the Access control (IAM) page, select the Role assignments tab. You should see the SCIM app service you created assigned to the custom role.

...

Next Steps

Connect EmpowerID to Azure Active Directory

...