Gerenciar atributos de segurança personalizados para um aplicativo

Os Atributos de segurança personalizados no Microsoft Entra ID são atributos específicos da empresa (pares chave-valor) que você pode definir e atribuir aos objetos do Microsoft Entra. Por exemplo, você pode atribuir atributo de segurança personalizado para filtrar seus aplicativos ou para ajudar a determinar quem obtém acesso. Esse artigo descreve como atribuir, atualizar, listar ou remover atributos de segurança personalizados para aplicativos empresariais do Microsoft Entra.

Pré-requisitos

Para atribuir ou remover atributos de segurança personalizados de um usuário no seu locatário do Microsoft Entra, você precisa de:

• Administrador de Designação de Atributos
• Certifique-se de que você tenha atributos de segurança personalizados existentes. Para saber como criar um atributo de segurança, consulte Como adicionar ou desativar atributos de segurança personalizados no Microsoft Entra ID.

Importante

Por padrão, o Administrador Global e outras funções de administrador não têm permissão para ler, definir ou designar atributos de segurança personalizados.

Atribuir, atualizar, listar ou remover atributos personalizados de um aplicativo

Saiba como trabalhar com atributos personalizados para aplicativos no Microsoft Entra ID.

Atribuir atributos de segurança personalizados a um aplicativo

Dica

As etapas neste artigo podem variar ligeiramente com base no portal do qual você começa.

Realize as etapas a seguir para atribuir atributos de segurança personalizados por meio do centro de administração do Microsoft Entra.

1. Entre no Centro de administração do Microsoft Entra como um Administrador de Atribuição de Atributos.

2. Navegue até Identidade>Aplicativos>Aplicativos empresariais.

3. Encontre e selecione o aplicativo ao que você deseja adicionar um atributo de segurança personalizado.

4. Na seção Gerenciar, selecione Atributos de segurança personalizados.

5. Selecione Adicionar atribuição.

6. Em conjunto de atributos, selecione um conjunto de atributos na lista.

7. Em nome do atributo, selecione um atributo de segurança personalizado na lista.

8. Dependendo das propriedades do atributo de segurança personalizado selecionado, você pode inserir um único valor, selecionar um valor de uma lista predefinida ou adicionar vários valores.

   • Para atributos de segurança personalizados de forma livre, de valor único, insira um valor na caixa valores atribuídos.
   • Para valores de atributo de segurança personalizados predefinidos, selecione um valor na lista valores atribuídos.
   • Para atributos de segurança personalizados com valores múltiplos, selecione Adicionar valores para abrir o painel valores de atributo e adicionar seus valores. Após terminar de adicionar valores, selecione Concluído.

   

9. Ao terminar, selecione Salvar para atribuir os atributos de segurança personalizados ao aplicativo.

Atualizar valores de atribuição de atributo de segurança personalizados para um aplicativo

1. Entre no Centro de administração do Microsoft Entra como um Administrador de Atribuição de Atributos.

2. Navegue até Identidade>Aplicativos>Aplicativos empresariais.

3. Localize e selecione o aplicativo que tem um valor de atribuição de atributo de segurança personalizado que você deseja atualizar.

4. Na seção Gerenciar, selecione Atributos de segurança personalizados.

5. Localize o valor de atribuição de atributo de segurança personalizado que você deseja atualizar.

   Depois de atribuir um atributo de segurança personalizado a um aplicativo, você só poderá alterar o valor do atributo de segurança personalizado. Não é possível alterar outras propriedades do atributo de segurança personalizado, como o conjunto de atributos ou o nome do atributo de segurança personalizado.

6. Dependendo das propriedades do atributo de segurança personalizado selecionado, você pode atualizar um único valor, selecionar um valor de uma lista predefinida ou atualizar vários valores.

7. Quando terminar, selecione Avançar.

Filtrar aplicativos com base em atributos de segurança personalizados

Você pode filtrar a lista de atributos de segurança personalizados atribuídos a aplicativos na página Todos os aplicativos.

1. Entre no Centro de administração do Microsoft Entra como, no mínimo, um Administrador de Atribuição de Atributos.

2. Navegue até Identidade>Aplicativos>Aplicativos empresariais.

3. Selecione adicionar filtros para abrir o painel Selecionar um campo.

   Se você não vir Adicionar filtros, selecione a faixa para habilitar a visualização Enterprise pesquisa de aplicativos.

4. Para filtros, selecione Atributo de segurança personalizado.

5. Selecione o conjunto de atributos e o nome do atributo.

6. Para operador, você pode selecionar Equals (==), not Equals (! =), ou começa com.

7. Para Valor, inserir ou selecionar um valor.

8. Para aplicar o filtro, selecione Aplicar.

Remover atribuições de atributo de segurança personalizadas de aplicativos

1. Entre no centro de administração do Microsoft Entra como um Administrador de Atribuição de Atributos.

