Usar a Aprovação de Vários Administradores com a API do Graph

O MAA (Multi Administração Approval) impõe fluxos de trabalho de aprovação em chamadas à API autenticadas pelo aplicativo (app-auth) feitas por meio da API do Graph. Se sua organização usa entidades de serviço, scripts de automação ou aplicativos de terceiros para gerenciar recursos do Intune, essas chamadas são interceptadas pelo MAA quando o recurso de destino é protegido por uma política de acesso.

Este artigo explica como atualizar sua automação para trabalhar com o fluxo de trabalho de aprovação do MAA e como excluir aplicativos específicos da aplicação quando uma alteração de código não é imediatamente viável.

O que muda para chamadas de autenticação de aplicativo

Anteriormente, somente ações administrativas interativas (delegadas) estavam sujeitas a fluxos de trabalho de aprovação do MAA. Com essa alteração, as chamadas automatizadas e com script que usam tokens somente de aplicativo também são interceptadas pelo MAA quando o recurso de destino é protegido por uma política de acesso.

Se o aplicativo fizer chamadas de API para recursos protegidos por MAA usando app-auth e não incluir os cabeçalhos de aprovação necessários, a chamada retornará um erro HTTP 400. O corpo da resposta indica que a operação requer a aprovação de vários administradores.

Tipos de recursos afetados

As políticas de acesso MAA podem proteger os seguintes tipos de recursos. Se suas chamadas de autenticação de aplicativo forem direcionadas a qualquer um desses recursos e uma política de acesso estiver ativa, sua automação será afetada:

• Aplicativos
• Políticas de conformidade
• Políticas de configuração
• Ações de dispositivo
• Controle de acesso baseado em função
• Scripts
• Configuração do Locatário

O MAA só se aplica a operações que modificam recursos protegidos (POST, PATCH, PUT, DELETE). As operações somente leitura (GET) não são afetadas.

Pré-requisitos

• Um registro de aplicativo com as permissões de aplicativo Microsoft Graph necessárias para os recursos do Intune que seu aplicativo gerencia (por exemplo, DeviceManagementApps.ReadWrite.All).
• Políticas de acesso MAA configuradas para as cargas de trabalho relevantes. Para obter mais informações, consulte Criar uma política de acesso.
• Uma conta de administrador separada que seja membro do grupo aprovador da política de acesso. Os aplicativos não podem aprovar ou rejeitar solicitações MAA, somente contas de administrador interativas podem aprovar solicitações.

Etapa 1: Enviar uma solicitação com um cabeçalho de justificativa

Quando o MAA estiver habilitado, inclua um cabeçalho de justificativa com sua solicitação. O x-msft-approval-justification valor do cabeçalho deve ser codificado em Base64.

O exemplo a seguir cria um recurso de script do PowerShell no Intune e inclui o cabeçalho de justificativa necessário:

POST https://graph.microsoft.com/beta/deviceManagement/deviceManagementScripts
Content-Type: application/json
x-msft-approval-justification: YXBwIG9ubHkgdGVzdA==

{
  "displayName": "My Test Script",
  "description": "Testing MAA with app-only token",
  "scriptContent": "V3JpdGUtT3V0cHV0ICJIZWxsbyBXb3JsZCI=",
  "runAsAccount": "system",
  "fileName": "TestScript.ps1",
  "roleScopeTagIds": ["0"]
}

Sem o cabeçalho de justificativa, a solicitação falha com um erro indicando que o x-msft-approval-justification cabeçalho é necessário.

Etapa 2: Lidar com a resposta de aprovação

A solicitação retorna um HTTP 412 (Precondition Failed) com um código de erro externo do Microsoft Graph de BadRequest. Essa resposta é esperada e não indica um problema de permissão — é como o MAA sinaliza que a solicitação foi recebida e agora está aguardando aprovação. Os detalhes da aprovação necessária estão aninhados na mensagem de erro.

A resposta inclui um x-msft-approval-code cabeçalho que você precisa para as etapas restantes. Use a presença desse cabeçalho junto com o HTTP 412 como o sinal de que o MAA aceitou a solicitação e criou uma solicitação de aprovação.

Exemplo de resposta:

HTTP/1.1 412 Precondition Failed
x-msft-approval-code: aabb1234-5678-9012-abcd-ef0123456789
Content-Type: application/json

{
  "error": {
    "code": "BadRequest",
    "message": "{\r\n  \"_version\": 3,\r\n  \"Message\": \"Approval Required. Request Approval using the request ID returned as part of the x-msft-approval-code response header. x-msft-approval-code: aabb1234-5678-9012-abcd-ef0123456789 - Operation ID (for customer support): 00000000-0000-0000-0000-000000000000 - Activity ID: <activity-id> - Url: <service-url>\",\r\n  \"CustomApiErrorPhrase\": \"\",\r\n  \"RetryAfter\": null,\r\n  \"ErrorSourceService\": \"\",\r\n  \"HttpHeaders\": \"{\\\"x-msft-approval-code\\\":\\\"aabb1234-5678-9012-abcd-ef0123456789\\\"}\"\r\n}"
  }
}

