Nós recomendamos essa opção caso sua app necessite acessar contas de terceiros.

O protocolo OAuth2 permite o acesso parcial ou total por terceiros sem necessidade de compartilhar sua senha. É mais complexo que acessar por usuário e senha mas é mais flexível. OAuth2 funciona muito bem para aplicações web, assim como para desktop e mobile.

Bibliotecas

Há bibliotecas OAuth2 para quase todas as linguagens visto que é um protocolo amplamente utilizado na industria de software e por empresas como Google e Facebook.

Escolha uma biblioteca antes de começar.

Registro da Aplicação

Para começar você precisa cadastrar a sua aplicação. Nós te forneceremos um client_id e client_secret.

Você também deverá nos fornecer uma URL de Redirecionamento redirect_uri para o seu site.

Endpoints

Resumo do funcionamento

OAuth2 requer que o usuário autorize o acesso da sua app à conta dele. Para autenticar o usuário no OAuth2:

  • Use o client_id e client_secret que você obteve conosco durante o registro para redircionar o usuário para a Authorize URL. Opcionalmente inclua o scope para acessar alguma informação em específico.
  • Se o usuário autorizar sua app, ele será redirecionado para a redirect_uri que você configurou no registro com o parâmetro code.
  • Use o parâmetro code recebido para gerar um access_token fazendo uma requisição no Token URL.
  • Use o access_token para fazer as requisições em nome do usuário.

Passo a Passo detalhado

1. Considerando as seguintes informações:

* **Client ID** -> fc4e525ff3
* **Client Secret** -> 95ea9a477d
* **Redirect URL** -> http://seusite.com.br

2. Redirecione o usuário para o endereço de solicitação de autorização.

https://api-sandbox.kobana.com.br/v1/oauth2/authorize?response_type=code&client_id=fc4e525ff3&redirect_uri=http://seusite.com.br
client_id = 'fc4e525ff3'
client_secret = '95ea9a477d'
redirect_url = 'http://seusite.com.br'
client = OAuth2::Client.new(client_id, client_secret, site: 'https://api-sandbox.kobana.com.br/v1')

redirect_to client.auth_code.authorize_url(redirect_uri: redirect_url)

O usuário verá uma tela solicitando a autorização para a sua aplicação acessar os dados dele e com dois links, um para declinar e outro para autorizar que redirecionam para os seguintes endereços:

Caso seja declinado
http://seusite.com.br/?error=access_denied&error_description=O+dono+do+recurso+ou+servidor+de+autorização+negou+a+solicitação
Caso seja autorizado
http://seusite.com.br/?code=57858ba460

code é o código para que você possa solicitar o token de acesso.

3. Faça uma requisição POST para o endereço abaixo para receber o access token.

https://api-sandbox.kobana.com.br/v1/oauth2/token?grant_type=authorization_code&code=57858ba460&redirect_uri=http://seusite.com.br&client_id=fc4e525ff3&client_secret=95ea9a477d
curl -i \
-d 'grant_type=authorization_code&code=57858ba460&redirect_uri=http://seusite.com.br&client_id=fc4e525ff3&client_secret=95ea9a477d' \
-H 'User-Agent: MyApp ([email protected])' \
-X POST 'https://api-sandbox.kobana.com.br/v1/oauth2/token'
client_id = 'fc4e525ff3'
    client_secret = '95ea9a477d'
    redirect_url = 'http://seusite.com.br'
    code = 'código de autorização retornado'

    client = OAuth2::Client.new(client_id, client_secret, site: 'https://api-sandbox.kobana.com.br/v1')
    access_token = client.auth_code.get_token(code, redirect_uri: redirect_uri)
Resposta em caso de erro:
HTTP/1.1 401 Unauthorized
Date: Fri, 17 Oct 2014 18:39:47 GMT
Status: 401 Unauthorized
Content-Type: application/json; charset=utf-8
...

{"error":"invalid_grant","error_description":"A permissão de autorização provida é inválida, está expirada, revogada, não coincide com a URL de redirecionamento usada na requisição de autorização ou foi emitida por outro cliente."}
Resposta em caso de sucesso:
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 18:39:47 GMT
Status: 200 OK
Content-Type: application/json; charset=utf-8
...

{"access_token":"ada046e3cc","token_type":"bearer","scope":"login"}

4. Agora você pode usar o access_token para realizar chamadas a API.

Requisição
curl -i \
-H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp ([email protected])' \
-X GET 'https://api-sandbox.kobana.com.br/v1/userinfo'
access_token.get('/v1/userinfo').body
Resposta
HTTP/1.1 200 OK
Date: Fri, 17 Oct 2014 18:14:56 GMT
Status: 200 OK
...

# dados do usuário que autorizou o acesso

Você pode salvar esse token por tempo indeterminado. O token não expira.

Cadastrando contas no Boleto Simples com a API de Parceiro

Para parceiros interessados na criação de novas contas no Boleto Simples a partir do seu produto,
será necessário obter um tipo especial de token de acesso.

Para isso, cadastre a sua aplicação e obtenha o client_id e client_secret.

Depois obtenha o token de acesso usando o tipo de permissão client_credentials:

Requisição

curl https://api-sandbox.kobana.com.br/v1/oauth2/token \
-d 'grant_type=client_credentials&client_id=seu_client_id&client_secret=seu_client_secret'
require 'boletosimples'

BoletoSimples.configure do |c|
  c.environment = :sandbox
  c.application_id = 'seu_client_id'
  c.application_secret = 'seu_client_secret'
end

puts BoletoSimples.configuration.client_credentials

Resposta

{
  "access_token":"397946a4ad90110b918c111261c184beb6cb515988688d6db9c31d5dabd03459",
  "token_type":"bearer",
  "scope":"login",
  "created_at":1434463054
}

Utilize esse token na api de parceiros para criar novas contas no Boleto Simples.

Desenvolvendo aplicações para Mobile e Desktop

Se você está desenvolvendo para mobile ou desktop, você talvez não tenha uma url de redirecionamento.

Nestes casos você pode conferir as formas de se usar OAuth 2.0 para diversos tipos de devices.