simple_oauth

This README is the one indexed from the repository at its latest ref, not from the tag for this version.

[![GitHub release](https://img.shields.io/github/release/lbarasti/simple_oauth.svg)](https://github.com/lbarasti/simple_oauth/releases)
![Build Status](https://github.com/lbarasti/simple_oauth/workflows/build/badge.svg)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Docs](https://img.shields.io/badge/docs-available-brightgreen.svg)](https://lbarasti.github.io/simple_oauth)

# simple_oauth

A minimal implementation of the OAuth specification designed to build OAuth1.0 flows quickly.

`SimpleOAuth` offers a small subset of the capabilities of its counterpart in the [Crystal standard library](https://crystal-lang.org/api/latest/OAuth.html). It makes it easier to swap HTTP client and is simpler to navigate - by means of being a lot smaller.

## Installation

1. Add the dependency to your `shard.yml`:

   ```yaml
   dependencies:
     simple_oauth:
       github: lbarasti/simple_oauth
   ```

2. Run `shards install`

## Usage

Just extend `SimpleOAuth::Consumer` and define the request, authenticate and access token URLs as class variables.
```crystal
require "simple_oauth"

class TumblrAPI < SimpleOAuth::Consumer
  @@request_token_url = "https://www.tumblr.com/oauth/request_token"
  @@authenticate_url = "https://www.tumblr.com/oauth/authorize"
  @@access_token_url = "https://www.tumblr.com/oauth/access_token"
end
```

#### Initializing a consumer client
You can now create a consumer client, provided a consumer key, a secret and a callback URL. You can get these from your OAuth provider.

```crystal
consumer_key = ENV["TUMBLR_CONSUMER_KEY"]
consumer_secret = ENV["TUMBLR_CONSUMER_SECRET"]
callback_url = ENV["TUMBLR_CALLBACK_URL"]

consumer = TumblrAPI.new(consumer_key, consumer_secret, callback_url)
```

#### Requesting an OAuth Request Token
When a user requests to sign in with a selected OAuth provider, the first step for your app is to ask the provider for an OAuth Requests Token.
```crystal
request_token = consumer.get_token
```
Your app will then redirect the user to a provider-owned login screen - `TumblrAPI.authenticate_url(request_token)` in this example - where they can authorize your app to issue requests on their behalf.

#### Upgrading to an OAuth Access Token
After the sign-in, the user is redirected to your app via a white-listed callback URL. With the parameters included in the request, your app can now upgrade the request token to an access one.
```crystal
access_token = consumer.upgrade_token(request_token, verifier)
```

#### How does this work in practice?
Check out the `/examples` folder to see the big picture. For example
```
cd example/tumblr_integration
shards install
crystal src/server.cr # now head to localhost:8090
```

![tumblr demo](examples/tumblr_integration/oauth_flow.gif)

## Contributing

1. Fork it (<https://github.com/lbarasti/simple_oauth/fork>)
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create a new Pull Request

## Contributors

- [lbarasti](https://github.com/lbarasti) - creator and maintainer