Guia do Usuário

Criação de Aplicativo e Login

O objetivo deste guia é fornecer ao usuário desenvolvedor uma visão geral sobre as ações necessárias para criar e integrar um aplicativo próprio com a plataforma iugu. Neste guia iremos apresentar os passos para criar um novo aplicativo, fazer a integração do mesmo com a plataforma iugu e por fim realizar o login do usuário deste aplicativo usando o recurso OAuth 2.0 da plataforma.

O guia irá cobrir as seguintes fases necessárias para a integração:

• Inclusão do aplicativo no Console
• Configurações mínimas do aplicativo necessárias para integração
• Permissões do aplicativo
• Credenciais do aplicativo
• Instalação do aplicativo
• Criação de tokens para integração
• Chamadas de integração a um outro aplicativo

Inclusão do aplicativo no Console

O primeiro passo é incluir o aplicativo no Gerenciador de Aplicativos da sua Área de Trabalho. Você encontrará informações mais detalhadas sobre o Gerenciador aqui.

Em princípio você só precisará fornecer um nome para o seu novo aplicativo. No momento da inclusão o Gerenciador irá gerar automaticamente um slug e um prefixo de ações implementadas para o seu aplicativo.

Para entender melhor estes dois elementos, dê uma olhada aqui.

O slug pode ser alterado posteriormente, mas o prefixo de ações implementadas não pode ser alterado. Por isso procure usar um nome curto mas que descreva com clareza a função do seu aplicativo.

Configurações mínimas do aplicativo necessárias para integração

Para que a integração do aplicativo funcione você deverá fornecer algumas informações mínimas. São elas:

• Na opção Listagens é necessário marcar o item Emite Cobrança, para que você possa enviar chamadas de inclusão de eventos de faturamento
• Na opção Permissões inclua pelo menos uma ação consumida e uma ação implementada, para que você possa realizar testes do fluxo Verify
• Na opção Credenciais
  • Anote o ID e a chave do Cliente, que serão usadas posteriomente nas chamadas de integração
  • Coloque a URL do seu aplicativo
    • Não é necessário que esta URL esteja na Internet - em tempo de desenvolvimento você pode usar, por exemplo, http://localhost
  • Coloque as URLs de callback do seu aplicativo
    • Somente as URLs listadas aqui serão autorizadas a realizar o callback

Para maiores informações sobre os itens elencados acima consulte esta documentação. Os itens das telas do Gerenciador que não forem citados aqui, não são relevantes para o contexto desse guia e serão cobertos em outra ocasião.

Permissões do aplicativo

A definição das permissões do seu aplicativo é uma tarefa importante para garantir a segurança da integração entre o seu aplicativo e a plataforma iugu.

Você precisará definir labels de identificação para as ações implementadas no seu aplicativo via API. Desta forma, outros aplicativos que irão interagir com o seu aplicativo via API, só poderão efetuar estas ações a partir do momento em que estas sejam necessariamente autorizadas na configuração daquele aplicativo.

E também poderá incluir Ações Consumidas, que são labels de ações de outros aplicativos, as quais o seu aplicativo irá utilizar. Estas ações devem ser autorizadas explicitamente na página Permissões do seu aplicativo.

É necessário que o aplicativo esteja devidamente instalado e autorizado na sua Área de Trabalho. Você pode obter maiores informações sobre permissões aqui.

Credenciais do aplicativo

A tela de Credenciais trata dos parâmetros necessários para a comunicação entre a sua aplicação e a plataforma iugu. O ID do Cliente é público e poderá ser consultado por aqueles que desejam interagir com o seu aplicativo.

Já a Chave do Cliente é secreta e deve ser protegida. Ela será exibida apenas uma vez na interface do Console, e é sua obrigação armazená-la e protegê-la. Nem mesmo o Console iugu irá apresentar a Chave do Cliente novamente.

Caso você a perca, deverá gerar uma nova chave, e neste momento, a chave antiga ficará automaticamente invalidada. Este procedimento é necessário para a segurança da comunicação entre o seu aplicativo e a plataforma iugu.

Maiores informações sobre Credenciais você encontra aqui.

Nesta mesma tela você deverá informar a URL do seu aplicativo, onde os usuários do seu aplicativo poderão acessá-lo. Também deverá informar a URL de callback para a comunicação OAuth 2.0. Maiores informações sobre OAuth 2.0 você encontra aqui.

Instalação do aplicativo

Antes de iniciar a comunicação propriamente dita entre o seu aplicativo e a plataforma iugu, você deve instalar o seu aplicativo em uma Área de Trabalho.

O aplicativo pode ser instalado na mesma na mesma Área de Trabalho em que o aplicativo está sendo gerenciado, ou em outra qualquer. É preferível que, em tempo de desenvolvimento, você instale o aplicativo na mesma área de trabalho em que ele foi criado, para facilitar os ajustes de configurações.

