Gerenciar a atribuição de usuários e grupos a um aplicativo

Artigo
12/22/2023

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, você também pode 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 e grupos do Microsoft 365 cuja configuração SecurityEnabled é definida como somente True. No momento, não há suporte para associações de grupos aninhados. Para ver mais 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.

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 conta, é possível criar uma conta gratuita.
Uma das seguintes funções: administrador global, administrador de aplicativos 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 ver mais 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 Administrador de Aplicativo 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 pesquisa.
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 ou contosoteam1@contoso.com.
Escolha 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 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 saber mais 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 elevado do Windows PowerShell.
Execute Connect-AzureAD e entre como, pelo menos, um Administrador de Aplicativos de Nuvem.

Use o script a seguir 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 a seguir 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 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 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 a seguir 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 a seguir 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 em 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.

Será necessário 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: o ID do servicePrincipal do recurso que definiu 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 expor as funções, o usuário receberá a função de acesso padrão.
Obtenha o usuário filtrando pelo nome UPN. Registre a ID do objeto do usuário.
```
GET https://graph.microsoft.com/v1.0/users/{userPrincipalName}
```

Atribuir o usuário ao aplicativo.

POST https://graph.microsoft.com/v1.0/servicePrincipals/{resource-servicePrincipal-id}/appRoleAssignedTo

{
"principalId": "33ad69f9-da99-4bed-acd0-3f24235cb296",
"resourceId": "9028d19c-26a9-4809-8e3f-20ff73e2d75e",
"appRoleId": "ef7437e6-4f94-4a0a-a110-a439eb2aa8f7"
}

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}