Extraia o x-msft-approval-code valor da resposta. Salve o método HTTP original, a URL e o corpo da solicitação com esse valor, pois você deve reenviar a mesma solicitação na Etapa 4 após a aprovação.

Etapa 3: aguardar aprovação

Neste ponto, a solicitação de aprovação deve ser revisada e aprovada por outro administrador no centro de administração do Microsoft Intune. Os aplicativos não podem aprovar ou rejeitar solicitações MAA — somente contas administrativas interativas podem aprová-las.

Você pode consultar o status da solicitação de aprovação a qualquer momento usando o código de aprovação:

GET https://graph.microsoft.com/beta/deviceManagement/operationApprovalRequests?$filter=requestId eq 'aabb1234-5678-9012-abcd-ef0123456789'

O status campo indica o estado atual da solicitação. Os valores comuns incluem needsApproval, approved, rejectede cancelled. Aguarde até que o status mude para approved antes de continuar.

Etapa 4: reenviar com o código de aprovação

Depois que a solicitação for aprovada, reenvie a solicitação original. Substitua o cabeçalho da justificação pelo x-msft-approval-code cabeçalho e use o código de aprovação da Etapa 2:

POST https://graph.microsoft.com/beta/deviceManagement/deviceManagementScripts
Content-Type: application/json
x-msft-approval-code: aabb1234-5678-9012-abcd-ef0123456789

{
  "displayName": "My Test Script",
  "description": "Testing MAA with app-only token",
  "scriptContent": "V3JpdGUtT3V0cHV0ICJIZWxsbyBXb3JsZCI=",
  "runAsAccount": "system",
  "fileName": "TestScript.ps1",
  "roleScopeTagIds": ["0"]
}

A solicitação é concluída com êxito e o recurso é criado.

Excluir um aplicativo da imposição do MAA

Se você não puder atualizar imediatamente seu aplicativo para incluir o fluxo de trabalho de aprovação, poderá excluí-lo da imposição do MAA na política de acesso. Para configurar uma exclusão, edite a política de acesso para a carga de trabalho que seu aplicativo chama e adicione o aplicativo na guia Exclusões . Um segundo administrador deve aprovar a alteração antes que a exclusão entre em vigor.

As exclusões se aplicam somente a chamadas de autenticação de aplicativo (autenticadas pelo aplicativo) feitas pela entidade de serviço excluída. Ações administrativas interativas (delegadas) nos mesmos recursos protegidos ainda exigem aprovação do MAA.

Para obter mais informações sobre exclusões, incluindo escopo, limites e considerações de segurança, consulte Criar uma política de acesso.

Monitorar a atividade do MAA para chamadas de autenticação de aplicativo

Eventos relacionados ao MAA — incluindo aprovar, bloquear, passar, adicionar exclusão e remover exclusão — são registrados no log de auditoria do Intune existente. Use o log de auditoria padrão e a exportação da API do Graph para ver quais chamadas de autenticação de aplicativo estão passando pelo MAA e como estão sendo tratadas.

Perguntas frequentes

Por que meus scripts de automação estão falhando?

Se sua automação chamar o Microsoft Graph e tiver como destino recursos protegidos por uma política de acesso MAA, essas chamadas serão interceptadas pelo fluxo de trabalho de aprovação do MAA, independentemente de o script usar autenticação delegada ou somente de aplicativo. Atualize seus scripts para incluir os cabeçalhos de justificativa e aprovação descritos neste artigo. Se o script usar tokens somente de aplicativo (fluxo de credenciais do cliente), você também poderá excluir o aplicativo da política de acesso.

O MAA afeta as chamadas de API somente leitura?

Não. O MAA só se aplica a operações que modificam recursos protegidos (POST, PATCH, PUT, DELETE). As solicitações GET não são afetadas.

Um aplicativo pode aprovar suas próprias solicitações de MAA?

Não. Os aplicativos não podem aprovar ou rejeitar solicitações MAA. Uma conta de administrador interativa separada que é membro do grupo de aprovadores deve aprovar a solicitação no centro de administração do Microsoft Intune.

Como fazer marcar se meu locatário tiver o MAA habilitado?

No centro de administração do Microsoft Intune, acesse Administração de>locatários Aprovação> AdministraçãoPolíticas de acesso. Se houver políticas de acesso ativas listadas, o MAA será habilitado para essas cargas de trabalho.

Posso desativar o MAA para interromper a imposição?

As políticas de acesso MAA podem ser gerenciadas por administradores com as permissões apropriadas. No entanto, a Microsoft recomenda manter o MAA habilitado como uma prática recomendada de segurança.

Conteúdo relacionado

• Usar políticas de acesso para exigir a aprovação de vários administradores
• Logs de auditoria para atividades do Intune