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

Artigo
11/03/2024

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, 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 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.

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 conta, é possível criar uma conta gratuita.
Uma das seguintes funções: 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.
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 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 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

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.
```
$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.
```
$user = Get-AzureADUser -ObjectId "$username"
$sp = Get-AzureADServicePrincipal -Filter "displayName eq '$app_name'"
```
Execute o comando a seguir para localizar as funções de aplicativo expostas pela entidade de serviço
```
$appRoles = $sp.AppRoles
# Display the app roles
$appRoles | ForEach-Object {
    Write-Output "AppRole: $($_.DisplayName) - ID: $($_.Id)"
```
Observação

A ID do AppRole padrão é 00000000-0000-0000-0000-000000000000. Essa função é atribuída quando nenhum AppRole específico é definido para uma entidade de serviço.
Atribua o nome do AppRole à variável $app_role_name. Neste exemplo, queremos atribuir a Brenda Fernandes a função de Analista (acesso limitado).
```
$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.

New-AzureADUserAppRoleAssignment -ObjectId $user.ObjectId -PrincipalId $user.ObjectId -ResourceId $sp.ObjectId -Id $appRole.Id

Para atribuir um grupo a um aplicativo empresarial, substitua 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.

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

Abra um prompt de comando elevado do Windows PowerShell.

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 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 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, the service principal and appRole.
$params = @{
"PrincipalId" =$userId
"ResourceId" =$sp.Id
"AppRoleId" =($sp.AppRoles | Where-Object { $_.DisplayName -eq $app_role_name }).Id
}
#Assign the user to the AppRole
New-MgUserAppRoleAssignment -UserId $userId -BodyParameter $params |
    Format-List Id, AppRoleId, CreationTime, PrincipalDisplayName,
    PrincipalId, PrincipalType, ResourceDisplayName, ResourceId

Exemplo

Este exemplo atribui a usuária Brenda Fernandes ao aplicativo Microsoft Workplace Analytics usando o Microsoft Graph PowerShell.

No PowerShell, atribua os valores correspondentes às variáveis $userId, $app_name e $app_role_name.

# Assign the values to the variables  
$userId = "<Britta Simon's user ID>"  
$app_name = "Workplace Analytics"

Neste exemplo, não sabemos o nome exato da função de aplicativo que desejamos atribuir à Brenda Fernandes. Execute o comando a seguir para obter a entidade de serviço ($sp) usando o nome de exibição da entidade de serviço.
```
# Get the service principal for the app  
$sp = Get-MgServicePrincipal -Filter "displayName eq '$app_name'"  
```
Execute o comando a seguir para localizar as funções de aplicativo expostas pela entidade de serviço.
```
# Get the app roles exposed by the service principal  
$appRoles = $sp.AppRoles  
# Display the app roles  
$appRoles | ForEach-Object {  
    Write-Output "AppRole: $($_.DisplayName) - ID: $($_.Id)"  
}  
```
Observação

A ID do AppRole padrão é 00000000-0000-0000-0000-000000000000. Essa função é atribuída quando nenhum AppRole específico é definido para uma entidade de serviço.

Atribua o nome de função à variável $app_role_name. Neste exemplo, queremos atribuir a Brenda Fernandes a função de Analista (acesso limitado).

# Assign the values to the variables  
$app_role_name = "Analyst (Limited access)"  
$appRoleId = ($sp.AppRoles | Where-Object { $_.DisplayName -eq $app_role_name }).Id

Prepare os parâmetros e execute o seguinte comando para atribuir o usuário à função de aplicativo.

# Prepare parameters for the role assignment  
$params = @{  
    "PrincipalId" = $userId  
    "ResourceId" = $sp.Id  
    "AppRoleId" = $appRoleId  
}  

# Assign the user to the app role  
New-MgUserAppRoleAssignment -UserId $userId -BodyParameter $params |   
    Format-List Id, AppRoleId, CreationTime, PrincipalDisplayName,   
    PrincipalId, PrincipalType, ResourceDisplayName, ResourceId

Para atribuir um grupo a um aplicativo empresarial, substitua Get-MgUser por Get-MgGroup e New-MgUserAppRoleAssignment por New-MgGroupAppRoleAssignment.

Para saber mais sobre como atribuir um grupo a uma função de aplicativo, confira a documentação sobre New-MgGroupAppRoleAssignment.

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.

Obter o usuário e a entidade de serviço

$user = Get-MgUser -UserId <userid>
$sp = Get-MgServicePrincipal -ServicePrincipalId <ServicePrincipalId>

Obter a ID da atribuição de função

$assignments = Get-MgServicePrincipalAppRoleAssignedTo -ServicePrincipalId $sp.Id | Where {$_.PrincipalDisplayName -eq $user.DisplayName}

Executar o comando a seguir para mostrar a lista de usuários atribuídos ao aplicativo
```
$assignments | Select *
```

Execute o seguinte comando para remover a atribuição AppRole.

Remove-MgServicePrincipalAppRoleAssignedTo -AppRoleAssignmentId  '<AppRoleAssignment-id>' -ServicePrincipalId $sp.Id

Remover todos os usuários e grupos atribuídos ao aplicativo usando o PowerShell do Microsoft Graph

Execute o comando 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 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.Alle 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. Filtrar 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
- ID do AppRole 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.
Observação

A ID do AppRole padrão é 00000000-0000-0000-0000-000000000000. Essa função é atribuída quando nenhum AppRole específico é definido para uma entidade de serviço.
Obtenha o usuário filtrando pelo nome principal de segurança. Registre a ID do 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 todos os usuários e grupos no aplicativo, execute a consulta a seguir.

Obtenha o aplicativo empresarial. Filtrar por displayName.

GET https://graph.microsoft.com/v1.0/servicePrincipals?$filter=displayName eq '{appDisplayName}'

Obtenha a lista de appRoleAssignments para o 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}

O Microsoft Graph Explorer não dá suporte diretamente à exclusão em lote de atribuições de função de aplicativo. Você precisa excluir cada atribuição individualmente. No entanto, você pode automatizar esse processo usando o Microsoft Graph PowerShell para iterar e remover cada atribuição

Compartilhar via

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

Pré-requisitos

Atribuir usuários e grupos a um aplicativo usando o centro de administração do Microsoft Entra

Cancelar atribuição de usuários e grupos em um aplicativo

Atribuir usuários e grupos a um aplicativo usando o PowerShell do Azure AD

Exemplo

Cancelar a atribuição de usuários e grupos de um aplicativo usando o PowerShell do Azure AD

Remover todos os usuários atribuídos ao aplicativo usando o PowerShell do Azure AD

Atribuir usuários e grupos a um aplicativo usando o PowerShell do Microsoft Graph

Exemplo

Cancelar a atribuição de usuários e grupos de um aplicativo usando o PowerShell do Microsoft Graph

Remover todos os usuários e grupos atribuídos ao aplicativo usando o PowerShell do Microsoft Graph

Atribuir usuários e grupos a um aplicativo usando uma API do Microsoft Graph

Cancelar atribuição de usuários e grupos de um aplicativo usando a API do Microsoft Graph

Próximas etapas

Comentários

Recursos adicionais