# class OAuth::Consumer

- OAuth::Consumer
- Reference
- Object

##
Overview

An OAuth consumer.

For a quick example of how to authenticate an `HTTP::Client` with OAuth if you already have an access token, check the `OAuth` module description.

This class also provides methods to get request tokens, build authorize URIs and get access tokens, as specified by RFC 5849.

###
Example

    require "oauth"

    consumer_key = "some_key"
    consumer_secret = "some_secret"
    oauth_callback = "http://some.callback"

    # Create consumer, optionally pass custom URIs if needed,
    # if the request, authorize or access_token URIs are not the standard ones
    # (they can also be absolute URLs)
    consumer = OAuth::Consumer.new("api.example.com", consumer_key, consumer_secret)

    # Get a request token.
    # We probably need to save this somewhere to get it back in the
    # callback URL (saving token and secret should be enough)
    request_token = consumer.get_request_token(oauth_callback)

    # Build an authorize URI
    authorize_uri = consumer.get_authorize_uri(request_token, oauth_callback)

    # Redirect the user to `authorize_uri`...
    #
    # ...
    #
    # When http://some.callback is hit, once the user authorized the access,
    # we resume our logic to finally get an access token. The callback URL
    # should receive an `oauth_verifier` parameter that we need to use.
    oauth_verifier = request.params["oauth_verifier"]

    # Get the access token
    access_token = consumer.get_access_token(request_token, oauth_verifier)

    # Probably save the access token for reuse... This can be done
    # with `to_json` and `from_json`.

    # Use the token to authenticate an HTTP::Client
    client = HTTP::Client.new("api.example.com", tls: true)
    access_token.authenticate(client, consumer_key, consumer_secret)

    # And do requests as usual
    client.get "/some_path"

##
Defined in:

##
Constructors

- .new(host : String, consumer_key : String, consumer_secret : String, port : Int32? = nil, scheme : String = "https", request_token_uri : String = "/oauth/request_token", authorize_uri : String = "/oauth/authorize", access_token_uri : String = "/oauth/access_token")

  Creates an OAuth consumer.

##
Instance Method Summary

- #authenticate(client : HTTP::Client, token : AccessToken) : Nil

  Authenticated an `HTTP::Client` to add an OAuth authorization header, as specified by RFC 5849, Section 3.

- #get_access_token(request_token, oauth_verifier, extra_params = nil) : AccessToken

  Gets an access token from a previously obtained request token and an oauth_verifier obtained from an authorize URI, as specified by RFC 5849, Section 2.3.

- #get_authorize_uri(request_token, oauth_callback = nil) : String

  Returns an authorize URI from a given request token to redirect the user to obtain an access token, as specified by RFC 5849, Section 2.2.

- #get_authorize_uri(request_token, oauth_callback = nil, &block : HTTP::Params::Builder -> ) : String

  Returns an authorize URI from a given request token to redirect the user to obtain an access token, as specified by RFC 5849, Section 2.2.

- #get_request_token(oauth_callback = "oob")

  Obtains a request token, also known as "temporary credentials", as specified by RFC 5849, Section 2.1.

### Instance methods inherited from class `Reference`

==(other : self)
==(other : JSON::Any)
==(other : YAML::Any)
==(other) ==, dup dup, hash(hasher) hash, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference)
same?(other : Nil) same?, to_s(io : IO) : Nil to_s

### Constructor methods inherited from class `Reference`

new new

### Instance methods inherited from class `Object`

!=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, __crystal_pseudo_! : Bool __crystal_pseudo_!, __crystal_pseudo_as(type : Class) __crystal_pseudo_as, __crystal_pseudo_as?(type : Class) __crystal_pseudo_as?, __crystal_pseudo_is_a?(type : Class) : Bool __crystal_pseudo_is_a?, __crystal_pseudo_nil? : Bool __crystal_pseudo_nil?, __crystal_pseudo_responds_to?(name : Symbol) : Bool __crystal_pseudo_responds_to?, class class, dup dup, hash(hasher)
hash hash, inspect : String
inspect(io : IO) : Nil inspect, itself itself, not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, tap(&) tap, to_json(io : IO)
to_json to_json, to_pretty_json(indent : String = " ")
to_pretty_json(io : IO, indent : String = " ") to_pretty_json, to_s : String
to_s(io : IO) : Nil to_s, to_yaml(io : IO)
to_yaml to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

### Class methods inherited from class `Object`

from_json(string_or_io, root : String)
from_json(string_or_io) from_json, from_yaml(string_or_io : String | IO) from_yaml

##
Constructor Detail

def self.new(host : String, consumer_key : String, consumer_secret : String, port : Int32? = nil, scheme : String = "https", request_token_uri : String = "/oauth/request_token", authorize_uri : String = "/oauth/authorize", access_token_uri : String = "/oauth/access_token") #

Creates an OAuth consumer.

Any or all of the customizable URIs request_token_uri, authorize_uri and access_token_uri can be relative or absolute. If they are relative, the given host, port and scheme will be used. If they are absolute, the absolute URL will be used.

##
Instance Method Detail

def authenticate(client : HTTP::Client, token : AccessToken) : Nil #

Authenticated an `HTTP::Client` to add an OAuth authorization header, as specified by RFC 5849, Section 3.

def get_access_token(request_token, oauth_verifier, extra_params = nil) : AccessToken #

Gets an access token from a previously obtained request token and an oauth_verifier obtained from an authorize URI, as specified by RFC 5849, Section 2.3.

Raises `OAuth::Error` if there was an error getting the access token.

def get_authorize_uri(request_token, oauth_callback = nil) : String #

Returns an authorize URI from a given request token to redirect the user to obtain an access token, as specified by RFC 5849, Section 2.2.

def get_authorize_uri(request_token, oauth_callback = nil, &block : HTTP::Params::Builder -> ) : String #

Returns an authorize URI from a given request token to redirect the user to obtain an access token, as specified by RFC 5849, Section 2.2.

Yields an `HTTP::Params::Builder` to add extra parameters other than those defined by the standard.

def get_request_token(oauth_callback = "oob") #

Obtains a request token, also known as "temporary credentials", as specified by RFC 5849, Section 2.1.

Raises `OAuth::Error` if there was an error getting the request token.