New-EntraServicePrincipalAppRoleAssignment

Module:

Microsoft.Graph.Entra

Assigns a service principal to an application role.

Syntax

New-EntraServicePrincipalAppRoleAssignment
   -ObjectId <String>
   -PrincipalId <String>
   -Id <String>
   -ResourceId <String>
   [<CommonParameters>]

Description

The New-EntraServicePrincipalAppRoleAssignment cmdlet assigns a service principal to an application role in Microsoft Entra ID.

For delegated scenarios, the calling user needs at least one of the following Microsoft Entra roles.

• Directory Synchronization Accounts
• Directory Writer
• Hybrid Identity Administrator
• Identity Governance Administrator
• Privileged Role Administrator
• User Administrator
• Application Administrator
• Cloud Application Administrator

Examples

Example 1: Assign an app role to another service principal

Connect-Entra -Scopes 'AppRoleAssignment.ReadWrite.All'
 $appname = 'Box'
 $spo = Get-EntraServicePrincipal -Filter "Displayname eq '$appname'"
 $params = @{
    ObjectId = $spo.ObjectId
    ResourceId = $spo.ObjectId
    Id = $spo.Approles[1].Id
    PrincipalId = $spo.ObjectId
}

New-EntraServicePrincipalAppRoleAssignment @params

Id                                          AppRoleId                            CreationTimestamp   PrincipalDisplayName PrincipalId                          PrincipalType    ResourceDisplayName ResourceId
--                                          ---------                            -----------------   -------------------- -----------                          -------------    ------------------- ----------
1aaaaaa1-2bb2-3cc3-4dd4-5eeeeeeeeee5 00000000-0000-0000-0000-000000000000 12-03-2024 11:05:29 Box                  aaaaaaaa-bbbb-cccc-1111-222222222222 ServicePrincipal Box                 aaaa0000-bb11-2222-33cc-444444dddddd

This example demonstrates how to assign an app role to another service principal in Microsoft Entra ID. You can use the command Get-EntraServicePrincipal to get a service principal Id.

• -ObjectId parameter specifies the ObjectId of a client service principal to which you're assigning the app role.
• -ResourceIdparameter specifies the ObjectId of the resource service principal.
• -Id parameter specifies the Id of the app role (defined on the resource service principal) to assign to the client service principal. If no app roles are defined on the resource app, you can use 00000000-0000-0000-0000-000000000000.
• -PrincipalId parameter specifies the ObjectId of the client service principal to which you're assigning the app role.

Example 2: Assign an app role to a user

Connect-Entra -Scopes 'AppRoleAssignment.ReadWrite.All'
 $appname = 'Box'
 $spo = Get-EntraServicePrincipal -Filter "Displayname eq '$appname'"
 $user = Get-EntraUser -SearchString 'Test Contoso'

 $params = @{
    ObjectId = $spo.ObjectId
    ResourceId = $spo.ObjectId
    Id = $spo.Approles[1].Id
    PrincipalId = $user.ObjectId
}

New-EntraServicePrincipalAppRoleAssignment @params

Id                                          AppRoleId                            CreationTimestamp   PrincipalDisplayName PrincipalId                          PrincipalType    ResourceDisplayName ResourceId
--                                          ---------                            -----------------   -------------------- -----------                          -------------    ------------------- ----------
2bbbbbb2-3cc3-4dd4-5ee5-6ffffffffff6 00000000-0000-0000-0000-000000000000 12-03-2024 11:05:29 Box                  aaaaaaaa-bbbb-cccc-1111-222222222222 ServicePrincipal Box                 bbbb1111-cc22-3333-44dd-555555eeeeee

This example demonstrates how to assign an app role to a user in Microsoft Entra ID.
You can use the command Get-EntraServicePrincipal to get a service principal Id.
You can use the command Get-EntraUser to get a user Id.

• -ObjectId parameter specifies the ObjectId of the app's service principal.
• -ResourceIdparameter specifies the ObjectId of the app's service principal.
• -Id parameter specifies the Id of app role (defined on the app's service principal) to assign to the user. If no app roles are defined to the resource app, you can use 00000000-0000-0000-0000-000000000000 to indicate that the app is assigned to the user.
• -PrincipalId parameter specifies the ObjectId of a user to which you're assigning the app role.

Example 3: Assign an app role to a group

Connect-Entra -Scopes 'AppRoleAssignment.ReadWrite.All'
 $appname = 'Box'
 $spo = Get-EntraServicePrincipal -Filter "Displayname eq '$appname'"
 $group = Get-EntraGroup -SearchString 'testGroup'

 $params = @{
    ObjectId = $spo.ObjectId
    ResourceId = $spo.ObjectId
    Id = $spo.Approles[1].Id
    PrincipalId = $group.ObjectId
 }

 New-EntraServicePrincipalAppRoleAssignment @params

Id                                          AppRoleId                            CreationTimestamp   PrincipalDisplayName PrincipalId                          PrincipalType    ResourceDisplayName ResourceId
--                                          ---------                            -----------------   -------------------- -----------                          -------------    ------------------- ----------
3cccccc3-4dd4-5ee5-6ff6-7aaaaaaaaaa7 00000000-0000-0000-0000-000000000000 12-03-2024 11:05:29 Box                  aaaaaaaa-bbbb-cccc-1111-222222222222 ServicePrincipal Box                 cccc2222-dd33-4444-55ee-666666ffffff

This example demonstrates how to assign an app role to a group in Microsoft Entra ID.
You can use the command Get-EntraServicePrincipal to get a service principal Id.
You can use the command Get-EntraGroup to get a group Id.

• -ObjectId parameter specifies the ObjectId of the app's service principal.
• -ResourceIdparameter specifies the ObjectId of the app's service principal.
• -Id parameter specifies the Id of app role (defined on the app's service principal) to assign to the group. If no app roles are defined to the resource app, you can use 00000000-0000-0000-0000-000000000000 to indicate that the app is assigned to the group.
• -PrincipalId parameter specifies the ObjectId of a group to which you're assigning the app role.

Parameters

-Id

Specifies the ID.

Type:	System.String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-ObjectId

Specifies the ID of a service principal in Microsoft Entra ID.

Type:	System.String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-PrincipalId

Specifies a principal ID.

Type:	System.String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

-ResourceId

Specifies a resource ID.

Type:	System.String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	False
Accept wildcard characters:	False

Notes

New-EntraServiceAppRoleAssignment is an alias for New-EntraServicePrincipalAppRoleAssignment.

Related Links

• Get-EntraServicePrincipalAppRoleAssignment
• Remove-EntraServicePrincipalAppRoleAssignment