Chamando uma API de outra API

Como você, como desenvolvedor, garante a Confiança Zero quando tem uma API que precisa chamar outra API? Neste artigo, você aprenderá a desenvolver seu aplicativo com segurança quando ele estiver trabalhando em nome de um usuário.

Quando um usuário dirige a interface do usuário de um aplicativo, o aplicativo pode utilizar uma permissão delegada para que a API saiba qual usuário em nome do qual o aplicativo está trabalhando. Ele inspecionaria as declarações de declaração de assunto (sub) ou ID de objeto (oid) e ID de locatário (tid) no token de acesso que o aplicativo fornece ao chamar a API. A API não dependeria do aplicativo não confiável, que é apenas uma chamada vinda de algum lugar da rede. Em vez disso, ele validaria o token para garantir que a API funcione apenas em nome do usuário do aplicativo que o Microsoft Entra ID verificou.

Quando uma API (nós a chamamos de API Original) chama outra, é vital que a API que estamos chamando (nós a chamamos de API Downstream) siga o processo de validação descrito acima. A API Downstream não pode depender de uma fonte de rede não confiável. Ele deve obter a identidade do usuário de um token de acesso validado corretamente.

Se a API Downstream não seguir o processo de validação adequado, a API Downstream deverá confiar na API Original para fornecer a identidade do usuário de outra maneira. A API Downstream pode utilizar incorretamente uma permissão de aplicativo para executar a operação. Em seguida, a API Original se tornaria a única autoridade sobre a qual os usuários poderiam obter quais resultados em relação à API Downstream. A API original pode intencionalmente (ou não) permitir que um usuário realize uma tarefa que o usuário não poderia realizar de outra forma. Por exemplo, um usuário pode alterar os detalhes de outro usuário ou ler e atualizar documentos que o usuário não tem permissão para acessar. A validação incorreta pode cautilizar sérios problemas de segurança.

Para maior segurança, a API Original adquire um token de acesso com permissão delegada para fornecer à API Downstream quando a API Original faz a chamada. Vamos ver como isso funciona.

O aplicativo cliente adquire token de acesso para chamar a API original

O diagrama a seguir mostra o Aplicativo Cliente à esquerda e a API Original à direita.

Título do diagrama: O aplicativo cliente adquiriu um token de acesso para chamar a API original. Legenda do diagrama: O Aplicativo Cliente tem um token de acesso 'A' que permite que ele trabalhe em nome do usuário identificado no token para chamar a API Original. Componentes do diagrama: uma representação de uma nuvem aparece no centro superior do slide que inclui um ícone de ID do Microsoft Entra. No canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há duas formas de hexágonos rotuladas como 'ID' e 'A' que representam tokens de ID e acesso. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas à esquerda às formas à direita.

O Aplicativo Cliente adquiriu um token de acesso de permissão delegada (indicado pela forma do pentágono com o rótulo "A") para a API Original. O token de acesso de permissão delegada permite que ele trabalhe em nome do usuário para chamar a API Original que requer autorização.

O aplicativo cliente fornece token de acesso à API original

A animação abaixo mostra o Aplicativo Cliente dando o token de acesso à API Original. A API Original valida e inspeciona totalmente o token de acesso para determinar a identidade do usuário do Aplicativo Cliente.

O diagrama animado mostra dois diagramas com uma transição de movimento entre o primeiro diagrama e o segundo diagrama. Primeiro título do diagrama: O aplicativo cliente adquiriu um token de acesso para chamar a API original. Primeiro subtítulo do diagrama: O Aplicativo Cliente tem um token de acesso 'A' que permite que ele trabalhe em nome do usuário identificado no token para chamar a API Original. Primeiros componentes do diagrama: uma representação de uma nuvem aparece no centro superior do slide que inclui um ícone de ID do Microsoft Entra. No canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há duas formas de hexágonos rotuladas como 'ID' e 'A' que representam tokens de ID e acesso. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas à esquerda às formas à direita. Segundo título do diagrama: O Aplicativo Cliente fornece o token de acesso à API Original. Componentes do segundo diagrama: uma representação de uma nuvem aparece no centro superior do slide que inclui um ícone de ID do Microsoft Entra. No canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há uma forma de hexágono rotulada como 'ID' que representa um token de ID. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". À sua esquerda está uma forma de hexágono rotulada 'A' que representa um token de acesso. Uma seta conecta as formas à esquerda às formas à direita.

