O que é Fluxo de código de autorização (Authorization code flow)?

O que é o fluxo de código de autorização (authorization code flow)?

O fluxo de código de autorização (authorization code flow) (também conhecido como concessão de código de autorização), definido na OAuth 2.0 RFC 6749, seção 4.1 , é um mecanismo de autorização OAuth 2.0 amplamente utilizado que permite que aplicações obtenham um access token em nome de um utilizador. Este fluxo é particularmente adequado para aplicações confidenciais (por exemplo, aplicações web tradicionais do lado do servidor) onde o segredo do cliente pode ser armazenado com segurança.

O fluxo de código de autorização (authorization code flow) é um método robusto e seguro para obter access tokens no OAuth 2.0, tornando-o uma escolha preferida para muitas aplicações web. Compreender este fluxo é essencial para desenvolvedores que trabalham com OAuth 2.0 e integrações de API.

Como funciona o fluxo de código de autorização (authorization code flow)?

O fluxo de código de autorização (authorization code flow) envolve os seguintes passos:

1. Iniciação do fluxo: O utilizador inicia o fluxo, normalmente clicando num link ou botão na aplicação para iniciar sessão. A aplicação redireciona o utilizador para o endpoint de autorização do servidor de autorização, passando o ID do cliente, o scope solicitado, um redirect URI e um parâmetro de estado. O servidor de autorização valida os parâmetros e solicita que o utilizador se autentique na página de início de sessão do servidor de autorização.
2. Autenticação e autorização do utilizador: O utilizador autentica-se com o servidor de autorização e concede à aplicação permissão para aceder aos recursos solicitados.
3. Geração de código e redirecionamento: O servidor de autorização gera um código de autorização e redireciona o utilizador de volta para a aplicação usando o redirect URI fornecido anteriormente. O código de autorização é incluído na string de consulta do redirect URI.
4. Troca de código: A aplicação extrai o código de autorização da string de consulta e faz uma solicitação POST para o endpoint de token do servidor de autorização para trocar o código de autorização por um access token. A aplicação também deve incluir o ID do cliente, o segredo do cliente, o redirect URI e o código de autorização na solicitação.
5. Recuperação do access token: O servidor de autorização valida o código de autorização e emite um access token (e opcionalmente um refresh token) para a aplicação após validação bem-sucedida. A aplicação pode então usar o access token para fazer solicitações de API autorizadas em nome do utilizador.

Os passos podem ser ilustrados pelo seguinte diagrama de sequência:

Pedido de autenticação (Authentication request)

Os parâmetros do pedido são os seguintes:

• client_id: OBRIGATÓRIO. Identificador de cliente OAuth 2.0 válido.
• scope: OBRIGATÓRIO. Este valor especifica um conjunto de recursos que o utilizador está a solicitar ao servidor de autorização. Por exemplo, openid profile email.
• response_type: OBRIGATÓRIO. O valor deve ser code para indicar que a aplicação espera um código de autorização.
• redirect_uri: OBRIGATÓRIO. O URI para o qual a resposta de autenticação será enviada e deve corresponder exatamente ao redirect URI que o cliente pré-registrou no servidor de autorização.
• state: RECOMENDADO. Um valor opaco usado para manter o estado entre o pedido e o retorno de chamada. Também é usado para prevenir ataques de Falsificação de solicitação entre sites (CSRF) .
• nonce: OPCIONAL. Uma string aleatória usada para associar uma sessão de cliente com um ID token e para mitigar ataques de repetição.
• prompt: OPCIONAL. Lista de valores de string delimitados por espaço e sensíveis a maiúsculas e minúsculas que especifica se o servidor de autorização solicita ao utilizador final uma nova autenticação e consentimento. Os valores definidos são:
  • none: O servidor de autorização NÃO DEVE exibir quaisquer páginas de interface de utilizador de autenticação ou consentimento. Um erro é retornado se um utilizador final não estiver já autenticado ou se o cliente não tiver consentimento pré-configurado para os Claims solicitados ou não cumprir outras condições para processar o pedido. O código de erro será tipicamente login_required, interaction_required. Isto pode ser usado como um método para verificar a existência de autenticação e/ou consentimento.
  • login: O servidor de autorização DEVE solicitar ao utilizador final uma nova autenticação. Se não puder reautenticar o utilizador final, DEVE retornar um erro, tipicamente login_required.
  • consent: O servidor de autorização DEVE solicitar ao utilizador final consentimento antes de retornar informações ao cliente. Se não puder obter consentimento, DEVE retornar um erro, tipicamente consent_required.
  • select_account: O servidor de autorização DEVE solicitar ao utilizador final que selecione uma conta de utilizador. Isto permite que um utilizador final que tenha múltiplas contas no servidor de autorização selecione entre as múltiplas contas para as quais possa ter sessões atuais. Se não puder obter uma escolha de seleção de conta feita pelo utilizador final, DEVE retornar um erro, tipicamente account_selection_required.

