Desafio de Autenticação Elevada (Step Up Auth Challenge)

Para que você possa proteger os recursos de sua aplicação e definir uma segurança mais refinada, a iugu oferece o Desafio de Autenticação Elevada (Step Up Authentication Challenge). Esse desafio faz parte do protocolo Oauth e é definido na RFC 9470.

Através desse desafio, você será capaz de exigir que seus usuários se autentiquem novamente para executar determinadas ações. Assim, você garante que seus usuários são quem dizem que são no momento que eles realizam uma ação importante, como alterar uma configuração de conta ou realizar uma transação financeira.

O artigo a seguir explica como você pode solicitar o desafio em sua aplicação iugu.

1. O protocolo Step Up

O fluxo do Step Up é definido da seguinte forma:

1. Client solicita um recurso protegido, utilizando um token cujo ACR não é suficiente para o acesso.
2. Servidor informa que o token apresentado não tem autenticação suficiente para acessar o recurso e informa qual tipo de autenticação é necessária.
3. Client solicita o desafio referente ao ACR necessário, informado pelo servidor.
4. Servidor retorna o desafio.
5. Client completa o desafio.
6. Servidor retorna o JWT com o ACR necessário para acessar o recurso.
7. Client solicita o mesmo recurso utilizando o JWT com o ACR de nível correto.
8. Servidor valida o nível do ACR e fornece o recurso solicitado.

2. Adicionando o Step Up na sua aplicação

Para explicar como adicionar o Step Up em seu sistema, vamos utilizar um cenário fictício:

• Imagine que sua aplicação tem uma tela que permite o usuário realizar uma trasferência bancária para a conta que desejar.

Faz sentido que nessa tela, a aplicação exija do usuário uma autenticação recente, a fim de proteger o sistema de alguém mal intencionado que pode ter se apoderado do computador do usuário e deseja transferir valores da empresa para sua conta pessoal.

Para que você possa proteger essa tela com o Step Up, são necessárias algumas etapas:

1. Configurar os scopes do seu aplicativo no console
2. Verificar se o nível do ACR no JWT do seu usuário é compatível com a ação que ele deseja fazer
3. Solicitar um desafio para o servidor de autenticação e repassar para o usuário
4. Autorizar o acesso à tela quando ele cumprir o desafio e se autenticar novamente.

2.1. Configurar os scopes do seu aplicativo no console

A iugu tem atualmente 3 níveis de grant_scopes:

• Nível 1: informations, acr: urn:iugu:grant_scopes:informations.
  • Todo JWT tem por padrão esse acr. Ele permite que os usuários leiam informações gerais da aplicação.
• Nível 2: config, acr: urn:iugu:grant_scopes:config.
  • Permite que o usuário tenha acesso ao gerenciamento de configurações da aplicação.
• Nível 3: transfers, acr: urn:iugu:grant_scopes:transfers.
  • Permite que o usuário realize transações e movimentações financeiras.

Recomendamos que você salve essas configurações no seu projeto, assim elas pode ser referenciadas no seu sistema em diferentes contextos.

2.2. Verificar se o nível do ACR no JWT do seu usuário é compatível com a ação que ele deseja fazer

Em termos de código, você deve verificar o JWT atual antes de realizar a operação. Caso o JWT não tenha o acr válido para executar a transferência, você deve solicitar um novo token no endpoint /authorize com um novo parâmetro chamado acr_values que é uma string representando o acr desejado. Além disso, também é possível passar um parâmetro max_age com um valor inteiro em segundos que representa o tempo desde a última autenticação.

Exemplo de pseudo-código em ruby

class TransfersController < BaseController
  def index
    ...
  end

  def transfer
    if valid_acr?(current_jwt)
      handle_transfer
    else
      @last_action = transfer_url
      redirect_to oauth2.authorize(
        redirect_uri: transfers_acr_callback_url,
        acr_values: "urn:iugu:grant_scopes:transfers",
        max_age: 300 # 5 minutos
      )
    end
  end

  def acr_callback
    response = oauth2.get_token(params[:code])
    current_jwt = response["access_token"]

    if executing_action?
      redirect_to @last_action # continuar operação anterior
    end
  end

  private

  def handle_transfer
    ...
  end

  def valid_acr?(jwt)
    jwt["acr"] == "urn:iugu:grant_scopes:transfers" # idealmente esse acr deve ser salvo em uma variável global
  end
end

2.3. Solicitar um desafio para o servidor de autenticação e repassar para o usuário

2.4. Autorizar o acesso à tela quando ele cumprir o desafio e se autenticar novamente.