2. Navegue até Identidade>Aplicativos>Aplicativos empresariais.

3. Localize e selecione o aplicativo que tem as atribuições de atributos de segurança personalizados que você deseja remover.

4. Na seção Gerenciar, selecione Atributos de segurança personalizados (versão prévia).

5. Adicione marcas de seleção ao lado de todas as atribuições de atributo de segurança personalizadas que você deseja remover.

6. Selecione Remover a atribuição.

Azure AD PowerShell

Você pode usar o PowerShell para gerenciar atribuições de atributo de segurança personalizadas para aplicativos em sua organização do Microsoft Entra. Os comandos a seguir podem ser usados para gerenciar atribuições.

Atribuir um atributo de segurança personalizado com um valor de várias cadeias de caracteres a um aplicativo (entidade de serviço) usando o PowerShell do Azure AD

Use o comando Set-AzureADMSServicePrincipal para atribuir um atributo de segurança personalizado com um valor de cadeia de caracteres múltipla a um aplicativo (entidade de serviço).

• Conjunto de atributos: Engineering
• Atributo: Project
• Tipo de dados de atributo: coleção de cadeias de caracteres
• Valor do atributo: ("Baker","Cascade")

$attributes = @{
    Engineering = @{
        "@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
        "Project@odata.type" = "#Collection(String)"
        Project = @("Baker","Cascade")
    }
}
Set-AzureADMSServicePrincipal -Id aaaaaaaa-bbbb-cccc-1111-222222222222 -CustomSecurityAttributes $attributes

Atualizar um atributo de segurança personalizado com um valor de várias cadeias de caracteres para um aplicativo (entidade de serviço) usando o PowerShell do Azure AD

Forneça o novo conjunto de valores de atributo que você gostaria de refletir sobre o aplicativo. Neste exemplo, estamos adicionando mais um valor para o atributo de projeto.

• Conjunto de atributos: Engineering
• Atributo: Project
• Tipo de dados de atributo: coleção de cadeias de caracteres
• Valor do atributo: ("Alpine","Baker")

$attributesUpdate = @{
    Engineering = @{
        "@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
        "Project@odata.type" = "#Collection(String)"
        Project = @("Alpine","Baker")
    }
}
Set-AzureADMSServicePrincipal -Id aaaaaaaa-bbbb-cccc-1111-222222222222 -CustomSecurityAttributes $attributesUpdate 

Obter as atribuições de atributo de segurança personalizadas para um aplicativo (entidade de serviço) usando o PowerShell do Azure AD

Use o comando Get-AzureADMSServicePrincipal para obter as atribuições de atributo de segurança personalizado de um aplicativo (entidade de serviço).

Get-AzureADMSServicePrincipal -Select CustomSecurityAttributes
Get-AzureADMSServicePrincipal -Id aaaaaaaa-bbbb-cccc-1111-222222222222  -Select "CustomSecurityAttributes, Id"

Microsoft Graph/PowerShell

Você pode usar o PowerShell do Microsoft Graph para gerenciar atribuições de atributo de segurança personalizadas para aplicativos em sua organização do Microsoft Entra. Os comandos a seguir podem ser usados para gerenciar atribuições.

Atribuir um atributo de segurança personalizado com um valor de várias cadeias de caracteres a um aplicativo (entidade de serviço) usando o PowerShell do Microsoft Graph

Use o comando Update-MgServicePrincipal para atribuir um atributo de segurança personalizado com um valor de várias cadeias de caracteres a um aplicativo (entidade de serviço).

Considerando os valores

• Conjunto de atributos: Engineering
• Atributo: ProjectDate
• Tipo de dados de atributo: Cadeia de caracteres
• Valor do atributo: "2024-11-15"

#Retrieve the servicePrincipal

$ServicePrincipal = (Get-MgServicePrincipal -Filter "displayName eq 'TestApp'").Id

$customSecurityAttributes = @{
    Engineering = @{
        "@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
        "ProjectDate" ="2024-11-15"
    }
}
Update-MgServicePrincipal -ServicePrincipalId $ServicePrincipal -CustomSecurityAttributes $customSecurityAttributes

Atualizar um atributo de segurança personalizado com um valor de várias cadeias de caracteres para um aplicativo (entidade de serviço) usando o PowerShell do Microsoft Graph

Forneça o novo conjunto de valores de atributo que você gostaria de refletir sobre o aplicativo. Neste exemplo, estamos adicionando mais um valor para o atributo de projeto.

Considerando os valores

• Conjunto de atributos: Engineering
• Atributo: Project
• Tipo de dados de atributo: coleção de cadeias de caracteres
• Valor do atributo: ["Baker","Cascade"]

