Web API

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

• Identidade do aplicativo - Este cenário usa a concessão de credenciais de cliente OAuth 2.0 para autenticar como o aplicativo e acessar a API da Web. Ao usar uma identidade de aplicativo, a API da Web só pode detetar que o aplicativo da Web está chamando-a, pois a API da 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 da 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 - Este cenário pode ser realizado de duas maneiras: OpenID Connect e concessão de código de autorização 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 se autenticou com êxito no aplicativo Web e que o aplicativo Web foi capaz de obter uma identidade de usuário delegada para chamar a API Web. Esse token de acesso é enviado na solicitação para a API da Web, que autoriza o usuário e retorna o recurso desejado.

A identidade do aplicativo e os tipos de identidade de 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 da Web.

Diagrama

Fluxo de protocolo

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

1. Um usuário está conectado ao Azure AD no aplicativo Web (consulte a seção de aplicativos Web para obter mais informações).
2. O aplicativo Web precisa adquirir um token de acesso para que possa se autenticar na API da Web e recuperar o recurso desejado. Ele faz uma solicitação ao ponto de extremidade de token do Azure AD, fornecendo a credencial, a ID do aplicativo e o URI da 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. Por HTTPS, a aplicação web utiliza o token de acesso JWT retornado para adicionar a string JWT com a designação "Bearer" no cabeçalho Authorization do pedido à API da Web. Em seguida, a API da Web valida o token JWT e, se a validação for bem-sucedida, retorna 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 da Web em seu nome, o usuário precisará consentir. O aplicativo exibirá as permissões necessárias e, se qualquer uma delas for uma permissão de nível de administrador, um usuário normal no diretório não poderá consentir. Esse processo de consentimento só se aplica a aplicativos multilocatário, não a aplicativos de locatário único, pois o aplicativo já terá as permissões necessárias. Quando o usuário entrava, o aplicativo Web recebia 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. Por HTTPS, a aplicação web utiliza o token de acesso JWT retornado para adicionar a string JWT com a designação "Bearer" no cabeçalho Authorization do pedido à API da Web. Em seguida, a API da Web valida o token JWT e, se a validação for bem-sucedida, retorna o recurso desejado.

Identidade de usuário delegada com concessão de código de autorização 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 da Web em seu nome, o usuário precisará consentir. O aplicativo exibirá as permissões necessárias e, se qualquer uma delas for uma permissão de nível de administrador, um usuário normal no diretório não poderá consentir. Esse consentimento se aplica a aplicativos de inquilino único e multilocatário. No caso de um único locatário, um administrador pode executar o consentimento do administrador para consentir 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 recebe 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. Por HTTPS, a aplicação web utiliza o token de acesso JWT retornado para adicionar a string JWT com a designação "Bearer" no cabeçalho Authorization do pedido à API da Web. Em seguida, a API da Web valida o token JWT e, se a validação for bem-sucedida, retorna o recurso desejado.

Exemplos de código

Consulte os exemplos de código para cenários de Aplicativo Web para API Web. E volte com frequência -- novas amostras são adicionadas com frequência. Aplicação Web para API Web.

Registo na aplicação

Para registrar um aplicativo com o ponto de extremidade do Azure AD v1.0, consulte Registrar um aplicativo.

• Locatário único - Para os casos de identidade de aplicativo e identidade de usuário delegado, o aplicativo Web e a API Web devem ser registrados no mesmo diretório no Azure AD. A API da 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, o aplicativo Web precisará selecionar as permissões desejadas no menu suspenso Permissões para outros aplicativos no portal do Azure. Esta etapa não é necessária se o tipo de identidade do aplicativo estiver sendo usado.
• Multilocatário - Primeiro, a aplicação Web é configurada para indicar as permissões necessárias para funcionar corretamente. 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 para o aplicativo, que o torna disponível para sua organização. Alguns aplicativos exigem apenas permissões de nível de usuário, que qualquer usuário na organização pode consentir. Outros aplicativos exigem permissões de nível de administrador, que um usuário na organização não pode consentir. Somente um administrador de diretório pode dar consentimento para 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óximos passos

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