Web API

Aplicativos de API Web são aplicativos Web que precisam obter recursos de uma API Web. Nesse cenário, há dois tipos de identidade que o aplicativo Web pode usar para autenticar e chamar a API Web:

• Identidade do aplicativo – Esse cenário usa a concessão de credenciais de cliente do OAuth 2.0 para autenticar como o aplicativo e acessar a API Web. Ao usar uma identidade de aplicativo, a API Web só pode detectar que o aplicativo Web o está chamando, pois a API Web não recebe nenhuma informação sobre o usuário. Se o aplicativo receber informações sobre o usuário, ele será enviado por meio do protocolo do aplicativo e não será assinado pelo Azure AD. A API Web confia que o aplicativo Web autenticou o usuário. Por esse motivo, esse padrão é chamado de subsistema confiável.
• Identidade de usuário delegada – Esse cenário pode ser realizado de duas maneiras: OpenID Connect e concessão de código de autorização do OAuth 2.0 com um cliente confidencial. O aplicativo Web obtém um token de acesso para o usuário, que prova à API Web que o usuário autenticou com êxito no aplicativo Web e que o aplicativo Web conseguiu obter uma identidade de usuário delegada para chamar a API Web. Esse token de acesso é enviado na solicitação para a API Web, que autoriza o usuário e retorna o recurso desejado.

A identidade do aplicativo e os tipos de identidade do usuário delegado são discutidos no fluxo abaixo. A principal diferença entre eles é que a identidade do usuário delegado deve primeiro adquirir um código de autorização antes que o usuário possa entrar e obter acesso à API Web.

Diagrama

Fluxo de protocolo

Identidade do aplicativo com concessão de credenciais de cliente do OAuth 2.0

1. Um usuário está conectado ao Azure AD no aplicativo Web (consulte a seção aplicativos Web para obter mais informações).
2. O aplicativo Web precisa adquirir um token de acesso para que ele possa se autenticar na API Web e recuperar o recurso desejado. Ele faz uma solicitação para o endpoint de token do Azure AD, fornecendo a credencial, o ID do aplicativo e o URI do ID do aplicativo da API da web.
3. O Azure AD autentica o aplicativo e retorna um token de acesso JWT usado para chamar a API Web.
4. Sobre HTTPS, o aplicativo web usa o token de acesso JWT retornado para adicionar a string JWT com a designação "Bearer" no cabeçalho de autorização da solicitação à API web. A API Web valida o token JWT e, se a validação for bem-sucedida, retornará o recurso desejado.

Identidade de usuário delegada com OpenID Connect

1. Um usuário está conectado a um aplicativo Web usando o Azure AD (consulte a seção Navegador da Web para Aplicativo Web acima). Se o usuário do aplicativo Web ainda não consentiu em permitir que o aplicativo Web chame a API Web em seu nome, o usuário precisará consentir. O aplicativo exibirá as permissões necessárias e, se alguma delas for permissões no nível do administrador, um usuário normal no diretório não poderá consentir. Esse processo de consentimento só se aplica a aplicativos multilocatários, não a aplicativos de locatário único, pois o aplicativo já terá as permissões necessárias. Quando o usuário entrou, o aplicativo Web recebeu um token de ID com informações sobre o usuário, bem como um código de autorização.
2. Usando o código de autorização emitido pelo Azure AD, o aplicativo Web envia uma solicitação para o ponto de extremidade de token do Azure AD que inclui o código de autorização, detalhes sobre o aplicativo cliente (ID do aplicativo e URI de redirecionamento) e o recurso desejado (URI da ID do aplicativo para a API Web).
3. O código de autorização e as informações sobre o aplicativo Web e a API Web são validados pelo Azure AD. Após a validação bem-sucedida, o Azure AD retorna dois tokens: um token de acesso JWT e um token de atualização JWT.
4. Sobre HTTPS, o aplicativo web usa o token de acesso JWT retornado para adicionar a string JWT com a designação "Bearer" no cabeçalho de autorização da solicitação à API web. A API Web valida o token JWT e, se a validação for bem-sucedida, retornará o recurso desejado.