Definição completa dos parâmetros do pedido

Exemplo de pedido de autenticação (Authentication request)

curl -X GET "https://authorization-server.com/auth" \
  -d "response_type=code" \
  -d "client_id=YOUR_APPLICATION_ID" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "scope=openid profile email" \
  -d "state=RANDOM_STRING_FOR_STATE"

Uma resposta típica de sucesso:

HTTP/1.1 302 Found
Location: https://yourapp.com/callback?
  code=YOUR_AUTHORIZATION_CODE
  &state=RANDOM_STRING_FOR_STATE

Pedido de troca de token (Token exchange request)

Uma vez que o pedido de autenticação acima seja respondido com sucesso, o cliente será automaticamente redirecionado para o callback URI https://yourapp.com/callback, com o código como um parâmetro URI.

Espera-se que o cliente obtenha e processe o code com um pedido de troca de token subsequente, a fim de trocar pelo access token.

Exemplo de pedido de troca de token (Token exchange request)

curl -X POST "https://authorization-server.com/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code=YOUR_AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "grant_type=authorization_code" \

Benefícios

• Segurança aprimorada: O segredo do cliente nunca é exposto ao navegador do utilizador, reduzindo o risco de personificação do cliente.
• Código de autorização de uso único: O código de autorização tem uma vida útil curta e só pode ser usado uma vez, reduzindo o risco de intercepção e ataques de repetição.
• Tokens de curta duração: Access tokens emitidos neste fluxo são de curta duração (tipicamente 1 hora), reduzindo o risco de acesso não autorizado se o token for comprometido.
• Refresh token: O servidor de autorização pode opcionalmente emitir um refresh token, permitindo que a aplicação obtenha um novo access token sem exigir interação do utilizador.

Qual é a diferença entre o fluxo de código de autorização (authorization code flow) e o fluxo implícito (implicit flow)?

A principal diferença entre o fluxo de código de autorização (authorization code flow) e o fluxo implícito (implicit flow) é como o access token é obtido:

• Fluxo de código de autorização (authorization code flow): A aplicação cliente recebe primeiro um código de autorização do endpoint de autorização, depois troca-o por um access token numa solicitação POST subsequente para o endpoint de token.
• Fluxo implícito (implicit flow): A aplicação cliente recebe o access token diretamente do endpoint de autorização.

Qual é a diferença entre o fluxo de código de autorização (authorization code flow) e o fluxo de credenciais do cliente (client credentials flow)?

A principal diferença entre o fluxo de código de autorização (authorization code flow) e o fluxo de credenciais do cliente (client credentials flow) é o contexto em que o fluxo é usado:

• Fluxo de código de autorização (authorization code flow): Usado quando a aplicação cliente precisa acessar recursos em nome de um utilizador. O fluxo envolve autenticação e autorização do utilizador.
• Fluxo de credenciais do cliente (client credentials flow): Usado quando a aplicação cliente precisa acessar recursos em seu próprio nome. O fluxo envolve autenticação do cliente, mas não autenticação do utilizador, sendo mais adequado para comunicação machine-to-machine.

Quais são os casos de uso típicos para o fluxo de código de autorização (authorization code flow)?

• Aplicações web tradicionais que requerem autenticação do utilizador e acesso a APIs.
• Aplicações que precisam acessar dados do utilizador de serviços de terceiros de forma segura.

Veja também

• Fluxo de dispositivo (Device flow)
• Fluxo implícito (Implicit flow)
• Fluxo de credenciais do cliente (Client credentials flow)