A API original executa a validação e a imposição do token

A próxima animação mostra que, depois que o Aplicativo Cliente fornece o token de acesso à API Original, a API Original executa a validação e a imposição do token. Se tudo estiver bom, a API prosseguirá e atenderá a solicitação para o Aplicativo Cliente.

O diagrama animado mostra dois diagramas com uma transição de movimento entre o primeiro diagrama e o segundo diagrama. Primeiro título do diagrama: O Aplicativo Cliente fornece o token de acesso à API Original. Primeiros componentes do diagrama: uma representação de uma nuvem aparece no centro superior do slide que inclui um ícone de ID do Microsoft Entra. No canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há uma forma de hexágono rotulada como 'ID' que representa um token de ID. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". À sua esquerda está uma forma de hexágono rotulada 'A' que representa um token de acesso. Uma seta conecta as formas à esquerda às formas à direita. Segundo título do diagrama: A API original executa a validação e a imposição de token. Se tudo estiver bom, a API prossegue e atende a solicitação. Componentes do segundo diagrama: uma representação de uma nuvem aparece no centro superior do slide que inclui um ícone de ID do Microsoft Entra. No canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há uma forma de hexágono rotulada como 'ID' que representa um token de ID. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. Uma seta conecta as formas à esquerda às formas à direita. Acima da seta, à direita e abaixo da forma de nuvem, há uma forma de hexágono rotulada como 'A' que representa um token de acesso.

A API original não pode utilizar o token de acesso para chamar a API Downstream

A animação a seguir mostra que a API Original agora deseja chamar uma API Downstream. No entanto, a API Original não pode utilizar o token de acesso para chamar a API Downstream.

O diagrama animado mostra dois diagramas com uma transição de movimento entre o primeiro diagrama e o segundo diagrama. Primeiro título do diagrama: A API Original deseja chamar uma API Downstream. Primeiros componentes do diagrama: uma representação de uma nuvem aparece no centro superior do slide que inclui um ícone de ID do Microsoft Entra. No canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há uma forma de hexágono rotulada como 'ID' que representa um token de ID. No meio inferior, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. Uma seta conecta as formas à esquerda às formas no meio. Acima da seta, à esquerda e abaixo da forma de nuvem, há uma forma de hexágono rotulada 'A' que representa um token de acesso. Segundo título do diagrama: A API Original não pode utilizar o token para chamar a API Downstream. Componentes do segundo diagrama: uma representação de uma nuvem aparece no centro superior do slide que inclui um ícone de ID do Microsoft Entra. No canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há uma forma de hexágono rotulada como 'ID' que representa um token de ID. No meio inferior, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. Uma seta conecta as formas à esquerda às formas no meio. Acima da seta, à esquerda e abaixo da forma de nuvem, há uma forma de hexágono rotulada 'A' que representa um token de acesso. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Downstream. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas no meio às formas à direita.

API original volta para o Microsoft Entra ID

Na animação abaixo, a API Original precisa voltar para o Microsoft Entra ID. Ele precisa de um token de acesso para chamar a API Downstream em nome do usuário.

