O protocolo OAuth2 permite o acesso parcial ou total por terceiros sem necessidade de compartilhar a senha da conta que está compartilhando os dados. É mais complexo que acessar por usuário e senha mas é mais flexível e muito mais seguro.

Esse fluxo é recomendável para o caso da sua aplicação necessitar permissão para acesso a contas de terceiros, sejam clientes ou usuários do seu sistema, por exemplo.

O fluxo de autorização 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://app-sandbox.kobana.com.br/oauth/authorize
Token URL	POST https://app-sandbox.kobana.com.br/oauth/token

Produção	URL
Authorize URL	GET https://app.kobana.com.br/oauth/authorize
Token URL	POST https://app.kobana.com.br/oauth/token

Resumo do funcionamento

O fluxo de autorização requer que o usuário autorize o acesso da sua app à conta dele. Para autenticar o usuário:

Use o client_id e client_secret que você obteve conosco durante o registro para redirecionar 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** -> xxxxxxxxxx
* **Client Secret** -> yyyyyyyyyy
* **Redirect URL** -> http://seusite.com.br

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

https://app-sandbox.kobana.com.br/oauth/authorize?response_type=code&client_id=xxxxxxxxxx&redirect_uri=http://seusite.com.br

client_id = 'xxxxxxxxxx'
client_secret = 'yyyyyyyyyy'
redirect_url = 'http://seusite.com.br'
client = OAuth2::Client.new(client_id, client_secret, site: 'https://app-sandbox.kobana.com.br')

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://app-sandbox.kobana.com.br/oauth/token?grant_type=authorization_code&code=57858ba460&redirect_uri=http://seusite.com.br&client_id=xxxxxxxxxx&client_secret=yyyyyyyyyy

curl -i \
-d 'grant_type=authorization_code&code=57858ba460&redirect_uri=http://seusite.com.br&client_id=xxxxxxxxxx&client_secret=yyyyyyyyyy' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-X POST 'https://app-sandbox.kobana.com.br/oauth/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://app-sandbox.kobana.com.br')
    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 $KOBANA_TOKEN" \
-H 'Content-Type: application/json' \
-H 'User-Agent: MyApp (myapp@example.com)' \
-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.

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.