Share via

API Web

  • Artigo

Aviso

Este conteúdo destina-se ao ponto final Azure AD v1.0 mais antigo. Utilize o plataforma de identidades da Microsoft para novos projetos.

As aplicações de API Web são aplicações Web que precisam de obter recursos de uma API Web. Neste cenário, existem dois tipos de identidade que a aplicação Web pode utilizar para autenticar e chamar a API Web:

  • Identidade da aplicação – este cenário utiliza a concessão de credenciais de cliente OAuth 2.0 para autenticar como aplicação e aceder à API Web. Ao utilizar uma identidade de aplicação, a API Web só consegue detetar que a aplicação Web a está a chamar, uma vez que a API Web não recebe qualquer informação sobre o utilizador. Se a aplicação receber informações sobre o utilizador, será enviada através do protocolo da aplicação e não será assinada por Azure AD. A API Web confia que a aplicação Web autenticou o utilizador. Por este motivo, este padrão é denominado subsistema fidedigno.
  • Identidade de utilizador delegada – este cenário pode ser realizado de duas formas: OpenID Connect e concessão de código de autorização OAuth 2.0 com um cliente confidencial. A aplicação Web obtém um token de acesso para o utilizador, o que prova à API Web que o utilizador autenticou com êxito na aplicação Web e que a aplicação Web conseguiu obter uma identidade de utilizador delegada para chamar a API Web. Este token de acesso é enviado no pedido para a API Web, que autoriza o utilizador e devolve o recurso pretendido.

Tanto a identidade da aplicação como os tipos de identidade de utilizador delegados são abordados no fluxo abaixo. A principal diferença entre eles é que a identidade de utilizador delegado tem primeiro de adquirir um código de autorização antes de o utilizador poder iniciar sessão e obter acesso à API Web.

Diagrama

Diagrama da Aplicação Web para a API Web

Fluxo de protocolo

Identidade da aplicação com concessão de credenciais de cliente OAuth 2.0

  1. Um utilizador tem sessão iniciada para Azure AD na aplicação Web (consulte a secção Aplicações Web para obter mais informações).
  2. A aplicação Web tem de adquirir um token de acesso para que possa autenticar-se na API Web e obter o recurso pretendido. Faz um pedido ao ponto final de token do Azure AD, fornecendo a credencial, o ID da aplicação e o URI de ID da aplicação da API Web.
  3. Azure AD autentica a aplicação e devolve um token de acesso JWT que é utilizado para chamar a API Web.
  4. Através de HTTPS, a aplicação Web utiliza o token de acesso JWT devolvido para adicionar a cadeia JWT com uma designação "Portador" no cabeçalho Autorização do pedido à API Web. Em seguida, a API Web valida o token JWT e, se a validação for bem-sucedida, devolve o recurso pretendido.

Identidade de utilizador delegada com o OpenID Connect

  1. Um utilizador tem sessão iniciada numa aplicação Web com Azure AD (consulte a secção Browser para Aplicação Web acima). Se o utilizador da aplicação Web ainda não tiver consentido em permitir que a aplicação Web chame a API Web em seu nome, o utilizador terá de consentir. A aplicação apresentará as permissões necessárias e, se alguma destas permissões for ao nível do administrador, um utilizador normal no diretório não poderá consentir. Este processo de consentimento aplica-se apenas a aplicações multi-inquilino, não a aplicações de inquilino único, uma vez que a aplicação já terá as permissões necessárias. Quando o utilizador iniciou sessão, a aplicação Web recebeu um token de ID com informações sobre o utilizador, bem como um código de autorização.
  2. Com o código de autorização emitido pelo Azure AD, a aplicação Web envia um pedido para o ponto final de token do Azure AD que inclui o código de autorização, detalhes sobre a aplicação cliente (ID da Aplicação e URI de redirecionamento) e o recurso pretendido (URI do ID da aplicação para a API Web).
  3. O código de autorização e as informações sobre a aplicação Web e a API Web são validados por Azure AD. Após a validação bem-sucedida, Azure AD devolve dois tokens: um token de acesso JWT e um token de atualização JWT.
  4. Através de HTTPS, a aplicação Web utiliza o token de acesso JWT devolvido para adicionar a cadeia JWT com uma designação "Portador" no cabeçalho Autorização do pedido à API Web. Em seguida, a API Web valida o token JWT e, se a validação for bem-sucedida, devolve o recurso pretendido.

