Partilhar via


Gerenciar atribuições de atributo de segurança personalizadas

Atributos de segurança personalizados em Microsoft Entra ID são atributos específicos do negócio (pares de valor-chave) que você pode definir e atribuir a objetos Microsoft Entra. Esses atributos podem ser usados para armazenar informações, categorizar objetos ou impor controle de acesso refinado sobre recursos específicos do Azure por meio do Azure Attribute-Based Access Control (Azure ABAC).

Os atributos de segurança personalizados têm suporte apenas para usuários e entidades de serviço. Este artigo fornece exemplos de como atribuir, atualizar, listar ou remover diferentes tipos de atributos de segurança personalizados para usuários e aplicativos usando o Microsoft Graph.

Pré-requisitos

Atribuir atributos de segurança personalizados

Exemplo 1: atribuir um atributo de segurança personalizado com um valor de cadeia de caracteres a um usuário

O exemplo a seguir mostra como usar a API do usuário update para atribuir um atributo de segurança personalizado com um valor de cadeia de caracteres a um usuário.

  • Conjunto de atributos: Engineering
  • Atributo: ProjectDate
  • Tipo de dados de atributo: cadeia de caracteres
  • Valor do atributo: "2022-10-01"

Solicitação

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

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "ProjectDate":"2022-10-01"
        }
    }
}

Resposta

HTTP/1.1 204 No Content

Exemplo 2: atribuir um atributo de segurança personalizado com um valor de cadeia de caracteres a um principal de serviço

O exemplo a seguir mostra como usar a API do Update servicePrincipal para atribuir um atributo de segurança personalizado com um valor de cadeia de caracteres a uma entidade de serviço.

  • Conjunto de atributos: Engineering
  • Atributo: ProjectDate
  • Tipo de dados de atributo: cadeia de caracteres
  • Valor do atributo: "2022-10-01"

Solicitação

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

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "ProjectDate":"2022-10-01"
        }
    }
}

Resposta

HTTP/1.1 204 No Content

Exemplo 3: atribuir um atributo de segurança personalizado com um valor de várias cadeias de caracteres a um usuário

O exemplo a seguir mostra como usar a API do usuário update para atribuir um atributo de segurança personalizado com um valor de várias cadeias de caracteres a um usuário.

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

Solicitação

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

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

Resposta

HTTP/1.1 204 No Content

Exemplo 4: atribuir um atributo de segurança personalizado com um valor inteiro a um usuário

O exemplo a seguir mostra como usar a API do usuário atualizar para atribuir um atributo de segurança personalizado com um valor inteiro a um usuário.

  • Conjunto de atributos: Engineering
  • Atributo: NumVendors
  • Tipo de dados de atributo: Inteiro
  • Valor do atributo: 4

Solicitação

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

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "NumVendors@odata.type":"#Int32",
            "NumVendors":4
        }
    }
}

Resposta

HTTP/1.1 204 No Content

Exemplo 5: atribuir um atributo de segurança personalizado com um valor multi-inteiro a um usuário

O exemplo a seguir mostra como usar a API do usuário update para atribuir um atributo de segurança personalizado com um valor multi-inteiro a um usuário.

  • Conjunto de atributos: Engineering
  • Atributo: CostCenter
  • Tipo de dados de atributo: Coleção de inteiros
  • Valor do atributo: [1001,1003]

Solicitação

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

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "CostCenter@odata.type":"#Collection(Int32)",
            "CostCenter":[1001,1003]
        }
    }
}

Resposta

HTTP/1.1 204 No Content

Exemplo 6: atribuir um atributo de segurança personalizado com um valor booliano a um usuário

O exemplo a seguir mostra como usar a API do usuário atualizar para atribuir um atributo de segurança personalizado com um valor booliano a um usuário.

  • Conjunto de atributos: Engineering
  • Atributo: Certification
  • Tipo de dados de atributo: Booliano
  • Valor do atributo: true

Solicitação

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

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "Certification":true
        }
    }
}

Resposta

HTTP/1.1 204 No Content

Atualizar atribuições de atributo de segurança personalizadas

Exemplo 1: atualizar uma atribuição de atributo de segurança personalizada com um valor inteiro para um usuário

O exemplo a seguir mostra como usar a API do usuário update para atualizar uma atribuição de atributo de segurança personalizada com um valor inteiro para um usuário.

  • Conjunto de atributos: Engineering
  • Atributo: NumVendors
  • Tipo de dados de atributo: Inteiro
  • Valor do atributo: 8

Solicitação

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

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "NumVendors@odata.type":"#Int32",
            "NumVendors":8
        }
    }
}