Identidade de usuário delegada com concessão de código de autorização do OAuth 2.0

1. Um usuário já está conectado a um aplicativo Web, cujo mecanismo de autenticação é independente do Azure AD.
2. O aplicativo Web requer um código de autorização para adquirir um token de acesso, portanto, ele emite uma solicitação por meio do navegador para o ponto de extremidade de autorização do Azure AD, fornecendo a ID do aplicativo e o URI de redirecionamento para o aplicativo Web após a autenticação bem-sucedida. O usuário entra no Azure AD.
3. Se o usuário do aplicativo Web ainda não consentiu em permitir que o aplicativo Web chame a API Web em seu nome, o usuário precisará consentir. O aplicativo exibirá as permissões necessárias e, se alguma delas for permissões no nível do administrador, um usuário normal no diretório não poderá consentir. Esse consentimento se aplica a aplicativos individuais e multilocatários. No caso de locatário único, um administrador pode conceder consentimento administrativo em nome de seus usuários. Isso pode ser feito usando o Grant Permissions botão no portal do Azure.
4. Depois que o usuário consentir, o aplicativo Web receberá o código de autorização necessário para adquirir um token de acesso.
5. Usando o código de autorização emitido pelo Azure AD, o aplicativo Web envia uma solicitação para o ponto de extremidade de token do Azure AD que inclui o código de autorização, detalhes sobre o aplicativo cliente (ID do aplicativo e URI de redirecionamento) e o recurso desejado (URI da ID do aplicativo para a API Web).
6. O código de autorização e as informações sobre o aplicativo Web e a API Web são validados pelo Azure AD. Após a validação bem-sucedida, o Azure AD retorna dois tokens: um token de acesso JWT e um token de atualização JWT.
7. Sobre HTTPS, o aplicativo web usa o token de acesso JWT retornado para adicionar a string JWT com a designação "Bearer" no cabeçalho de autorização da solicitação à API web. A API Web valida o token JWT e, se a validação for bem-sucedida, retornará o recurso desejado.

Exemplos de código

Consulte os exemplos de código para cenários de Aplicativo Web para API Web. E, verifique com frequência : novos exemplos são adicionados com frequência. Aplicativo Web para API Web.

Registro do aplicativo

Para registrar um aplicativo no endpoint do Azure AD v1.0, consulte Registrar um aplicativo.

• Locatário único – para a identidade do aplicativo e os casos de identidade do usuário delegado, o aplicativo Web e a API Web devem ser registrados no mesmo diretório no Azure AD. A API Web pode ser configurada para expor um conjunto de permissões, que são usadas para limitar o acesso do aplicativo Web aos seus recursos. Se um tipo de identidade de usuário delegado estiver sendo usado, a aplicação Web precisará selecionar as permissões desejadas no menu suspenso Permissões para outros aplicativos no portal do Azure. Essa etapa não será necessária se o tipo de identidade do aplicativo estiver sendo usado.
• Multiusuário – primeiro, o aplicativo web é configurado para indicar as permissões necessárias para ser funcional. Essa lista de permissões necessárias é mostrada em uma caixa de diálogo quando um usuário ou administrador no diretório de destino dá consentimento ao aplicativo, o que o disponibiliza para sua organização. Alguns aplicativos exigem apenas permissões no nível do usuário, às quais qualquer usuário da organização pode consentir. Outros aplicativos exigem permissões no nível do administrador, às quais um usuário da organização não pode consentir. Somente um administrador de diretório pode dar consentimento a aplicativos que exigem esse nível de permissões. Quando o usuário ou administrador consente, o aplicativo Web e a API Web são registrados em seu diretório.

Expiração do token

Quando o aplicativo Web usa seu código de autorização para obter um token de acesso JWT, ele também recebe um token de atualização JWT. Quando o token de acesso expira, o token de atualização pode ser usado para autenticar novamente o usuário sem exigir que ele entre novamente. Esse token de atualização é usado para autenticar o usuário, o que resulta em um novo token de acesso e token de atualização.

Próximas etapas

• Saiba mais sobre outros tipos e cenários de aplicativos
• Saiba mais sobre as noções básicas de autenticação do Azure AD