OAuth 2.0

Authorization Code

O fluxo de Autorização de Código (Authorization Code Grant) é utilizado quando há um usuário envolvido, sendo o fluxo de authorization code utilizado primariamente para autenticar usuários na sua aplicação, além disso, também faz com que o usuário forneça as permissões necessárias (caso o usuário esteja apto para tal) na área de trabalho para que a aplicação execute as ações que ela desejar.

Por exemplo, o usuário do ecossistema iugu deseja se autenticar na aplicação “Pagamentos Online” instalada em sua área de trabalho (workspace). Para fornecer a permissão, o usuário deve estar logado no console.

Ao executar o fluxo corretamente, a aplicação “Pagamentos Online” irá receber como resposta um access token, um id token e um refresh token, concluindo o processo de autenticação do usuário em sua aplicação.

Conceitos

access token

O access token é um token JWT utilizado para autenticar uma aplicação em outra aplicação do ecossistema iugu.

id token

O id token é um token JWT utilizado para compartilhar informações de autenticação de um usuário entre o servidor authorization (Identity) da iugu e aplicações do ecossistema.

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 acesso a 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.

Fluxo

1. O usuário solicita a instalação do aplicativo.
2. O aplicativo redireciona o usuário para iugu para iniciar o processo de autorização. Neste ponto, o aplicativo solicita as permissões necessárias informadas na tela de consentimento.
3. O usuário concede as permissões, autorizando o aplicativo.
4. O aplicativo recebe uma concessão de autorização, que é uma credencial temporária que representa a autorização do usuário.
5. O aplicativo solicita um token de acesso, autenticando-se junto à iugu e apresentando a concessão de autorização recebida no passo anterior.
6. A iugu autentica o aplicativo, valida a concessão de autorização e emite um token de acesso access_token, juntamente com um token de identidade id_token e um token de renovação refresh_token.
7. O aplicativo utiliza o token de acesso para fazer solicitações à API da iugu.
8. A iugu valida o token de acesso e fornece os dados solicitados.

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

O fluxo de authorization code 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. Obter informações a respeito do usuário que se autenticou

Criar um token de estado anti-forgery

Sua aplicação deve proteger a segurança de seus usuários contra ataques de request forgery. O primeiro passo é criar um token único de session que guarda um estado compartilhado entre sua aplicação e o usuário cliente. Posteriormente, sua aplicação deverá validar o token único de session contra a resposta de autenticação enviada pelo servidor de Identity da iugu, garantindo assim que seu usuário cliente é quem realmente está fazendo a requisição e não um possível fraudador malicioso. Esse padrão de proteção é comumente conhecido como CSRF.

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

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

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 servidor de autorização iugu, com os parâmetros de URI (query strings) apropriados. Note que o uso de HTTPS é 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 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 utilizado para proteger o usuário cliente contra CSRF)

Exemplo

(endpoint /authorize)

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

Autenticação de usuários no servidor de Identity da iugu

Os usuários serão requisitados a aceitar as permissões que sua aplicação “Pagamentos Online” cadastrou na plataforma de Console da iugu, recebendo a resposta de autenticação apropriada (sucesso ou falha) no endpoint de callback cadastrado.

Confirmar o token de estado anti-forgery

Após a solicitação enviada ao autorize, caso a resposta de autenticação seja sucesso, sua aplicação receberá um request GET na rota de callback configurada, com o parâmetro 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 servidor de Identity da iugu.

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

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

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

Se o valor estiver correto, a aplicação “Pagamentos Online” deve avançar para o próximo passo e trocar o code pelo token pelo access token e o id token, enviando o código recebido no callback para a rota /token do servidor de autorização iugu.

Trocar o code pelo access token e o id token

A partir do code (um token de utilização única) obtido na resposta de autenticação sua aplicação pode obter um access token e um id token. Para efetuar esta troca é necessário enviar um request HTTPS POST ao endpoint de /token , 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

(endpoint /token)

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

Obter informações a respeito do usuário que se autenticou

Em posse das informações de identidade do usuário, sua aplicação pode oferecer uma experiência mais personalizada, por exemplo, fazendo uma query no banco de dados para buscar mais informações a respeito deste usuário e começar uma sessão para o mesmo. Para entender mais sobre os campos do JWT acesse JWT Claims.