New-EntraUserAppRoleAssignment

Módulo:
Microsoft.Entra.Users Module v1.3

Atribui um usuário a uma função de aplicativo.

Sintaxe

Default (Default) 

New-EntraUserAppRoleAssignment

    -UserId <String>
    -PrincipalId <String>
    -AppRoleId <String>
    -ResourceId <String>
    [<CommonParameters>]

Description

O New-EntraUserAppRoleAssignment cmdlet atribui um usuário a uma função de aplicativo em Microsoft Entra ID.

Em cenários delegados com contas corporativas ou de estudante, o usuário conectado deve ter uma função de Microsoft Entra com suporte ou uma função personalizada com as permissões necessárias. As funções suportadas incluem:

  • Contas de sincronização de diretório (para Entra Connect e Cloud Sync)
  • Editor de Diretórios
  • Administrador de identidade híbrida
  • Administrador de gestão de identidade
  • Administrador de Função Privilégiada
  • Administrador de usuários
  • Administrador de Aplicativos
  • Administrador de Aplicativos na Nuvem

Exemplos

Exemplo 1: Atribuir um usuário a um aplicativo sem funções

Connect-Entra -Scopes 'AppRoleAssignment.ReadWrite.All'
$appId = (Get-EntraApplication -SearchString '<App-DisplayName>').AppId
$user = Get-EntraUser -SearchString '<UserPrincipalName>'
$servicePrincipal = Get-EntraServicePrincipal -Filter "appId eq '$appId'"
$params = @{
    UserId      = $user.Id
    PrincipalId = $user.Id
    ResourceId  = $servicePrincipal.Id
    AppRoleId   = [Guid]::Empty
}
New-EntraUserAppRoleAssignment @params

DeletedDateTime Id                                          AppRoleId                            CreatedDateTime     PrincipalDisplayName PrincipalId                          PrincipalType ResourceDisplayName
--------------- --                                          ---------                            ---------------     -------------------- -----------                          ------------- ------------------- -
                A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u 00aa00aa-bb11-cc22-dd33-44ee44ee44ee 18-06-2024 11:22:40 UserPrincipalName          aaaaaaaa-bbbb-cccc-1111-222222222222 User          App-DisplayName

Esse comando atribui um usuário a um aplicativo que não tem nenhuma função.

  • -UserId O parâmetro especifica a ID de um usuário a quem você está atribuindo a função de aplicativo.
  • -PrincipalId O parâmetro especifica a ID de um usuário a quem você está atribuindo a função de aplicativo.
  • -ResourceId O parâmetro especifica a ID de um servicePrincipal de recursos que definiu a função de aplicativo.
  • -AppRoleId o parâmetro especifica a ID de um appRole (definido na entidade de serviço de recurso) a ser atribuído ao usuário.

Exemplo 2: Atribuir um usuário a uma função específica dentro de um aplicativo

Connect-Entra -Scopes 'AppRoleAssignment.ReadWrite.All'
$servicePrincipal = Get-EntraServicePrincipal -Filter "DisplayName eq 'Box'"
$user = Get-EntraUser -UserId 'SawyerM@contoso.com'
$params = @{
    UserId      = $user.Id
    PrincipalId = $user.Id
    ResourceId  = $servicePrincipal.Id
    AppRoleId   = $servicePrincipal.AppRoles[1].Id
}
New-EntraUserAppRoleAssignment @params

DeletedDateTime Id                                          AppRoleId                            CreatedDateTime     PrincipalDisplayName PrincipalId                          PrincipalType ResourceDisplayName
--------------- --                                          ---------                            ---------------     -------------------- -----------                          ------------- -------------------
                A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u 00aa00aa-bb11-cc22-dd33-44ee44ee44ee 06/18/2024 09:47:00 Sawyer Miller        1aaaaaa1-2bb2-3cc3-4dd4-5eeeeeeeeee5 User          Box

Este exemplo demonstra como atribuir um usuário a uma função de aplicativo em Microsoft Entra ID.

  • -UserId O parâmetro especifica a ID de um usuário a quem você está atribuindo a função de aplicativo.
  • -PrincipalId O parâmetro especifica a ID de um usuário a quem você está atribuindo a função de aplicativo.
  • -ResourceId O parâmetro especifica a ID de um servicePrincipal de recursos que definiu a função de aplicativo.
  • -AppRoleId o parâmetro especifica a ID de um appRole (definido na entidade de serviço de recurso) a ser atribuído ao usuário.

Parâmetros

-AppRoleId

A ID da função de aplicativo a ser atribuída.

Se o aplicativo não tiver nenhuma função ao criar uma nova atribuição de função de aplicativo, forneça um guid vazio ou a ID da função a ser atribuída ao usuário.

Você pode recuperar as funções do aplicativo examinando a propriedade AppRoles do objeto de aplicativo:

Get-EntraApplication -SearchString 'Your-Application-DisplayName' | Select-Object Approles | Format-List

Esse cmdlet retorna a lista de funções definidas em um aplicativo:

AppRoles: {GUID1, GUID2}

Propriedades do parâmetro

Tipo:System.String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-PrincipalId

A ID do objeto da entidade de segurança à qual a nova função de aplicativo é atribuída.

Ao atribuir uma nova função a um usuário, forneça a ID do objeto do usuário.

Propriedades do parâmetro

Tipo:System.String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-ResourceId

A ID do objeto da Entidade de Serviço para o aplicativo ao qual a função de usuário é atribuída.

Propriedades do parâmetro

Tipo:System.String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline pelo nome da propriedade:False
Valor dos argumentos restantes:False

-UserId

Especifica a ID do usuário (como UserPrincipalName ou ObjectId) em Microsoft Entra ID à qual a nova função de aplicativo deve ser atribuída.

Propriedades do parâmetro

Tipo:System.String
Valor padrão:None
Dá suporte a curingas:False
DontShow:False
Aliases:IdentificadorDeObjeto

Conjuntos de parâmetros

(All)
Cargo:Named
Obrigatório:True
Valor do pipeline:True
Valor do pipeline pelo nome da propriedade:True
Valor dos argumentos restantes:False

CommonParameters

Este cmdlet suporta os parâmetros comuns: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction e -WarningVariable. Para obter mais informações, consulte about_CommonParameters.