Partilhar via

Migre seus aplicativos CPV/CSP para usar privilégios de administrador delegado granulares

Funções apropriadas: Administrador de gerenciamento de usuários

Importante

O Azure Ative Directory (Azure AD) Graph foi preterido a partir de 30 de junho de 2023. No futuro, não faremos mais investimentos no Azure AD Graph. As APIs do Azure AD Graph não têm SLA ou compromisso de manutenção além das correções relacionadas à segurança. Os investimentos em novos recursos e funcionalidades só serão feitos no Microsoft Graph.

Desativaremos o Azure AD Graph em etapas incrementais para que você tenha tempo suficiente para migrar seus aplicativos para APIs do Microsoft Graph. Em uma data posterior que anunciaremos, bloquearemos a criação de novos aplicativos usando o Azure AD Graph.

Para saber mais, consulte Importante: Descontinuação do Azure AD Graph e do Módulo PowerShell.

Este artigo mostra como atualizar seus aplicativos CPV (Fornecedor do Painel de Controle) e CSP (Provedor de Soluções na Nuvem) para usar privilégios de administrador delegado granulares (GDAP). O modelo GDAP ajuda a aplicar as práticas recomendadas de segurança no modelo de aplicação seguro e no modelo de aplicação da plataforma de identidade Microsoft , incluindo o fornecimento de direitos mínimos e uma estrutura com limite de tempo.

Comparação do GDAP com o DAP

O modelo GDAP substitui o modelo de privilégios de administrador delegado (DAP) e não oferece compatibilidade retroativa. O modelo DAP está sendo preterido.

Com o modelo de agente de administração do DAP, você pode conceder ao seu aplicativo gerenciado pelo parceiro um conjunto de permissões configuradas para todos os seus clientes em seu locatário sem revisão. Este processo é chamado de pré-consentimento. Este processo expõe o tenant do cliente de uma forma que torna difícil para um parceiro gerir. Ele potencialmente escala usuários e tarefas não privilegiados para um contexto privilegiado.

O risco de usar o pré-consentimento é ainda maior porque os parceiros não podem revisar ou auditar os consentimentos. Embora a página Microsoft Entra Enterprise Application mostre outros consentimentos, ela não mostra aplicações para as quais os pré-consentimentos foram concedidos. Esse comportamento herdado não se alinha com o conceito de direitos mínimos na plataforma de identidade da Microsoft.

No modelo GDAP, o cliente ou um administrador com uma relação 'on-behalf-of' (OBO) com o cliente consente em permitir que as aplicações geridas pelo parceiro usem o seu locatário. Esse comportamento fornece rastreabilidade para o cliente e se alinha ao modelo de aplicativo da plataforma de identidade da Microsoft e à estrutura do modelo de aplicativo seguro.

O GDAP não exige que o utilizador crie um relacionamento ou grupo de segurança específico para o principal de serviço de aplicação.

Para obter mais informações, consulte Utilize a estrutura do modelo de aplicativo seguro.

Permissões de aplicativo e funções de usuário do Microsoft Entra

Você pode atribuir permissões de aplicativos no Microsoft Entra ID na guia permissões da API.

Com o GDAP, você não pode mais adicionar funções do Microsoft Entra a um aplicativo usando relacionamentos ou por meio da inclusão em um grupo de segurança. Os usuários têm funções atribuídas diretamente por meio do portal do Azure ou indiretamente por meio da atribuição de grupo. Os usuários não podem ter permissões de aplicativo.

O consentimento do aplicativo é o processo do qual um proprietário de recurso concede autorização para um aplicativo cliente acessar recursos protegidos, sob permissões específicas, em nome do proprietário do recurso.

A tabela a seguir lista os modelos de serviço de aplicativo que funcionam com consentimento de aplicativo.

Modelo de aplicação Consentimento da aplicação OBO
Somente aplicativo multilocatário (somente DAP, não suportado no GDAP) Sim Não
Aplicação multitenant e utilizador Sim Não
Aplicação multilocatária + utilizador + OBO Sim Requer um relacionamento GDAP

O consentimento explícito apenas para aplicativos a um inquilino cliente não é suportado por desenvolvedores de aplicativos de terceiros que usam GDAP. Este consentimento exclusivo de aplicativo não é compatível com o contrato de direitos mínimos e com duração limitada que o GDAP gerencia.

Aplicação multicliente explícita e consentimento do utilizador

O Partner Center disponibiliza uma API que permite a um CPV ou CSP conceder consentimento à sua aplicação através da automação no tenant do cliente. É necessário o consentimento explícito da aplicação e do utilizador para cada cliente.

O padrão aplicativo + usuário respeita o contrato de direitos mínimos por tempo limitado que o GDAP gerencia. Para mais informações, consulte:

A API exige que o usuário do parceiro que chama seja membro de um grupo de segurança que tenha um relacionamento GDAP com o cliente/locatário de destino. A relação GDAP e o grupo de segurança associado devem incluir pelo menos uma das seguintes funções confirmadas:

  • Administrador de Aplicações (em vez de Administrador de Função Privilegiada)
  • Administrador de aplicativos na nuvem

Observação

O uso do Privileged Role Administrator não é mais recomendado.

O usuário parceiro também deve ser membro do grupo de segurança AdminAgents, que é necessário para chamar as APIs do Partner Center.

Os parceiros podem fornecer automaticamente consentimento para um aplicativo configurando uma conta de administrador OBO, definindo permissões, gerando um token temporário e associando a conta ao usuário.

  1. Crie uma nova conta de usuário ou escolha uma conta de usuário existente para ser usada como a conta OBO CPV/CSP (por exemplo, AdminOnBehalfOf@contoso.onmicrosoft.com).

  2. Crie um grupo de segurança para ser associado ao relacionamento GDAP do seu cliente (por exemplo, AdminOnBehalfOfSG).

  3. Adicione seu usuário OBO (AdminOnBehalfOf@contoso.onmicrosoft.com) ao grupo de segurança GDAP do cliente (AdminOnBehalfOfSG).

  4. Defina os seguintes parâmetros de relacionamento GDAP. Você os usará mais tarde.

    • Duração em dias.
    • Funções solicitadas do Microsoft Entra necessárias para o OBO.
    • Quando você deseja automatizar o consentimento do aplicativo, conforme descrito na seção anterior. O relacionamento GDAP deve incluir pelo menos um dos seguintes: Cloud Application Administrator ou Application Administrator para realizar a operação de consentimento utilizando a API.

  5. O CPV ou CSP cria um novo registro de aplicativo multilocatário ou usa um registro existente no locatário parceiro.

    Registre o ID do aplicativo (por exemplo, 00001111-aaaa-2222-bbbb-3333cccc4444).

  6. Gere e renove o token de atualização OBO utilizando a aplicação multitenant + AdminOnBehalfOf identidade de utilizador gerada na etapa 1.

    Os exemplos a seguir mostram como criar o respetivo token usando o logon interativo único. Certifique-se de que o início de sessão utiliza autenticação multifatorial (MFA), porque o token de atualização tem de ser criado através de MFA para funcionar em cenários OBO.

    Armazene o token de atualização do utilizador OBO num local seguro acessível pelo seu aplicativo multi-inquilino. O Azure Key Vault pode ser uma opção, mas não é necessário. Para obter mais informações, consulte a visão geral do Azure Key Vault e a documentação da API do Key Vault.

    Certifique-se de que o token de atualização armazenado seja renovado pelo menos a cada 90 dias para evitar a expiração. Você pode fazer isso dentro do seu código de automação ou desenvolvendo um aplicativo ou script autônomo que renova o token. Sempre que um novo token de acesso é criado a partir do token de atualização armazenado, um novo token de atualização com um tempo de vida de 90 dias é gerado.

    Sempre que precisar autenticar o locatário do cliente para operações, obtenha o token de atualização mais recente do seu repositório seguro e use-o para gerar um token de acesso (e um novo token de atualização) para autenticação.

  7. Para cada cliente que usará seu aplicativo multilocatário e para quem você deseja executar atividades por meio de administração delegada, execute as seguintes etapas:

    1. Crie uma relação GDAP usando as informações definidas na etapa 4.
    2. Envie a relação GDAP para aprovação.
    3. Depois que o relacionamento GDAP estiver ativo, atribua o grupo de segurança definido na etapa 2 com as funções apropriadas do Microsoft Entra definidas na etapa 4.
    4. Certifique-se de que um administrador concedeu consentimento para seu aplicativo no locatário do cliente. Para a abordagem de consentimento automático, você pode fazer isso depois que o GDAP for estabelecido. Para obter o consentimento manual, o administrador de um cliente pode fazer isso antes que o GDAP seja configurado.

Observação

Você pode usar o token de atualização gerado na etapa 6 para autenticação em relação a cada cliente. Você não precisa executar a etapa 6 para cada cliente separadamente. Quando você está fazendo operações em um locatário cliente, você pega o token gerado inicialmente e o troca por um token gerado contra o locatário do cliente. Isso é possível devido à relação/funções GDAP e ao consentimento do aplicativo.