Resposta

HTTP/1.1 204 No Content

Exemplo 2: atualizar uma atribuição de atributo de segurança personalizada com um valor booliano para um usuário

O exemplo a seguir mostra como usar a API do usuário atualizar para atualizar uma atribuição de atributo de segurança personalizada com um valor booliano para um usuário.

  • Conjunto de atributos: Engineering
  • Atributo: Certification
  • Tipo de dados de atributo: Booliano
  • Valor do atributo: false

Solicitação

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

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "Certification":false
        }
    }
}

Resposta

HTTP/1.1 204 No Content

Listar atribuições de atributo de segurança personalizadas

Exemplo 1: obter as atribuições de atributo de segurança personalizadas para um usuário

O exemplo a seguir mostra como usar a API Obter usuário para obter as atribuições de atributo de segurança personalizadas para um usuário.

Atributo nº 1

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

Atributo nº 2

  • Conjunto de atributos: Engineering
  • Atributo: CostCenter
  • Tipo de dados de atributo: Coleção de inteiros
  • Valor do atributo: [1001]

Atributo nº 3

  • Conjunto de atributos: Engineering
  • Atributo: Certification
  • Tipo de dados de atributo: Booliano
  • Valor do atributo: true

Atributo nº 4

  • Conjunto de atributos: Marketing
  • Atributo: EmployeeId
  • Tipo de dados de atributo: cadeia de caracteres
  • Valor do atributo: "QN26904"

Solicitação

GET https://graph.microsoft.com/v1.0/users/{id}?$select=customSecurityAttributes

Resposta

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": {
        "Marketing": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "EmployeeId": "QN26904"
        },
        "Engineering": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "Project@odata.type": "#Collection(String)",
            "Project": [
                "Baker",
                "Cascade"
            ],
            "CostCenter@odata.type": "#Collection(Int32)",
            "CostCenter": [
                1001
            ],
            "Certification": true
        }
    }
}

Se não houver atributos de segurança personalizados atribuídos ao usuário ou se a entidade de chamada não tiver acesso, a seguinte será a resposta:

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}

Exemplo 2: Listar todos os usuários com uma atribuição de atributo de segurança personalizada igual a um valor

O exemplo a seguir mostra como usar a API de usuários de lista para listar todos os usuários com uma atribuição de atributo de segurança personalizada que é igual a um valor. O exemplo recupera usuários com um atributo de segurança personalizado chamado AppCountry com um valor igual a Canada. O valor do filtro é sensível a maiúsculas de minúsculas. Você deve adicionar ConsistencyLevel=eventual a solicitação ou o cabeçalho. Você também deve incluir $count=true para garantir que a solicitação seja roteada corretamente.

Usuário nº 1

  • Conjunto de atributos: Marketing
  • Atributo: AppCountry
  • Tipo de dados de atributo: Coleção de cadeias de caracteres
  • Valor do atributo: ["India","Canada"]

Usuário nº 2

  • Conjunto de atributos: Marketing
  • Atributo: AppCountry
  • Tipo de dados de atributo: Coleção de cadeias de caracteres
  • Valor do atributo: ["Canada","Mexico"]

Solicitação

GET https://graph.microsoft.com/v1.0/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry eq 'Canada'
ConsistencyLevel: eventual

Resposta

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,customSecurityAttributes)",
    "@odata.count": 2,
    "value": [
        {
            "id": "dbaf3778-4f81-4ea0-ac1c-502a293c12ac",
            "displayName": "Jiya",
            "customSecurityAttributes": {
                "Engineering": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "Datacenter@odata.type": "#Collection(String)",
                    "Datacenter": [
                        "India"
                    ]
                },
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "India",
                        "Canada"
                    ],
                    "EmployeeId": "KX19476"
                }
            }
        },
        {
            "id": "6bac433c-48c6-4213-a316-1428de32701b",
            "displayName": "Jana",
            "customSecurityAttributes": {
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "Canada",
                        "Mexico"
                    ],
                    "EmployeeId": "GS46982"
                }
            }
        }
    ]
}

Exemplo 3: listar todos os usuários com uma atribuição de atributo de segurança personalizada que começa com um valor

O exemplo a seguir mostra como usar a API de usuários de lista para listar todos os usuários com uma atribuição de atributo de segurança personalizada que começa com um valor. O exemplo recupera usuários com um atributo de segurança personalizado chamado EmployeeId com um valor que começa com GS. O valor do filtro é sensível a maiúsculas de minúsculas. Você deve adicionar ConsistencyLevel=eventual a solicitação ou o cabeçalho. Você também deve incluir $count=true para garantir que a solicitação seja roteada corretamente.

