New-EntraUserAppRoleAssignment

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

Atribui ao utilizador um papel de aplicação.

Sintaxe

Default (Predefinição) 

New-EntraUserAppRoleAssignment

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

Descrição

O New-EntraUserAppRoleAssignment cmdlet atribui ao utilizador um papel de aplicação no Microsoft Entra ID.

Em cenários delegados com contas de trabalho ou escola, o utilizador iniciado deve ter uma função Microsoft Entra suportada ou uma função personalizada com as permissões necessárias. As funções suportadas incluem:

  • Contas de Sincronização de Diretórios (para Entra Connect e Cloud Sync)
  • Gravador de Diretórios
  • Administrador de identidade híbrida
  • Administrador de Governança de Identidade
  • Administrador de Função Privilegiada
  • Administrador de usuários
  • Administrador de Aplicações
  • Administrador de aplicativos na nuvem

Exemplos

Exemplo 1: Atribuir um utilizador a uma aplicação 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

Este comando atribui um utilizador a uma aplicação que não tem quaisquer funções.

  • -UserId parâmetro especifica o ID de um utilizador a quem está a atribuir a função da aplicação.
  • -PrincipalId parâmetro especifica o ID de um utilizador a quem está a atribuir a função da aplicação.
  • -ResourceId O parâmetro especifica o Id de um resource servicePrincipal que definiu o papel da app.
  • -AppRoleId o parâmetro especifica o Id de um appRole (definido no principal do serviço de recursos) a atribuir ao utilizador.

Exemplo 2: Atribuir a um utilizador um papel específico dentro de uma aplicação

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 utilizador a um papel de aplicação no Microsoft Entra ID.

  • -UserId parâmetro especifica o ID de um utilizador a quem está a atribuir a função da aplicação.
  • -PrincipalId parâmetro especifica o ID de um utilizador a quem está a atribuir a função da aplicação.
  • -ResourceId O parâmetro especifica o Id de um resource servicePrincipal que definiu o papel da app.
  • -AppRoleId o parâmetro especifica o Id de um appRole (definido no principal do serviço de recursos) a atribuir ao utilizador.

Parâmetros

-AppRoleId

O ID do papel da aplicação a atribuir.

Se a aplicação não tiver nenhum papel ao criar uma nova atribuição de funções, então forneça um guid vazio, ou o ID do papel para atribuir ao utilizador.

Pode obter os papéis da aplicação examinando a propriedade AppRoles do objeto da aplicação:

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

Este cmdlet devolve a lista de funções definidas numa aplicação:

AppRoles: {GUID1, GUID2}

Propriedades dos parâmetros

Tipo:System.String
Valor predefinido:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Posto:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-PrincipalId

O ID do objeto do principal ao qual o novo papel da aplicação é atribuído.

Ao atribuir um novo papel a um utilizador, forneça o ID do objeto do utilizador.

Propriedades dos parâmetros

Tipo:System.String
Valor predefinido:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Posto:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-ResourceId

O ID do objeto do Service Principal para a aplicação à qual o papel de utilizador é atribuído.

Propriedades dos parâmetros

Tipo:System.String
Valor predefinido:None
Suporta carateres universais:False
NãoMostrar:False

Conjuntos de parâmetros

(All)
Posto:Named
Obrigatório:True
Valor do pipeline:False
Valor do pipeline por nome de propriedade:False
Valor dos restantes argumentos:False

-UserId

Especifica o ID do utilizador (como UserPrincipalName ou ObjectId) no Microsoft Entra ID ao qual o novo papel da aplicação será atribuído.

Propriedades dos parâmetros

Tipo:System.String
Valor predefinido:None
Suporta carateres universais:False
NãoMostrar:False
Aliases:IdentificadorDoObjeto

Conjuntos de parâmetros

(All)
Posto:Named
Obrigatório:True
Valor do pipeline:True
Valor do pipeline por nome de propriedade:True
Valor dos restantes argumentos: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.