Atribuir funções de administrador personalizadas usando a API do Microsoft Graph no Microsoft Entra ID

  • Artigo

Você pode automatizar a forma como atribui funções a contas de usuário usando a API do Microsoft Graph. Este artigo aborda as operações POST, GET e DELETE em roleAssignments.

Pré-requisitos

  • Licença P1 ou P2 do Microsoft Entra ID
  • Administrador de função com privilégios ou Administrador global
  • Consentimento do administrador ao usar o Explorador do Graph para a API do Microsoft Graph

Para obter mais informações, confira Pré-requisitos para usar o PowerShell ou o Explorador do Graph.

Operações POST no RoleAssignment

Use a API Create unifiedRoleAssignment para atribuir a função.

Exemplo 1: Criar uma atribuição de função entre um usuário e uma definição de função

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments
Content-type: application/json

Corpo

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "roleDefinitionId": "194ae4cb-b126-40b2-bd5b-6091b380977d",
    "directoryScopeId": "/"  // Don't use "resourceScope" attribute in Azure AD role assignments. It will be deprecated soon.
}

Resposta

HTTP/1.1 201 Created

Exemplo 2: Criar uma atribuição de função na qual a definição de entidade de segurança ou de função não existe

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

Corpo

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "2142743c-a5b3-4983-8486-4532ccba12869",
    "roleDefinitionId": "194ae4cb-b126-40b2-bd5b-6091b380977d",
    "directoryScopeId": "/"  //Don't use "resourceScope" attribute in Azure AD role assignments. It will be deprecated soon.
}

Resposta

HTTP/1.1 404 Not Found

Exemplo 3: Criar uma atribuição de função em um único escopo de recurso

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

Corpo

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "2142743c-a5b3-4983-8486-4532ccba12869",
    "roleDefinitionId": "e9b2b976-1dea-4229-a078-b08abd6c4f84",    //role template ID of a custom role
    "directoryScopeId": "/13ff0c50-18e7-4071-8b52-a6f08e17c8cc"  //object ID of an application
}

Resposta

HTTP/1.1 201 Created

Exemplo 4: Criar uma atribuição de função com escopo de unidade administrativa em uma definição de função interna que não tem suporte

POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

Corpo

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "roleDefinitionId": "29232cdf-9323-42fd-ade2-1d097af3e4de",    //role template ID of Exchange Administrator
    "directoryScopeId": "/administrativeUnits/13ff0c50-18e7-4071-8b52-a6f08e17c8cc"    //object ID of an administrative unit
}

Resposta

HTTP/1.1 400 Bad Request
{
    "odata.error":
    {
        "code":"Request_BadRequest",
        "message":
        {
            "message":"The given built-in role is not supported to be assigned to a single resource scope."
        }
    }
}

Somente um subconjunto de funções internas é habilitado para o escopo da Unidade administrativa. Consulte esta documentação para obter a lista de funções internas com suporte em uma unidade administrativa.

Operações GET no RoleAssignment

Use a API List unifiedRoleAssignments para obter a atribuição de função.

Exemplo 5: Obter atribuições de função para uma determinada entidade de segurança

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=principalId+eq+'<object-id-of-principal>'

Resposta

HTTP/1.1 200 OK
{
"value":[
            { 
                "id": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
                "roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",
                "directoryScopeId": "/"  
            } ,
            {
                "id": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
                "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
                "directoryScopeId": "/"
            }
        ]
}

Exemplo 6: Obter atribuições de função para uma determinada definição de função.

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=roleDefinitionId+eq+'<object-id-or-template-id-of-role-definition>'

Resposta

HTTP/1.1 200 OK
{
"value":[
            {
                "id": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
                "roleDefinitionId": "fe930be7-5e62-47db-91af-98c3a49a38b1",
                "directoryScopeId": "/"
            }
     ]
}

Exemplo 7: Obter uma atribuição de função por ID.

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

Resposta

HTTP/1.1 200 OK
{ 
    "id": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1",
    "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
    "roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",
    "directoryScopeId": "/"
}

Exemplo 8: Obter atribuições de função para um determinado escopo

GET https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments?$filter=directoryScopeId+eq+'/d23998b1-8853-4c87-b95f-be97d6c6b610'

Resposta

HTTP/1.1 200 OK
{
"value":[
            { 
                "id": "mhxJMipY4UanIzy2yE-r7JIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
                "roleDefinitionId": "10dae51f-b6af-4016-8d66-8c2a99b929b3",
                "directoryScopeId": "/d23998b1-8853-4c87-b95f-be97d6c6b610"
            } ,
            {
                "id": "CtRxNqwabEKgwaOCHr2CGJIiSDKQoTVJrLE9etXyrY0-1"
                "principalId": "ab2e1023-bddc-4038-9ac1-ad4843e7e539",
                "roleDefinitionId": "3671d40a-1aac-426c-a0c1-a3821ebd8218",
                "directoryScopeId": "/d23998b1-8853-4c87-b95f-be97d6c6b610"
            }
        ]
}

Operações DELETE no RoleAssignment

Use a API Delete unifiedRoleAssignment para excluir a atribuição de função.

Exemplo 9: Excluir uma atribuição de função entre um usuário e uma definição de função.

DELETE https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

Resposta

HTTP/1.1 204 No Content

Exemplo 10: Excluir uma atribuição de função que não existe mais

DELETE https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

Resposta

HTTP/1.1 404 Not Found

Exemplo 11: excluir uma atribuição de função entre a definição de função de administrador de si mesmo e global

DELETE https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments/lAPpYvVpN0KRkAEhdxReEJC2sEqbR_9Hr48lds9SGHI-1

Resposta

HTTP/1.1 400 Bad Request
{
    "odata.error":
    {
        "code":"Request_BadRequest",
        "message":
        {
            "lang":"en",
            "value":"Removing self from Global Administrator built-in role is not allowed"},
            "values":null
        }
    }
}

Impedimos que os usuários excluam sua própria função de Administrador global para evitar um cenário em que um locatário tenha zero Administradores globais. A remoção de outras funções atribuídas a si mesma é permitida.

Próximas etapas