GitHub release Build Status License Docs

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. 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:

    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.

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.

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.

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.

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

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