$customSecurityAttributes = @{
    Engineering = @{
        "@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
        "Project@odata.type" = "#Collection(String)"
        "Project" = @(
            "Baker"
            "Cascade"
        )
    }
}
Update-MgServicePrincipal -ServicePrincipalId $ServicePrincipal -CustomSecurityAttributes $customSecurityAttributes

Filtrar aplicativos com base em atributos de segurança personalizados usando o PowerShell do Microsoft Graph

Este exemplo filtra uma lista de aplicativos com uma atribuição de atributo de segurança personalizada que é igual ao valor especificado.

$appAttributes = Get-MgServicePrincipal -CountVariable CountVar -Property "id,displayName,customSecurityAttributes" -Filter "customSecurityAttributes/Engineering/Project eq 'Baker'" -ConsistencyLevel eventual
$appAttributes | select Id,DisplayName,CustomSecurityAttributes  | Format-List
$appAttributes.CustomSecurityAttributes.AdditionalProperties | Format-List

Id                       : aaaaaaaa-bbbb-cccc-1111-222222222222
DisplayName              : TestApp
CustomSecurityAttributes : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCustomSecurityAttributeValue

Key   : Engineering
Value : {[@odata.type, #microsoft.graph.customSecurityAttributeValue], [ProjectDate, 2024-11-15], [Project@odata.type, #Collection(String)], [Project, System.Object[]]}

Remover atribuições de atributo de segurança personalizadas de aplicativos usando o PowerShell do Microsoft Graph

Neste exemplo, removemos uma atribuição de atributo de segurança personalizada que dá suporte a valores únicos.

$params = @{
    "customSecurityAttributes" = @{
        "Engineering" = @{
            "@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
            "ProjectDate" = $null
        }
    }
}
Invoke-MgGraphRequest -Method PATCH -Uri "https://graph.microsoft.com/v1.0/servicePrincipals/$ServicePrincipal" -Body $params

Neste exemplo, removemos uma atribuição de atributo de segurança personalizada que dá suporte a vários valores.

$customSecurityAttributes = @{
    Engineering = @{
        "@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
        "Project" = @()
    }
}
Update-MgServicePrincipal -ServicePrincipalId $ServicePrincipal -CustomSecurityAttributes $customSecurityAttributes

API do Microsoft Graph

Você pode usar a API do Microsoft Graph para gerenciar atribuições de atributo de segurança personalizadas para aplicativos em sua organização do Microsoft Entra. Faça as chamadas à API a seguir para gerenciar atribuições.

Para ver outros exemplos semelhantes da API do Microsoft Graph para usuários, confira Atribuir, atualizar, listar ou remover atributos de segurança personalizados de um usuário e Exemplos: atribuir, atualizar, listar ou remover atributos de segurança personalizados usando a API do Microsoft Graph.

Atribuir um atributo de segurança personalizado com um valor de várias cadeias de caracteres a um aplicativo (entidade de serviço) usando a API do Microsoft Graph

Use a API Update servicePrincipal para atribuir um atributo de segurança personalizado com um valor de cadeia de caracteres a um aplicativo.

Considerando os valores

• Conjunto de atributos: Engineering
• Atributo: Project
• Tipo de dados de atributo: Cadeia de caracteres
• Valor do atributo: "Baker"

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "Project@odata.type":"#Collection(String)",
            "Project": "Baker"
        }
    }
}

Atualizar um atributo de segurança personalizado com um valor de várias cadeias de caracteres para um aplicativo (entidade de serviço) usando a API do Microsoft Graph

Forneça o novo conjunto de valores de atributo que você gostaria de refletir sobre o aplicativo. Neste exemplo, estamos adicionando mais um valor para o atributo de projeto.

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "Project@odata.type":"#Collection(String)",
            "Project":["Baker","Cascade"]
        }
    }
}

Filtrar aplicativos com base em atributos de segurança personalizados usando a API do Microsoft Graph

Este exemplo filtra uma lista de aplicativos com uma atribuição de atributo de segurança personalizada que é igual ao valor especificado. O valor do filtro diferencia maiúsculas de minúsculas. Você precisa adicionar ConsistencyLevel=eventual à solicitação ou ao cabeçalho. Você também deve incluir $count=true para garantir que a solicitação seja roteada corretamente.

GET https://graph.microsoft.com/v1.0/servicePrincipals?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Engineering/Project eq 'Baker'
ConsistencyLevel: eventual

Remover atribuições de atributo de segurança personalizadas de aplicativos usando a API do Microsoft Graph

Neste exemplo, removemos uma atribuição de atributo de segurança personalizada que dá suporte a vários valores.

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "Project":[]
        }
    }
}

Próximas etapas

• Adicionar ou desativar as definições dos atributos de segurança personalizados no Microsoft Entra ID
• Atribuir, atualizar, listar ou remover os atributos de segurança personalizados para um usuário
• Solucionar problemas dos atributos de segurança personalizados no Microsoft Entra ID