OAuth2
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
Sandbox | URL |
---|---|
Authorize URL | GET https://api-sandbox.kobana.com.br/v1/oauth2/authorize |
Token URL | POST https://api-sandbox.kobana.com.br/v1/oauth2/token |
Produção | URL |
---|---|
Authorize URL | GET https://api.kobana.com.br/v1/oauth2/authorize |
Token URL | POST https://api.kobana.com.br/v1/oauth2/token |
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
eclient_secret
que você obteve conosco durante o registro para redircionar o usuário para aAuthorize URL
. Opcionalmente inclua oscope
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âmetrocode
. - Use o parâmetro
code
recebido para gerar umaccess_token
fazendo uma requisição noToken URL
. - Use o
access_token
para fazer as requisições em nome do usuário.
Passo a Passo detalhado
-
Considerando as seguintes informações:
- Client ID -> fc4e525ff3
- Client Secret -> 95ea9a477d
- Redirect URL -> http://seusite.com.br
-
Redirecione o usuário para o endereço abaixo.
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. -
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
Requisição: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 (myapp@example.com)' \ -X POST 'https://api-sandbox.kobana.com.br/v1/oauth2/token'
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"}
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)
-
Agora você pode usar o
access_token
para realizar chamadas a API. Esse token não expira.Requisição:curl -i \ -H "Authorization: Bearer $BOLETOSIMPLES_TOKEN" \ -H 'Content-Type: application/json' \ -H 'User-Agent: MyApp (myapp@example.com)' \ -X GET 'https://api-sandbox.kobana.com.br/v1/userinfo'
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
access_token.get('/api/v1/userinfo').body
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
:
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'Resposta:
{ "access_token":"397946a4ad90110b918c111261c184beb6cb515988688d6db9c31d5dabd03459", "token_type":"bearer", "scope":"login", "created_at":1434463054 }
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_credentialsResposta:
{ :access_token=>"397946a4ad90110b918c111261c184beb6cb515988688d6db9c31d5dabd03459", :token_type=>"bearer", :scope=>"login", :created_at=>1434492337 }
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.