Usuário nº 1

  • Conjunto de atributos: Marketing
  • Atributo: EmployeeId
  • Tipo de dados de atributo: cadeia de caracteres
  • Valor do atributo: "KX19476"

Usuário nº 2

  • Conjunto de atributos: Marketing
  • Atributo: EmployeeId
  • Tipo de dados de atributo: cadeia de caracteres
  • Valor do atributo: "GS46982"

Solicitação

GET https://graph.microsoft.com/v1.0/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=startsWith(customSecurityAttributes/Marketing/EmployeeId,'GS')
ConsistencyLevel: eventual

Resposta

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,customSecurityAttributes)",
    "@odata.count": 1,
    "value": [
        {
            "id": "6bac433c-48c6-4213-a316-1428de32701b",
            "displayName": "Jana",
            "customSecurityAttributes": {
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "Canada",
                        "Mexico"
                    ],
                    "EmployeeId": "GS46982"
                }
            }
        }
    ]
}

Exemplo 4: Listar todos os usuários com uma atribuição de atributo de segurança personalizada que não seja igual a um valor

O exemplo a seguir mostra como usar a API de usuários de lista para listar todos os usuários com uma atribuição de atributo de segurança personalizada que não é igual a um valor. O exemplo recupera usuários com um atributo de segurança personalizado nomeado AppCountry com um valor que não é igual Canadaa . O valor do filtro é sensível a maiúsculas de minúsculas. Você deve adicionar ConsistencyLevel=eventual a solicitação ou o cabeçalho. Você também deve incluir $count=true para garantir que a solicitação seja roteada corretamente.

Usuário nº 1

  • Conjunto de atributos: Marketing
  • Atributo: AppCountry
  • Tipo de dados de atributo: Coleção de cadeias de caracteres
  • Valor do atributo: ["France"]

Todos os outros usuários

  • AppCountry atributo não adicionado

Solicitação

GET https://graph.microsoft.com/v1.0/users?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Marketing/AppCountry ne 'Canada'
ConsistencyLevel: eventual

Resposta

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,customSecurityAttributes)",
    "@odata.count": 32,
    "value": [
        {
            "id": "c4f9ecd3-d3c1-4544-b49a-bc9bb62beb67",
            "displayName": "Alain",
            "customSecurityAttributes": null
        },
        {
            "id": "de4f1218-b0fb-4449-b3a0-1e1dd193e6e7",
            "displayName": "Joe",
            "customSecurityAttributes": {
                "Engineering": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "Project3@odata.type": "#Collection(String)",
                    "Project3": [
                        "Baker",
                        "Cascade"
                    ],
                    "CostCenter@odata.type": "#Collection(Int32)",
                    "CostCenter": [
                        1001
                    ],
                    "Certification": true
                },
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "EmployeeId": "QN26904"
                }
            }
        },
        {
            "id": "f24d1474-ded5-432d-be08-8abd39921aac",
            "displayName": "Isabella",
            "customSecurityAttributes": {
                "Marketing": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "AppCountry@odata.type": "#Collection(String)",
                    "AppCountry": [
                        "France"
                    ]
                }
            }
        },
        {
            "id": "849e81fe-1109-4d57-9536-a25d537eec1f",
            "displayName": "Dara",
            "customSecurityAttributes": {
                "Engineering": {
                    "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
                    "ProjectDate": "2023-04-12"
                }
            }
        },
        {
            "id": "42c88239-db99-45f0-85af-cbb6c8acb2a3",
            "displayName": "Chandra",
            "customSecurityAttributes": null
        }
    ]
}

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

Exemplo 1: remover uma atribuição de atributo de segurança personalizada com valor único de um usuário

O exemplo a seguir mostra como usar a API do usuário update para remover uma atribuição de atributo de segurança personalizada que dá suporte a um único valor de um usuário.

  • Conjunto de atributos: Engineering
  • Atributo: ProjectDate
  • Valor do atributo: null

Solicitação

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

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "ProjectDate":null
        }
    }
}

Resposta

HTTP/1.1 204 No Content

Exemplo 2: remover uma atribuição de atributo de segurança personalizada de vários valores de um usuário

O exemplo a seguir mostra como usar a API do usuário update para remover uma atribuição de atributo de segurança personalizada que dá suporte a vários valores de um usuário.

  • Conjunto de atributos: Engineering
  • Atributo: Project
  • Valor do atributo: []

Solicitação

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

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

Resposta

HTTP/1.1 204 No Content

Próxima etapa