O diagrama animado mostra dois diagramas com uma transição de movimento entre o primeiro diagrama e o segundo diagrama. Primeiro título do diagrama: A API Original não pode utilizar o token para chamar a API Downstream. Primeiros componentes do diagrama: uma representação de uma nuvem aparece no centro superior do slide que inclui um ícone de ID do Microsoft Entra. No canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há uma forma de hexágono rotulada como 'ID' que representa um token de ID. No meio inferior, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. Uma seta conecta as formas à esquerda às formas no meio. Acima da seta, à esquerda e abaixo da forma de nuvem, há uma forma de hexágono rotulada 'A' que representa um token de acesso. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Downstream. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas no meio às formas à direita. Segundo título do diagrama: A API original volta para o Microsoft Entra ID. Subtítulo do segundo diagrama: Precisa de um token de acesso para chamar a API Downstream em nome do usuário. Componentes do segundo diagrama: uma representação de uma nuvem aparece no centro superior do slide que inclui um ícone de ID do Microsoft Entra. No canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há uma forma de hexágono rotulada como 'ID' que representa um token de ID. No meio inferior, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. Uma seta conecta as formas à esquerda às formas no meio. Acima da seta, à esquerda e abaixo da forma de nuvem, há uma forma de hexágono rotulada 'A' que representa um token de acesso. Acima das formas originais da API, uma seta as conecta à forma de nuvem do Microsoft Entra. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Downstream. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas no meio às formas à direita.

A próxima animação mostra a API Original fornecendo o token que a API Original recebeu do Aplicativo Cliente e as credenciais de cliente da API Original.

O diagrama animado mostra dois diagramas com uma transição de movimento entre o primeiro diagrama e o segundo diagrama. Primeiro título do diagrama: A API original remonta ao Microsoft Entra ID. Primeiro subtítulo do diagrama: Precisa de um token de acesso para chamar a API Downstream em nome do usuário. Primeiros componentes do diagrama: uma representação de uma nuvem aparece no centro superior do slide que inclui um ícone de ID do Microsoft Entra. No canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há uma forma de hexágono rotulada como 'ID' que representa um token de ID. No meio inferior, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. Uma seta conecta as formas à esquerda às formas no meio. Acima da seta, à esquerda e abaixo da forma de nuvem, há uma forma de hexágono rotulada 'A' que representa um token de acesso. Acima das formas originais da API, uma seta as conecta à forma de nuvem do Microsoft Entra. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Downstream. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas no meio às formas à direita. Segundo título do diagrama: A API original volta para o Microsoft Entra ID. Subtítulo do segundo diagrama: fornece o token do aplicativo cliente e as credenciais para a API original. Componentes do segundo diagrama: uma representação de uma nuvem aparece no centro superior do slide que inclui um ícone de ID do Microsoft Entra. No canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há uma forma de hexágono rotulada como 'ID' que representa um token de ID. No meio inferior, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. Uma seta conecta as formas à esquerda às formas no meio. Acima das formas originais da API, uma seta as conecta à forma de nuvem do Microsoft Entra. À esquerda dessa seta, à esquerda e abaixo da forma de nuvem, há uma forma de hexágono rotulada como 'A' que representa um token de acesso. Abaixo do token de acesso há uma forma de chave. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Downstream. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas no meio às formas à direita.

O Microsoft Entra ID verificará se há coisas como consentimento ou imposição de acesso condicional. É possível ter que voltar ao seu cliente de chamada e fornecer um motivo para não ser capaz de obter o token. Normalmente, você utilizaria um processo de desafio de declarações para retornar ao aplicativo de chamada com informações sobre o consentimento não recebido (como estar relacionado a políticas de acesso condicional).

Microsoft Entra ID executa verificações

Na animação a seguir, o Microsoft Entra ID executa suas verificações. Se tudo estiver bem, o Microsoft Entra ID emitirá um token de acesso à API Original para chamar a API Downstream em nome do usuário.