Identidade de utilizador delegada com concessão de código de autorização OAuth 2.0

  1. Um utilizador já tem sessão iniciada numa aplicação Web, cujo mecanismo de autenticação é independente do Azure AD.
  2. A aplicação Web requer um código de autorização para adquirir um token de acesso, pelo que emite um pedido através do browser para Azure AD ponto final de autorização, fornecendo o ID da Aplicação e redirecionando o URI para a aplicação Web após a autenticação com êxito. O utilizador inicia sessão no Azure AD.
  3. Se o utilizador da aplicação Web ainda não tiver consentido em permitir que a aplicação Web chame a API Web em seu nome, o utilizador terá de consentir. A aplicação apresentará as permissões necessárias e, se alguma destas permissões for ao nível do administrador, um utilizador normal no diretório não poderá consentir. Este consentimento aplica-se à aplicação única e multi-inquilino. No único caso de inquilino, um administrador pode dar consentimento ao administrador para dar consentimento em nome dos respetivos utilizadores. Isto pode ser feito com o Grant Permissions botão no portal do Azure.
  4. Depois de o utilizador ter consentido, a aplicação Web recebe o código de autorização de que precisa para adquirir um token de acesso.
  5. Com o código de autorização emitido pelo Azure AD, a aplicação Web envia um pedido para o ponto final de token do Azure AD que inclui o código de autorização, detalhes sobre a aplicação cliente (ID da Aplicação e URI de redirecionamento) e o recurso pretendido (URI do ID da aplicação para a API Web).
  6. O código de autorização e as informações sobre a aplicação Web e a API Web são validados por Azure AD. Após a validação bem-sucedida, Azure AD devolve dois tokens: um token de acesso JWT e um token de atualização JWT.
  7. Através de HTTPS, a aplicação Web utiliza o token de acesso JWT devolvido para adicionar a cadeia JWT com uma designação "Portador" no cabeçalho Autorização do pedido à API Web. Em seguida, a API Web valida o token JWT e, se a validação for bem-sucedida, devolve o recurso pretendido.

Exemplos de código

Veja os exemplos de código para cenários de APLICAÇÃO Web para API Web. E, verifique com frequência- são adicionados novos exemplos com frequência. Aplicação Web para a API Web.

Registo de aplicações

Para registar uma aplicação no ponto final Azure AD v1.0, consulte Registar uma aplicação.

  • Inquilino único – tanto na identidade da aplicação como nos casos de identidade de utilizador delegados, a aplicação Web e a API Web têm de estar registadas no mesmo diretório no Azure AD. A API Web pode ser configurada para expor um conjunto de permissões, que são utilizadas para limitar o acesso da aplicação Web aos respetivos recursos. Se estiver a ser utilizado um tipo de identidade de utilizador delegado, a aplicação Web tem de selecionar as permissões pretendidas no menu pendente Permissões para outras aplicações no portal do Azure. Este passo não é necessário se o tipo de identidade da aplicação estiver a ser utilizado.
  • Multi-inquilino – em primeiro lugar, a aplicação Web está configurada para indicar as permissões necessárias para estar funcional. Esta lista de permissões necessárias é apresentada numa caixa de diálogo quando um utilizador ou administrador no diretório de destino dá consentimento à aplicação, o que a torna disponível para a respetiva organização. Algumas aplicações apenas necessitam de permissões ao nível do utilizador, que qualquer utilizador na organização pode consentir. Outras aplicações requerem permissões ao nível do administrador, às quais um utilizador na organização não pode consentir. Apenas um administrador de diretórios pode dar consentimento a aplicações que necessitem deste nível de permissões. Quando o utilizador ou administrador consente, a aplicação Web e a API Web são registadas no respetivo diretório.

Expiração do token

Quando a aplicação Web utiliza o respetivo código de autorização para obter um token de acesso JWT, também recebe um token de atualização JWT. Quando o token de acesso expirar, o token de atualização pode ser utilizado para reautentorizar o utilizador sem exigir que iniciem sessão novamente. Este token de atualização é utilizado para autenticar o utilizador, o que resulta num novo token de acesso e token de atualização.

Passos seguintes