No procedimento de instalação, ocorrerá uma tela de consentimento que informará ao usuário que está instalando, as permissões requeridas pelo aplicativo. Nesta tela de consentimento, o usuário deverá aceitar as permissões requeridas, para que o procedimento de instalação seja finalizado.

Ao final do procedimento, as permissões serão automaticamente configuradas no GIA, não necessitando de nenhuma interação do usuário.

Criação de tokens para integração e login OAuth 2.0

Um dos primeiros recursos que você deverá implementar no seu aplicativo é o login com OAuth 2.0. Neste procedimento, um usuário que deseje utilizar o seu aplicativo, e já esteja devidamente logado na plataforma iugu, poderá utilizar o seu aplicativo sem a necessidade de fazer o preenchimento de um cadastro de novo usuário.

Importante destacar que o seu aplicativo deverá ter algum tipo de controle próprio de usuários e de autenticação (login/logout). O OAuth 2.0 proporcionará apenas a confiabilidade e os dados básicos de usuário para que você implemente o login e a criação de novos usuários, quando necessário.

Além disso, o OAuth 2.0 possibilita que o usuário do seu aplicativo faça login com apenas um clique, tornando prática a utilização do mesmo.

É necessário implementar o login utilizando um fluxo do tipo Authorization Code do OAuth 2.0. Você encontrará informações detalhadas sobre este fluxo aqui. Nesta página há um diagrama que ajuda a entender melhor este fluxo.

Basicamente, o fluxo Authorization Code para a realização do login consiste nos passos abaixo:

1. O seu aplicativo, ao receber uma requisição GET qualquer, detecta que o usuário ainda não está logado, e retorna uma resposta com um redirecionamento (HTTP 302) para uma URL do Identity (https://identity.iugu.com/authorize)
   • Neste redirecionamento, devem ser enviados alguns parâmetros do tipo query string, conforme descrito aqui
   • Um desses parâmetros será uma string randômica (state) criada pelo seu aplicativo, que deverá ser persistida na sessão do backend do seu aplicativo, para ser usado posteriormente na verificação, na etapa de callback
     • Este parâmetro tem o propósito de evitar ataques do tipo CSRF
2. Ao receber esta requisição, o Identity criará uma token, e responderá com um HTML que fará automaticamente um GET para a URL de callback do seu aplicativo
3. O seu aplicativo deverá estar preparado para receber esta requisição GET, na URL de callback informada no Gerenciador dde Aplicativo do Console
   • Nesta requisição virão apenas dois parâmetros: code e state
   • O parâmetro state deverá ser comparado com o valor que foi criado no passo 1, logo acima
   • Caso o state seja diferente do que foi criado pelo seu aplicativo, você deverá abortar a execução, com um HTTP 403 (forbidden) por exemplo
   • O parâmetro code será usado na próxima etapa, para identificar o token requerido
4. Após verificar o state com sucesso, o seu aplicativo deverá efetuar uma outra chamada ao Identity, desta vez na URL de geração de token (https://identity.iugu.com/token)
   • Esta requisição:
     • Deve ser do tipo POST
     • Deverá ser feita pelo backend, e não enviada como resposta ao navegador
     • Deve conter o cabeçalho Content-Type = application/x-www-form-urlencoded
     • Deve conter credenciais de autenticação básica HTTP, com o ID do Cliente e a Chave do Cliente obtidas no Gerenciador de Aplicativos do Console
       • Exemplo: Authorization = Basic NjZKR0FncjlzR1NE5iU3Mx1MGQzMzNkMGRlM2ZiNDA=
     • Deve conter no body payload os parâmetros descritos aqui
       • É importante destacar que aqui, quando o parâmetro audience não é enviado, ou é enviado com um valor nulo, o Identity irá retornar automaticamente tokens para
   • No retorno desta requisição, o seu aplicativo receberá um Json com uma access_token, uma id_token e uma refresh_token que serão utilizadas nas requisições posteriores de comunicação com a plataforma iugu
     • O seu aplicativo deverá armazenar estas tokens de forma segura no backend, e decodificá-las quando for necessário
     • Para decodificar as tokens utilize o certificado público da plataforma iugu, disponível em formato Json na URL https://identity.iugu.com/.well-known/jwks.json
     • Na token id_token você encontrará informações sobre o usuário, como por exemplo, id, nome e email
     • É responsabilidade do seu aplicativo criar o usuário se ele não existir, e realizar o login em algum recurso de autenticação do seu aplicativo
5. Por fim, após o recebimento e armazenamento das tokens, o seu aplicativo deverá redirecionar para alguma URL do seu aplicativo, por exemplo, a URL raiz

Pronto!

Agora você já fez o login do seu usuário, e possui a token access_token, que será usada nas requisições à plataforma iugu.