Authorization Code

O fluxo do authorization code é utilizado quando uma aplicação web quer autenticar seus usuários.

Por exemplo, o usuário da plataforma iugu deseja utilizar a aplicação “Pagamentos Online”, mas antes, a aplicação “Pagamentos Online” precisa autenticar este usuário. Para executar a autenticação deste usuário, a “Pagamentos Online” executa o fluxo do authorization code, utilizando o Identity, assim autenticando seu usuário e permitindo que ele acesse seus recursos.

Conceitos iniciais

access token

O access token é um token JWT assinado, ou seja, utiliza um mecanismo de assinatura criptográfica para atestar sua legitmidade, ele é utilizado para autenticar uma aplicação em outra aplicação da plataforma iugu.

No caso específico do authorization code, o access token terá a claim subject sendo o usuário que efetuou o login na aplicação e o client_id será o id da aplicação que solicitou o token, ou seja, a aplicação que está executando a autenticação.

id token

O id token é um token JWT utilizado para compartilhar informações de autenticação de um usuário entre o OpenID Provider (Identity) da iugu e aplicações da plataforma. Ele contém claims específicas sobre o usuário, que está sendo autenticado.

OBS: Sua aplicação não deve compartilhar o id token com outras aplicações, o token utilizado para autenticação em outras aplicações deve ser o access token.

refresh token

O refresh token é um token utilizado para obter um novo access token depois de o access token inicial ter expirado, sem precisar da presença do usuário, para mais informações visite a seção refresh_token.

relying party

É a aplicação interessada em executar a autenticação dos seus usuário, que fará toda a comunicação com o OP (OpenID Provider)

OpenID provider

É o Identity, o servidor responsável por executar todo o processo de autenticação de usuários e aplicações, na plataforma iugu

Audience

É um parâmetro utilizado para indicar qual aplicativo deverá estar autorizado a receber o access token que for gerado no processo, ou seja, ele indica a aplicação que o relying party deseja acessar.

Fluxo detalhado

1. O usuário tenta acessar o aplicativo, sem estar autenticado.
2. O aplicativo redireciona o usuário para o Identity para iniciar o processo de autenticação.
3. O usuário executa o processo de autenticação e concede as permissões necessárias.
4. O aplicativo recebe, através da query string de sua URL de callback, um code, que será utilizado para receber o access token e o id token.
5. O aplicativo solicita um access token, autenticando-se junto ao Identity e apresentando o code, recebido no passo anterior.
6. A iugu autentica o aplicativo, valida o code e emite um access_token, juntamente do id_token e um refresh_token.
7. O aplicativo valida os tokens recebidos, tendo acesso as informações de login do usuário, para executar sua autenticação.

Ao executar o fluxo corretamente, sua aplicação irá receber como resposta um access token, um id token e um refresh token.

Passo a Passo de implementação

Implementar o fluxo de authorization code para autenticar seus usuários envolve basicamente 5 estapas:

1. Criar um token de estado anti-forgery
2. Enviar o request de autenticação pro servidor de Identity da iugu
3. Confirmar o token de estado anti-forgery
4. Trocar o code pelo access token e o id token
5. Validar os tokens e confirmar sua integridade

1 - Criar um token de estado anti-forgery

Um ataque muito comum é o request forgery, tendo isso em mente, o Identity prove um mecanismo para que sua aplicação se proteja deste tipo de ataque.

O primeiro passo é criar um token único com baixa probabilidade de ser advinhado, como base, sugerimos um hash de 1024 bytes. Este token precisa estar associado de alguma forma com a autenticação do browser do seu usuário, segurimos o uso da session, caso sua aplicação utilize esse mecanismo. O token vai representar um estado compartilhado entre sua aplicação e o usuário.

Posteriormente, sua aplicação deverá validar o token único contra a resposta de autenticação enviada pelo Identity, garantindo assim que seu usuário estará acessando sua aplicação e não a de um possível fraudador malicioso.

Para saber mais sobre este tipo de ataque, acesse CSRF.

O código abaixo demonstra como gerar e guardar esse token em uma sessão web usando o framework Ruby on Rails

state = SecureRandom.base64(1024)
cookies[:oauth_state] = state

2 - Enviar o request de autenticação pro servidor de Identity da iugu

Nesse passo sua aplicação deve redirecionar o usuário para a rota de autorização do Identity, com os parâmetros de URI (query strings) apropriados. Note que o uso de TLS é obrigatório em todos os passos desse fluxo. A URI de autenticação utilizada deve ser https://identity.iugu.com/authorize.

Parâmetros necessários

• client_id (o client id da sua aplicação obtido na página de Credenciais do painel de administração do seu aplicativo)
• response_type (para esse fluxo em específico deve ser code)
• redirect_uri (deve ser o endpoint HTTP da sua aplicação que irá receber o request de resposta de autenticação do servidor de Identity da iugu. O seu valor deve ser exatamente aquele configurado no campo de Callbacks na aba de Credenciais do menu de administração do seu aplicativo)
• state (deve incluir o valor do token único de session gerado no passo anterior)

Exemplo de request

https://identity.iugu.com/authorize?
    response_type=code&
    client_id=2pWTsl4ZyO59S1Ft5eXTwV&
    redirect_uri=https%3A//oauth2.example.com/code&
    state=a4EUklMAM8gqu7PkzwR4NwCu5yXYrls9Uhr/rnWnI7/LEor3jyRKLp5D/1PjSB1I4MdgqmzD2tzgpB0Xb0Bf2A==

3 - Confirmar o token de estado anti-forgery

Após o usuário completar a sua autenticação junto ao Identity e conceder a sua aplicação as permissões necessárias, ele será redirecionado de volta a sua URL de callback que foi cadastrada. O request terá os seguintes parâmetros de URI code, que contêm o valor do code utilizado para obter o access token e o id token. Além desse parâmetro, o parametro state enviado no request original é retornado, inalterado, pelo Identity.

Ao receber estes parâmetros, sua aplicação deverá realizar a conferência do parâmetro “state”.

Exemplo:

def verified_state?
  params[:state] == cookies[:oauth_state]
end

render plain: 'Invalid state parameter', status: :unauthorized unless verified_state?

4 - Trocar o code pelo access token e o id token

A partir do code obtido no passo anterior, sua aplicação pode obter um access token e um id token junto ao Identity. Para isto é necessário enviar um request HTTPS POST ao endpoint de /token, na URL https://identity.iugu.com/token, utilizando o header Content-Type application/x-www-form-urlencoded, header de Basic Authorization com o client_id e client_secret, enviando os seguintes parâmetros no body do request.

Parâmetros necessários

• code (token de autorização obtido na resposta de autenticação)
• redirect_uri (deve ser o endpoint HTTP da sua aplicação que irá receber o request de resposta de autenticação do servidor de Identity da iugu. O seu valor deve ser exatamente aquele configurado no campo de Callbacks na aba de Credenciais do menu de administração do seu aplicativo)
• grant_type (para este fluxo em específico deve ser authorization_code)

Exemplo

POST /token HTTP/1.1
Host: identity.iugu.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

5 - Validar os tokens e confirmar sua integridade

Em posse do id token e do access token, sua aplicação deve validar a assinatura destes tokens antes de utilizar as informações contidas neles.

Para um passo a passo de como validar estes tokens acesse esta página.

Com as informações de login contidas no id token sua aplicação já pode finalizar a autenticação do usuário.