O diagrama animado mostra dois diagramas com uma transição de movimento entre o primeiro diagrama e o segundo diagrama. Primeiro título do diagrama: A API original remonta ao Microsoft Entra ID. Primeiro subtítulo do diagrama: fornece o token do aplicativo cliente e as credenciais para a API original. Primeiros componentes do diagrama: uma representação de uma nuvem aparece no centro superior do slide que inclui um ícone de ID do Microsoft Entra. No canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há uma forma de hexágono rotulada como 'ID' que representa um token de ID. No meio inferior, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. Uma seta conecta as formas à esquerda às formas no meio. Acima das formas originais da API, uma seta as conecta à forma de nuvem do Microsoft Entra. À esquerda dessa seta, à esquerda e abaixo da forma de nuvem, há uma forma de hexágono rotulada como 'A' que representa um token de acesso. Abaixo do token de acesso há uma forma de chave. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Downstream. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas no meio às formas à direita. Segundo título do diagrama: Microsoft Entra ID verifica o acesso condicional, consentimento, etc. Segundo título do diagrama: A API Original recebe seu próprio token de acesso para chamar a API Downstream em nome do usuário que entrou no Aplicativo Cliente. Componentes do segundo diagrama: uma representação de uma nuvem aparece no centro superior do slide que inclui um ícone de ID do Microsoft Entra. No canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há uma forma de hexágono rotulada como 'ID' que representa um token de ID. No meio inferior, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. Uma seta conecta as formas à esquerda às formas no meio. Acima das formas originais da API, uma seta as conecta à forma de nuvem do Microsoft Entra. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Downstream. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas no meio às formas à direita. Acima dessa seta, à direita das formas da API Original, há uma forma de hexágono rotulada como 'A' que representa um token de acesso.

A API original tem contexto de usuário com fluxo On-Behalf-Of

A animação abaixo ilustra o processo de fluxo On-Behalf-Of (OBO) que permite que uma API continue a ter o contexto do usuário à medida que ela chama a API Downstream.

O diagrama animado mostra dois diagramas com uma transição de movimento entre o primeiro diagrama e o segundo diagrama. Primeiro título do diagrama: O processo de fluxo On-Behalf-Of permite que a API Original continue a ter contexto de usuário como ela chama a API Downstream. Primeiros componentes do diagrama: no canto inferior esquerdo, uma forma de retângulo representa o Aplicativo Cliente. Abaixo do retângulo do Aplicativo Cliente há uma forma de hexágono rotulada como 'ID' que representa um token de ID. No meio inferior, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. Uma seta conecta as formas à esquerda às formas no meio. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Downstream. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas no meio às formas à direita. Acima dessa seta, à direita das formas da API Original, há uma forma de hexágono rotulada como 'A' que representa um token de acesso. Segundo título do diagrama: O processo de fluxo On-Behalf-Of permite que a API Original continue a ter contexto de usuário como ela chama a API Downstream. Componentes do segundo diagrama: no canto inferior esquerdo, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Downstream. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas à esquerda às formas à direita. Acima dessa seta, à direita das formas da API Original, há uma forma de hexágono rotulada como 'A' que representa um token de acesso.

API original chama API Downstream

Na próxima animação, chamamos a API Downstream. O token que a API Downstream recebe terá a declaração de audiência apropriada (aud) que indica a API Downstream.

O diagrama animado mostra dois diagramas com uma transição de movimento entre o primeiro diagrama e o segundo diagrama. Primeiro título do diagrama: O processo de fluxo On-Behalf-Of permite que a API Original continue a ter contexto de usuário como ela chama a API Downstream. Primeiros componentes do diagrama: no canto inferior esquerdo, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Downstream. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas à esquerda às formas à direita. Acima dessa seta, à direita das formas da API Original, há uma forma de hexágono rotulada como 'A' que representa um token de acesso. Segundo título do diagrama: A API Downstream é chamada. Segundo subtítulo do diagrama: O token que a API Downstream recebe tem declarações apropriadas para identificar o usuário do Aplicativo Cliente. Componentes do segundo diagrama: no canto inferior esquerdo, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Downstream. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas à esquerda às formas à direita. Acima dessa seta, à esquerda da forma Autorização Requerida, há uma forma de hexágono rotulada como 'A' que representa um token de acesso.

