Gerenciar a atribuição de usuários e grupos a um aplicativo
Este artigo mostra como atribuir usuários ou grupos a um aplicativo empresarial no Microsoft Entra ID usando o PowerShell. Quando você atribuir um usuário a um aplicativo, esse aplicativo será exibido no portal Meus Aplicativos do usuário para facilitar o acesso. Se o aplicativo expõe funções do aplicativo, também é possível atribuir uma função de aplicativo específica ao usuário.
Quando você atribuir um grupo a um aplicativo, somente os usuários no grupo terão acesso. A atribuição não se propaga para grupos aninhados.
A atribuição baseada em grupo requer Microsoft Entra ID P1 ou P2. A atribuição baseada em grupo tem suporte para grupos de segurança, grupos do Microsoft 365 e grupos de distribuição cuja configuração SecurityEnabled
está definida apenas como True
. No momento, não há suporte para associações de grupos aninhados. Para obter mais informações sobre os requisitos de licenciamento dos recursos discutidos neste artigo, confira a página de preços do Microsoft Entra.
Para maior controle, determinados tipos de aplicativos empresariais podem ser configurados para exigir a atribuição de usuário. Para obter mais informações sobre a necessidade de atribuição de usuário para um aplicativo, confira Gerenciar o acesso a um aplicativo.
Observação
Os aplicativos que exigem que os usuários sejam atribuídos ao aplicativo devem ter suas permissões consentidas por um administrador, mesmo que as políticas de consentimento do usuário para o seu diretório permitam que um usuário consinta em seu próprio nome.
Pré-requisitos
Para atribuir usuários a um aplicativo empresarial, é necessário:
- Uma conta do Microsoft Entra com uma assinatura ativa. Se você ainda não tem uma, é possível criar uma conta gratuita.
- Uma das seguintes funções: Administrador de Aplicativo de Nuvem, Administrador de Aplicativos ou proprietário da entidade de serviço.
- Microsoft Entra ID P1 ou P2 para atribuição baseada em grupo. Para obter mais informações sobre os requisitos de licenciamento dos recursos discutidos neste artigo, confira a página de preços do Microsoft Entra.
Dica
As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.
Atribuir usuários e grupos a um aplicativo usando o centro de administração do Microsoft Entra
Para atribuir uma conta de usuário ou de grupo a um aplicativo empresarial:
Entre no Centro de administração do Microsoft Entra como, pelo menos, um Administrador de aplicativos de nuvem.
Navegue até Identidade>Aplicativos>Aplicativos Empresariais>Todos os aplicativos.
Insira o nome do aplicativo existente na caixa de pesquisa e, em seguida, selecione o aplicativo nos resultados da busca.
Selecione Usuários e grupos e selecione Adicionar usuário/grupo.
No painel Adicionar Atribuição, selecione Nenhum Selecionado em Usuários e grupos.
Procure e selecione o usuário ou grupo que você deseja atribuir ao aplicativo. Por exemplo,
contosouser1@contoso.com
oucontosoteam1@contoso.com
.Selecione Selecionar.
Em Selecione uma função, selecione a função que você quer atribuir ao usuário ou grupo. Se você ainda não definiu nenhuma função, a função padrão será Acesso padrão.
No painel Adicionar atribuição, selecione Atribuir para atribuir o usuário ou grupo ao aplicativo.
Cancelar atribuição de usuários e grupos em um aplicativo
- Siga as etapas na seção Atribuir usuários e grupos a um aplicativo para navegar até o painel Usuários e grupos.
- Procure e selecione o usuário ou grupo que você quer atribuir ao aplicativo.
- Selecione Remover para cancelar a atribuição do usuário ou grupo do aplicativo.
Atribuir usuários e grupos a um aplicativo usando o PowerShell do Azure AD
Abra um prompt de comando elevado do Windows PowerShell.
Execute
Connect-AzureAD
e entre como, pelo menos, um Administrador de aplicativos de nuvem.Use o script abaixo para atribuir um usuário e uma função a um aplicativo:
# Assign the values to the variables $username = "<Your user's UPN>" $app_name = "<Your App's display name>" $app_role_name = "<App role display name>" # Get the user to assign, and the service principal for the app to assign to $user = Get-AzureADUser -ObjectId "$username" $sp = Get-AzureADServicePrincipal -Filter "displayName eq '$app_name'" $appRole = $sp.AppRoles | Where-Object { $_.DisplayName -eq $app_role_name } # Assign the user to the app role New-AzureADUserAppRoleAssignment -ObjectId $user.ObjectId -PrincipalId $user.ObjectId -ResourceId $sp.ObjectId -Id $appRole.Id
Para atribuir um grupo a um aplicativo empresarial, é preciso substituir Get-AzureADUser
por Get-AzureADGroup
e New-AzureADUserAppRoleAssignment
por New-AzureADGroupAppRoleAssignment
.
Para obter mais informações sobre como atribuir um grupo a uma função de aplicativo, confira a documentação sobre New-AzureADGroupAppRoleAssignment.
Exemplo
Este exemplo atribui a usuária Brenda Fernandes ao aplicativo Microsoft Workplace Analytics usando o PowerShell.
No PowerShell, atribua os valores correspondentes às variáveis $username, app_name $ e $app_role_name.
# Assign the values to the variables $username = "britta.simon@contoso.com" $app_name = "Workplace Analytics"
Neste exemplo, não sabemos o nome exato da função de aplicativo que desejamos atribuir à Brenda Fernandes. Execute os comandos a seguir para obter o usuário ($user) e a entidade de serviço ($sp) usando o nome UPN do usuário e o nome de exibição da entidade de serviço.
# Get the user to assign, and the service principal for the app to assign to $user = Get-AzureADUser -ObjectId "$username" $sp = Get-AzureADServicePrincipal -Filter "displayName eq '$app_name'"
Execute o comando
$sp.AppRoles
para exibir as funções disponíveis para o aplicativo Workplace Analytics. Neste exemplo, queremos atribuir a Brenda Fernandes a função de Analista (acesso limitado).Atribua o nome de função à variável
$app_role_name
.# Assign the values to the variables $app_role_name = "Analyst (Limited access)" $appRole = $sp.AppRoles | Where-Object { $_.DisplayName -eq $app_role_name }
Execute o seguinte comando para atribuir o usuário à função de aplicativo:
# Assign the user to the app role New-AzureADUserAppRoleAssignment -ObjectId $user.ObjectId -PrincipalId $user.ObjectId -ResourceId $sp.ObjectId -Id $appRole.Id
Cancelar a atribuição de usuários e grupos de um aplicativo usando o PowerShell do Azure AD
Abra um prompt de comando elevado do Windows PowerShell.
Execute
Connect-AzureAD
e entre como, pelo menos, um Administrador de aplicativos de nuvem.Use o script abaixo para remover um usuário e uma função de um aplicativo.
# Store the proper parameters $user = get-azureaduser -ObjectId <objectId> $spo = Get-AzureADServicePrincipal -ObjectId <objectId> #Get the ID of role assignment $assignments = Get-AzureADServiceAppRoleAssignment -ObjectId $spo.ObjectId | Where {$_.PrincipalDisplayName -eq $user.DisplayName} #if you run the following, it will show you what is assigned what $assignments | Select * #To remove the App role assignment run the following command. Remove-AzureADServiceAppRoleAssignment -ObjectId $spo.ObjectId -AppRoleAssignmentId $assignments[assignment number].ObjectId
Remover todos os usuários atribuídos ao aplicativo usando o PowerShell do Azure AD
Use o script abaixo para remover todos os usuários e grupos atribuídos ao aplicativo.
#Retrieve the service principal object ID.
$app_name = "<Your App's display name>"
$sp = Get-AzureADServicePrincipal -Filter "displayName eq '$app_name'"
$sp.ObjectId
# Get Service Principal using objectId
$sp = Get-AzureADServicePrincipal -ObjectId "<ServicePrincipal objectID>"
# Get Azure AD App role assignments using objectId of the Service Principal
$assignments = Get-AzureADServiceAppRoleAssignment -ObjectId $sp.ObjectId -All $true
# Remove all users and groups assigned to the application
$assignments | ForEach-Object {
if ($_.PrincipalType -eq "User") {
Remove-AzureADUserAppRoleAssignment -ObjectId $_.PrincipalId -AppRoleAssignmentId $_.ObjectId
} elseif ($_.PrincipalType -eq "Group") {
Remove-AzureADGroupAppRoleAssignment -ObjectId $_.PrincipalId -AppRoleAssignmentId $_.ObjectId
}
}
Atribuir usuários e grupos a um aplicativo usando o PowerShell do Microsoft Graph
- Abra um prompt de comando elevado do Windows PowerShell.
- Execute
Connect-MgGraph -Scopes "Application.ReadWrite.All", "Directory.ReadWrite.All", "AppRoleAssignment.ReadWrite.All"
e entre como, pelo menos, um Administrador de aplicativos de nuvem. - Use o script abaixo para atribuir um usuário e uma função a um aplicativo:
# Assign the values to the variables
$userId = "<Your user's ID>"
$app_name = "<Your App's display name>"
$app_role_name = "<App role display name>"
$sp = Get-MgServicePrincipal -Filter "displayName eq '$app_name'"
# Get the user to assign, and the service principal for the app to assign to
$params = @{
"PrincipalId" =$userId
"ResourceId" =$sp.Id
"AppRoleId" =($sp.AppRoles | Where-Object { $_.DisplayName -eq $app_role_name }).Id
}
# Assign the user to the app role
New-MgUserAppRoleAssignment -UserId $userId -BodyParameter $params |
Format-List Id, AppRoleId, CreationTime, PrincipalDisplayName,
PrincipalId, PrincipalType, ResourceDisplayName, ResourceId
Cancelar a atribuição de usuários e grupos de um aplicativo usando o PowerShell do Microsoft Graph
- Abra um prompt de comando elevado do Windows PowerShell.
- Execute
Connect-MgGraph -Scopes "Application.ReadWrite.All", "Directory.ReadWrite.All", "AppRoleAssignment.ReadWrite.All"
e entre como, pelo menos, um Administrador de aplicativos de nuvem. Use o script abaixo para remover um usuário e uma função de um aplicativo.
# Get the user and the service principal
$user = Get-MgUser -UserId <userid>
$spo = Get-MgServicePrincipal -ServicePrincipalId <ServicePrincipalId>
# Get the Id of the role assignment
$assignments = Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $spo.Id | Where {$_.PrincipalDisplayName -eq $user.DisplayName}
# if you run the following, it will show you the list of users assigned to the application
$assignments | Select *
# To remove the App role assignment run the following command.
Remove-MgServicePrincipalAppRoleAssignedTo -AppRoleAssignmentId '<AppRoleAssignment-id>' -ServicePrincipalId $spo.Id
Remover todos os usuários e grupos atribuídos ao aplicativo usando o PowerShell do Microsoft Graph
Use o script abaixo para remover todos os usuários e grupos atribuídos ao aplicativo.
$assignments | ForEach-Object {
if ($_.PrincipalType -in ("user", "Group")) {
Remove-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $Sp.Id -AppRoleAssignmentId $_.Id }
}
Atribuir usuários e grupos a um aplicativo usando uma API do Microsoft Graph
Para atribuir usuários e grupos a um aplicativo, entre no Graph Explorer como, pelo menos, um Administrador de aplicativos de nuvem.
Você precisa consentir com as seguintes permissões:
Application.ReadWrite.All
,Directory.ReadWrite.All
,AppRoleAssignment.ReadWrite.All
.Para conceder uma atribuição de função de aplicativo, você precisa de três identificadores:
principalId
: a ID do usuário ou do grupo ao qual você está atribuindo a função de aplicativo.resourceId
: a ID do servicePrincipal do recurso que define a função do aplicativo.appRoleId
: a ID do appRole (definida na entidade de serviço do recurso) a ser atribuída a um usuário ou grupo.
Obtenha o aplicativo empresarial. Filtre por DisplayName.
GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq '{appDisplayName}'
Registre os seguintes valores do corpo da resposta:
- ID do objeto do aplicativo empresarial
- appRoleId que você atribui ao usuário. Se o aplicativo não expuser as funções, o usuário receberá a função de acesso padrão.
Obtenha o usuário filtrando pelo nome principal de segurança. Registre a ID de objeto do usuário.
GET https://graph.microsoft.com/v1.0/users/{userPrincipalName}
Atribua o usuário ao aplicativo.
POST https://graph.microsoft.com/v1.0/servicePrincipals/{resource-servicePrincipal-id}/appRoleAssignedTo { "principalId": "aaaaaaaa-bbbb-cccc-1111-222222222222", "resourceId": "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1", "appRoleId": "00000000-0000-0000-0000-000000000000" }
No exemplo, resource-servicePrincipal-id e resourceId representam o aplicativo empresarial.
Cancelar atribuição de usuários e grupos de um aplicativo usando a API do Microsoft Graph
Para cancelar a atribuição de usuários e grupos no aplicativo, execute a consulta a seguir.
Obtenha o aplicativo empresarial. Filtre por displayName.
GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq '{appDisplayName}'
Obtenha a lista de appRoleAssignments do aplicativo.
GET https://graph.microsoft.com/v1.0/servicePrincipals/{id}/appRoleAssignedTo
Remova o appRoleAssignments especificando a ID do appRoleAssignment.
DELETE https://graph.microsoft.com/v1.0/servicePrincipals/{resource-servicePrincipal-id}/appRoleAssignedTo/{appRoleAssignment-id}