Para configurar vários clientes em escala, recomendamos o seguinte processo:

  • Para novos clientes onde não existe nenhum privilégio de delegação, inclua uma das funções de consentimento de pré-requisito em sua solicitação inicial de relacionamento GDAP (por exemplo, Cloud Application Administrator).

    Como alternativa, se você preferir a delegação de privilégios de curto prazo, avalie se pode usar uma segunda solicitação de relacionamento GDAP com curta duração (como um dia) usando uma permissão que permita a delegação de consentimento (como Cloud Application Administrator). Essa abordagem permite remover a função mais privilegiada depois de verificar a função de consentimento. Você pode remover manualmente essa segunda solicitação GDAP a qualquer momento.

  • Para casos de clientes em que existe um privilégio de delegação e o parceiro tem DAP, execute o consentimento automatizado em massa (por exemplo, usando o script PowerShell new-PartnerCustomerApplicationConsent).

Ao migrar do DAP para o GDAP usando a ferramenta de migração em massa liderada pelo parceiro, configure as respetivas funções que permitem que o parceiro dê consentimento para os clientes migrados. Para clientes que têm apenas delegações parciais de função GDAP, o parceiro solicita a função Cloud Application Administrator (ou uma função semelhante na lista de pré-requisitos de função) para o cliente aprovar manualmente.

Esta seção discute em maior detalhe a aplicação da API CPV/CSP e o consentimento do utilizador no tenant do cliente.

Identificar aplicativos e escopos corporativos (também conhecidos como permissões)

Para cada aplicativo para o qual você planeja dar consentimento, mapeie as APIs e permissões do aplicativo para a carga JSON útil. Você pode encontrar os detalhes da sua aplicação no portal do Azure selecionando ID do Microsoft Entra: Registos de Aplicações "a sua aplicação" e, em seguida, selecionando a guia Permissões da API.

Siga as etapas em Verifique as aplicações de primeira parte da Microsoft nos relatórios de início de sessão no Microsoft Entra ID para filtrar aplicações Microsoft. Localize as APIs de aplicativos corporativos referenciadas pelo seu aplicativo e obtenha suas IDs de aplicativo específicas. Esses IDs de aplicativo serão atribuídos a enterpriseApplicationId no exemplo JSON a seguir.

Os IDs a seguir vêm de permissões de aplicativo de exemplo:

Nome do aplicativo ID do aplicativo == enterpriseApplicationId
Microsoft Entra ID (um serviço de identificação da Microsoft) 00000002-0000-0000-C000-0000000000000
Gráfico da Microsoft 00000003-0000-0000-C000-000000000000

Inclua na propriedade scope as permissões necessárias para cada API. A propriedade scope pode conter todas as permissões (delimitadas por vírgula) ou um subconjunto de permissões configuradas no aplicativo para o qual você deseja fornecer consentimento.

Exemplo de carga útil JSON:

{
    "applicationId": "11112222-bbbb-3333-cccc-4444dddd5555",
    "applicationGrants": [
        {
            "enterpriseApplicationId":"00000002-0000-0000-c000-000000000000",
            "scope":"Directory.ReadWrite.All"
        },
        {
            "enterpriseApplicationId":"00000003-0000-0000-c000-000000000000",
            "scope":"Directory.ReadWrite.All"
        }
    ]
}

Observação

Antes de chamar a API, verifique se o token de autenticação criado usa a mesma ID da aplicação para a qual deseja dar consentimento no tenant do cliente. Você pode usar um site popular, como o jwt.ms, para decodificar seu token de portador e garantir que os IDs do aplicativo correspondam. No token de portador, "appID":"11112222-bbbb-3333-cccc-4444dddd5555" deve corresponder ao valor de applicationID na carga útil JSON.

Obter nomes amigáveis para permissões e âmbitos

As informações a seguir são úteis se tu quiseres descobrir os nomes amigáveis para permissões de API de aplicação, conforme exibido na seção de registo de aplicações Microsoft Entra do portal Azure para uma aplicação específica.

Obtenha uma lista das suas aplicações

Execute graph api get application.

Obtenha uma lista de IDs de aplicações e nomes de exibição. O valor id é a ID do objeto do aplicativo.

https://graph.microsoft.com/v1.0/applications?$select=id,displayName

Obtenha o valor requiredResourceAccess de um aplicativo, que contém a API e as permissões do aplicativo, conforme exibido no portal do Azure. Substitua {applicationObjectId} pelo ID do aplicativo da etapa anterior.

https://graph.microsoft.com/v1.0/applications/{applicationObjectId}?$select=requiredResourceAccess](https://graph.microsoft.com/v1.0/applications/{applicationObjectId}?$select=requiredResourceAccess)

Exemplo de resposta:

"requiredResourceAccess": [
    {
        "resourceAppId": "00000003-0000-0000-c000-000000000000",
        "resourceAccess": [
            {
                "id": "885f682f-a990-4bad-a642-36736a74b0c7",
                "type": "Scope"
            },
            {
                "id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d",
                "type": "Scope"
            },
            {
                "id": "06da0dbc-49e2-44d2-8312-53f166ab848a",
                "type": "Scope"
            },
            {
                "id": "c5366453-9fb0-48a5-a156-24f0c49a4b84",
                "type": "Scope"
            }
        ]
    }
]

