แก้ไข

แชร์ผ่าน

New-AzureADServiceAppRoleAssignment

Module:
AzureAD Module

Assigns an app role to a user, a group, or another service principal.

Syntax

Default (Default) 

New-AzureADServiceAppRoleAssignment
    -ObjectId <String>
    [-InformationAction <ActionPreference>]
    [-InformationVariable <String>]
    -Id <String>
    -PrincipalId <String>
    -ResourceId <String>
    [<CommonParameters>]

Description

The New-AzureADServiceAppRoleAssignment cmdlet assigns an app role from a resource service principal to a user, a group, or another service principal. App roles assigned to service principals are also known as application permissions.

Note

The behavior described here applies when Connect-AzureAD was called without any parameters, or using a Microsoft-owned application identity. See Example 4 to learn more about the difference when connected using a customer-owned app registration or service identity.

Examples

Example 1: Assign an app role to another service principal

PS C:\> Connect-AzureAD
PS C:\> New-AzureADServiceAppRoleAssignment -ObjectId $resource.ObjectId -ResourceId $resource.ObjectId -Id $appRole.Id -PrincipalId $client.ObjectId

In this example, a client service principal is assigned an app role (application permission) defined by a resource service principal (for example, an API):

  • ObjectId: The ObjectId of the resource service principal (for example, an API).
  • ResourceId: The ObjectId of the resource service principal (for example, an API).
  • Id: The Id of the app role (defined on the resource service principal) to assign to the client service principal. If no app roles have been defined on the resource app, you can use 00000000-0000-0000-0000-000000000000.
  • PrincipalId: The ObjectId of the client service principal to which you are assigning the app role.

Note

This example applies when Connect-AzureAD was called without any parameters. See Example 4 to see how this cmdlet is used when connected using a customer-owned app registration or service identity.

Example 2: Assign an app role to a user

PS C:\> Connect-AzureAD
PS C:\> New-AzureADServiceAppRoleAssignment -ObjectId $resource.ObjectId -ResourceId $resource.ObjectId -Id $appRole.Id -PrincipalId $user.ObjectId

In this example, a user is assigned an app role defined by a resource app:

  • ObjectId: The ObjectId of the app's service principal.
  • ResourceId: The ObjectId of the app's service principal.
  • Id: The Id of the app role (defined on the app's service principal) to assign to the user. If no app roles have been defined to the resource app, you can use 00000000-0000-0000-0000-000000000000 to indicate that the app is assigned to the user.
  • PrincipalId: The ObjectId of the user to which you are assigning the app role.

Note

This example applies when Connect-AzureAD was called without any parameters. See Example 4 to see how this cmdlet is used when connected using a customer-owned app registration or service identity.

Example 3: Assign an app role to a group

PS C:\> Connect-AzureAD
PS C:\> New-AzureADServiceAppRoleAssignment -ObjectId $resource.ObjectId -ResourceId $resource.ObjectId -Id $appRole.Id -PrincipalId $group.ObjectId

In this example, a group is assigned an app role defined by a resource app. All users who are direct member of the assigned group are considered to be assigned the app role:

  • ObjectId: The ObjectId of the app's service principal.
  • ResourceId: The ObjectId of the app's service principal.
  • Id: The Id of the app role (defined on the app's service principal) to assign to the group. If no app roles have been defined on the resource app, you can use 00000000-0000-0000-0000-000000000000 to indicate the app is assigned to the group.
  • PrincipalId: The ObjectId of the group to which you are assigning the app role.

Note

This example applies when Connect-AzureAD was called without any parameters. See Example 4 to see how this cmdlet is used when connected using a customer-owned app registration or service identity.

Example 4: When connected using a customer-owned app or service identity

PS C:\> Connect-AzureAD -TenantId $tenantOrDomain -ApplicationId $appId -CertificateThumbprint $thumb
PS C:\> New-AzureADServiceAppRoleAssignment -ObjectId $client.ObjectId -ResourceId $resource.ObjectId -Id $appRole.Id -PrincipalId $client.ObjectId

This cmdlet's behavior changes when connected to the Azure AD PowerShell module using a customer-owned app registration or service identity, including:

  • When connecting as a service principal, and
  • When using the AadAccessToken parameter with an access token obtained for a customer-owned app registration or service identity.

Under these circumstances, this cmdlet is only used for assigning an app role to another service principal, identified by the ObjectId and PrincipalId parameters:

  • ObjectId: The ObjectId of the client service principal to which you are assigning the app role.
  • ResourceId: The ObjectId of the resource service principal (for example, an API).
  • Id: The Id of the app role (defined on the resource service principal) to assign to the client service principal. If no app roles have been defined on the resource app, you can use 00000000-0000-0000-0000-000000000000.
  • PrincipalId: The ObjectId of the client service principal to which you are assigning the app role.

When connected using a customer-owned app or service identity, use New-AzureADUserAppRoleAssignment and New-AzureADGroupAppRoleAssignment to create app role assignments for a user and groups, respectively.

Parameters

-Id

Specifies the Id of the app role (defined on the resource service principal) to assign. If no app roles have been defined on the resource app, you can use 00000000-0000-0000-0000-000000000000 to indicate assignment of the resource app or service, without specifying an app role.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-InformationAction

Specifies how this cmdlet responds to an information event. The acceptable values for this parameter are:

  • Continue
  • Ignore
  • Inquire
  • SilentlyContinue
  • Stop
  • Suspend

Parameter properties

Type:ActionPreference
Default value:None
Supports wildcards:False
DontShow:False
Aliases:infa

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-InformationVariable

Specifies an information variable.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False
Aliases:iv

Parameter sets

(All)
Position:Named
Mandatory:False
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ObjectId

Specifies the ObjectId of the resource service principal (such as an app or an API) that is going to be assigned to a user, a group, or another service principal.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:True
Value from pipeline by property name:True
Value from remaining arguments:False

-PrincipalId

Specifies the ObjectId of the user, group, or other service principal to which the app role is being assigned.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

-ResourceId

Specifies the ObjectId of the resource service principal (such as an app or an API) that is going to be assigned to a user, a group, or another service principal.

Parameter properties

Type:String
Default value:None
Supports wildcards:False
DontShow:False

Parameter sets

(All)
Position:Named
Mandatory:True
Value from pipeline:False
Value from pipeline by property name:False
Value from remaining arguments:False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

Notes

See the migration guide for New-AzureADServiceAppRoleAssignment to the Microsoft Graph PowerShell.