Migre seus aplicativos CPV/CSP para usar privilégios de administrador delegado granulares
Funções apropriadas: Administrador global | 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: Aposentadoria do Azure AD Graph e Descontinuação 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 aplicativo seguro e no modelo de aplicativo da plataforma de identidade da 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 é compatível com versões anteriores. 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. Esse processo expõe o locatário do cliente de uma forma difícil para um parceiro governar. 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 Aplicativo Empresarial do Microsoft Entra mostre outros consentimentos, ela não mostra aplicativos com os quais os pré-consentimentos tenham consentido. 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 em nome de (OBO) com o cliente consente em permitir que os aplicativos gerenciados pelo parceiro usem 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 você crie um relacionamento ou grupo de segurança específico para sua entidade de serviço de aplicativo.
Para obter mais informações, consulte Usar a estrutura de 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.
Consentimento da aplicação
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 | No |
Aplicativo multilocatário + usuário | Sim | No |
Aplicativo multilocatário + usuário + OBO | Sim | Requer uma relação GDAP |
Consentimento explícito de aplicativo multilocatário somente
O consentimento explícito somente de aplicativo para um locatário cliente não é suportado por desenvolvedores de aplicativos de terceiros que usam GDAP. Esse consentimento somente de aplicativo não é compatível com o contrato de direitos mínimos por tempo limitado que o GDAP gerencia.
Aplicativo multilocatário explícito + consentimento do usuário
O Partner Center fornece uma API que permite que um CPV ou CSP forneça consentimento para seu aplicativo por meio da automação no locatário do cliente. Aplicativo explícito + consentimento do usuário é necessário para cada locatário do cliente.
O padrão aplicativo + usuário respeita o contrato de direitos mínimos por tempo limitado que o GDAP gerencia. Para obter mais informações, consulte:
- API REST para automatizar o aplicativo CPV/CSP explícito + consentimento do usuário em um locatário do cliente
- Cmdlet do PowerShell para chamar a API
Essa API exige que o usuário do parceiro chamador seja membro de um grupo de segurança que tenha um relacionamento GDAP com o cliente/locatário de destino. O relacionamento GDAP e o grupo de segurança associado devem incluir pelo menos uma destas funções confirmadas:
- Administrador Global
- Administrador de aplicativos (substituído Administrador de função privilegiada)
- Administrador de Aplicações na Cloud
Nota
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.
Uso de uma conta de administrador para fornecer consentimento em nome dos usuários no modelo de aplicativo seguro
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.
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
).Crie um grupo de segurança para ser associado ao relacionamento GDAP do seu cliente (por exemplo, AdminOnBehalfOfSG).
Adicione seu usuário OBO (
AdminOnBehalfOf@contoso.onmicrosoft.com
) ao grupo de segurança GDAP do cliente (AdminOnBehalfOfSG).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, Application Administrator, Global Administrator para fazer a operação de consentimento usando a API.
O CPV ou CSP cria um novo registro de aplicativo multilocatário ou usa um registro existente no locatário parceiro.
Registre a ID do aplicativo (por exemplo, A5000000-F000-4000-8000-3000000000000).
Gere e renove o token de atualização OBO usando o aplicativo multilocatário + identidade de usuário AdminOnBehalfOf 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 multifator (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 usuário OBO em um local seguro que possa ser acessado a partir do seu aplicativo multilocatário. 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.
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:
- Crie uma relação GDAP usando as informações definidas na etapa 4.
- Envie o relacionamento GDAP para aprovação.
- 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.
- 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.
Nota
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
new-PartnerCustomerApplicationConsent
do PowerShell).
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.
API de consentimento
Esta seção discute o aplicativo API CPV/CSP + consentimento do usuário no locatário do cliente com mais detalhes.
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 do seu aplicativo no portal do Azure selecionando Microsoft Entra ID: Registros de Aplicativo "seu aplicativo" e, em seguida, selecionando a guia Permissões da API.
Siga as etapas em Verificar aplicativos primários da Microsoft em relatórios de entrada no Microsoft Entra ID para filtrar aplicativos da 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 no enterpriseApplicationId
exemplo JSON a seguir.
Os IDs a seguir vêm de permissões de aplicativo de exemplo:
Nome da aplicação | ID do aplicativo == enterpriseApplicationId |
---|---|
Microsoft Entra ID | 00000002-0000-0000-C000-0000000000000 |
Microsoft Graph | 00000003-0000-0000-C000-0000000000000 |
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": "57667d41-992a-49b0-99d8-ddf68328373f",
"applicationGrants": [
{
"enterpriseApplicationId":"00000002-0000-0000-c000-000000000000",
"scope":"Directory.ReadWrite.All"
},
{
"enterpriseApplicationId":"00000003-0000-0000-c000-000000000000",
"scope":"Directory.ReadWrite.All"
}
]
}
Nota
Antes de chamar a API, verifique se o token de autenticação criado usa a mesma ID do aplicativo para a qual você deseja dar consentimento no locatário do cliente. Você pode usar um site popular, como o jwt.ms , para decodificar seu token de portador e garantir que seus IDs de aplicativo correspondam. No token ao portador, "appID":"57667d41-992a-49b0-99d8-ddf68328373f"
deve corresponder ao applicationID
valor na carga JSON útil.
Obter nomes amigáveis para permissões e escopos
As informações a seguir são úteis se você quiser descobrir os nomes amigáveis para permissões de API de aplicativo, conforme exibido na seção de registro de aplicativo Microsoft Entra do portal do Azure para um aplicativo específico.
Obtenha uma lista das suas aplicações
Execute o graph api get application
.
Obtenha uma lista de IDs de aplicativos e nomes para exibição. O id
valor é o ID do objeto do aplicativo.
https://graph.microsoft.com/v1.0/applications?$select=id,displayName
Obtenha o valor de um aplicativo, que contém a API e as requiredResourceAccess
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)
Resposta de exemplo:
"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 uma entidade de serviço
Execute Graph api get servicePrincipal.
Obtenha o valor de uma entidade de oauth2PermissionScopes
serviço específica. Substitua {resourceAppId}
pelo valor retornado na requiredResourceAccess
matriz. (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 value
propriedade.
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 do aplicativo requer que as APIs do aplicativo (entidades de serviço) existam no locatário 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á tentando acessar um serviço 'c5393580-f805-4401-95e8-94b7a6ef2fc2' (APIs de gerenciamento do Office 365) para o qual sua organização 'contosoxyz.onmicrosoft.com' não tem uma entidade de serviço. Entre em contato com o administrador de TI para revisar a configuração de suas assinaturas de serviço ou consentir com o aplicativo para 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 a entidade de serviço esteja instalada, consulte Introdução às APIs de gerenciamento do Office 365.
Para verificar se existe uma entidade de serviço no locatário do cliente, você pode chamar a API do Graph para servicePrincipals
nesse locatário.
Para o aplicativo que precisa de consentimento no locatário do cliente, você pode consultar a matriz do requiredResourceAccess
aplicativo. Nessa matriz, para cada resourceAppId
instância, você pode chamar a API no locatário de destino. Substitua {resourceIDvalue} pelo resourceAppId
valor.
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 'c5393580-f805-4401-95e8-94b7a6ef2fc2'&$select=id,appId,appDisplayName
Este é o resultado se a entidade de serviço for encontrada:
"value": [
{
"id": "6cf71994-a896-4e8a-a7a4-6d64276bf370",
"appId": "c5393580-f805-4401-95e8-94b7a6ef2fc2",
"appDisplayName": "Office 365 Management APIs"
}
]
Este é o resultado se a entidade de serviço não for encontrada:
"value": []
Seu resultado determinará seu caminho a seguir: omitir a entidade de serviço, determinar por que uma entidade de serviço está faltando para um cliente ou outras ações específicas para sua empresa.
Solicitar manualmente o consentimento do aplicativo
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 locatário 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:
- Consentimento do aplicativo GDAP
- Modelo de aplicação seguro
- Plataforma de identidade da Microsoft
- Criar aplicativos que entram em usuários do Microsoft Entra
- Funções internas do Microsoft Entra: plataforma de identidade da Microsoft e fluxo OAuth2.0 em nome do
- Escopos, permissões e consentimento
- Tokens de acesso
- Quadro de consentimento
- Glossário de termos na plataforma de identidade da Microsoft (consentimento)