Obter um principal de serviço

Execute Graph API obter Service Principal.

Obtenha o valor oauth2PermissionScopes de um service principal específico. Substitua {resourceAppId} pelo valor retornado na matriz requiredResourceAccess. (Pode haver mais de um.)

https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appid eq '{resourceAppId}'&$select=oauth2PermissionScopes

Encontre as definições de escopo por ID na resposta e o nome amigável armazenado na propriedade value.

Exemplo de resposta editada (reduzida para maior clareza):

{
    "adminConsentDisplayName": "Manage Delegated Admin relationships with customers",
    "id": "885f682f-a990-4bad-a642-36736a74b0c7",
    "isEnabled": true,
     "type": "Admin",
    "value": "DelegatedAdminRelationship.ReadWrite.All"
},
{
    "adminConsentDisplayName": "Sign in and read user profile",
    "id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d",
    "isEnabled": true,
    "type": "User",
    "value": "User.Read"
},
{
    "adminConsentDisplayName": "Read directory data",
    "id": "06da0dbc-49e2-44d2-8312-53f166ab848a",
    "isEnabled": true,
    "type": "Admin",
    "value": "Directory.Read.All"
},
{
    "adminConsentDisplayName": "Read and write directory data",
    "id": "c5366453-9fb0-48a5-a156-24f0c49a4b84",
    "isEnabled": true,
    "type": "Admin",
    "value": "Directory.ReadWrite.All"
},

Entidades de segurança ausentes em um locatário do cliente

A API de consentimento da aplicação requer que as APIs da aplicação (principais de serviço) existam no inquilino do cliente. Poderá ver uma mensagem de erro como o exemplo seguinte quando estiver a consentir. Ele sinaliza que o aplicativo não existe no locatário do cliente.

O aplicativo está a tentar aceder a um serviço '22223333-cccc-4444-dddd-5555eeee6666' (APIs de gestão do Office 365) para o qual a sua organização 'contosoxyz.onmicrosoft.com' não tem um principal de serviço. Entre em contacto com o administrador de IT para rever a configuração das suas assinaturas de serviço ou dar consentimento à aplicação, de modo a criar a entidade de serviço necessária.

O erro de exemplo diz que a API de Gerenciamento do Office 365 não está instalada no locatário do cliente. Para obter os pré-requisitos para garantir que o principal de serviço esteja instalado, consulte Introdução às APIs de Gerenciamento do Office 365.

Para verificar se existe um serviço principal no tenant do cliente, pode chamar a API do Graph para servicePrincipals nesse tenant.

Para o aplicativo que precisa de consentimento no locatário do cliente, você pode consultar a matriz requiredResourceAccess do aplicativo. Nesse array, para cada instância resourceAppId, pode-se chamar a API no inquilino de destino. Substitua {resourceIDvalue} pelo valor resourceAppId.

https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appid eq '{resourceID value}'&$select=id,appId,appDisplayName

Por exemplo:

https://graph.microsoft.com/v1.0/servicePrincipals?$filter=appid eq '22223333-cccc-4444-dddd-5555eeee6666'&$select=id,appId,appDisplayName

Este será o resultado caso a entidade de serviço seja encontrada:

    "value": [
        {
            "id": "6cf71994-a896-4e8a-a7a4-6d64276bf370",
            "appId": "22223333-cccc-4444-dddd-5555eeee6666",
            "appDisplayName": "Office 365 Management APIs"
        }
    ]

Este é o resultado se o principal do serviço não for encontrado.

    "value": []

O seu resultado determinará o seu caminho a seguir: omitir o principal de serviço, determinar por que um principal de serviço está em falta para um cliente ou outras ações específicas para o seu negócio.

Se você tiver a função de Administrador Global no locatário de um cliente, poderá consentir com o aplicativo por conta própria. Nos casos em que o cliente não deseja aprovar a função de Administrador Global, você pode solicitar que ele insira o URI em um navegador e dê o seu consentimento manualmente. Depois que o consentimento for concluído, seu aplicativo poderá ser executado com o cliente habilitado para GDAP.

Para obter consentimento para seu aplicativo no locatário do cliente, construa um URI da seguinte maneira. Substitua {customertenant} pelo inquilino do cliente. Substitua {appid} pelo aplicativo para o qual você deseja fornecer consentimento.

https://login.microsoftonline.com/{customertenant}.onmicrosoft.com/adminconsent?client_id={appid}

Insira o URI recém-construído em um navegador da Web e siga os prompts de login e consentimento.

Recursos

Os links de recursos a seguir são uma ordem de leitura sugerida:

  • Last updated on