O token incluirá os escopos para consentimento concedido e a identidade do usuário do aplicativo original. A API Downstream pode implementar corretamente permissões efetivas para garantir que o usuário identificado tenha permissão para realizar a tarefa solicitada. Você desejará utilizar o em nome do fluxo para adquirir tokens para uma API chamar outra API para garantir que o contexto do usuário passe para todas as APIs Downstream.

Melhor opção: a API original executa o fluxo em nome de

Essa última animação mostra que a melhor opção é que a API Original execute o fluxo On-Behalf-Of (OBO). Se a API Downstream receber o token correto, ela poderá responder corretamente.

O diagrama animado mostra dois diagramas com uma transição de movimento entre o primeiro diagrama e o segundo diagrama. Primeiro título do diagrama: A API Downstream é chamada. Primeiro subtítulo do diagrama: O token que a API Downstream recebe tem declarações apropriadas para identificar o usuário do Aplicativo Cliente. Primeiros componentes do diagrama: no canto inferior esquerdo, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Downstream. À sua esquerda, um rótulo de forma quadrada é "Autorização necessária". Uma seta conecta as formas à esquerda às formas à direita. Acima dessa seta, à esquerda da forma Autorização Requerida, há uma forma de hexágono rotulada como 'A' que representa um token de acesso. Segundo título do diagrama: A melhor opção é que a API Original seja executada "em nome do fluxo". Se a API Downstream receber o token correto, ela poderá responder corretamente. Componentes do segundo diagrama: no canto inferior esquerdo, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Original. No canto inferior direito, um ícone em forma de cubo, uma forma de nuvem e um ícone de mundo representam a API Downstream. Uma seta conecta as formas à esquerda às formas à direita. Acima dessa seta, à esquerda das formas da API Downstream, há uma forma de hexágono rotulada como 'A' que representa um token de acesso.

Quando uma API está agindo em nome de um usuário e precisa chamar outra API, a API deve utilizar OBO para adquirir um token de acesso de permissão delegada para chamar a API Downstream em nome do usuário. As APIs nunca devem utilizar permissões de aplicativo para chamar APIs Downstream quando a API estiver agindo em nome de um usuário.

Próximas etapas

• O artigo Cenários de autenticação e cenários de aplicativo da plataforma de identidade da Microsoft descreve os fluxos de autenticação e os cenários de aplicativo nos quais eles são usados.
• O artigo Proteção de APIs descreve as práticas recomendadas para proteger sua API por meio de registro, definição de permissões e consentimento e imposição de acesso para atingir as metas de Confiança Zero.
• O artigo Exemplo de API protegida pela estrutura de consentimento de identidade da Microsoft ajuda você a projetar estratégias de permissões de aplicativos com privilégios mínimos para oferecer a melhor experiência do usuário.
• O artigo Personalizar tokens descreve informações que você pode receber nos tokens do Microsoft Entra e como personalizar tokens para melhorar a flexibilidade e o controle e, ao mesmo tempo, aumentar a segurança de confiança zero do aplicativo com privilégios mínimos.
• O módulo de aprendizado Proteger APIs personalizadas com identidade da Microsoft explica como proteger uma API Web com a identidade da Microsoft e como chamá-la de outro aplicativo.
• O artigo Práticas recomendadas de segurança para propriedades de aplicativos descreve o URI de redirecionamento, tokens de acesso (usados para fluxos implícitos), certificados e segredos, URI de ID do aplicativo e propriedade de aplicativos.
• O artigo Bibliotecas de autenticação de plataforma de identidade da Microsoft descreve o suporte da Biblioteca de Autenticação da Microsoft para vários tipos de aplicativos.