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

oauth/consumer.cr

##
Constructors

- .new(host : String, consumer_key : String, consumer_secret : String, port : Int32 | Nil = 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 : RequestToken, oauth_verifier : String, extra_params : Hash(String, String) | Nil = 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 : RequestToken, oauth_callback : String | Nil = 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 : RequestToken, oauth_callback : String | Nil = nil, &block : URI::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 : String = "oob") : RequestToken

  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, initialize initialize, inspect(io : IO) : Nil inspect, object_id : UInt64 object_id, pretty_print(pp) : Nil pretty_print, same?(other : Reference) : Bool
same?(other : Nil) same?, to_s(io : IO) : Nil to_s

### Constructor methods inherited from class `Reference`

new new, unsafe_construct(address : Pointer, *args, **opts) : self unsafe_construct

### Class methods inherited from class `Reference`

pre_initialize(address : Pointer) pre_initialize

### Instance methods inherited from class `Object`

! : Bool !, !=(other) !=, !~(other) !~, ==(other) ==, ===(other : JSON::Any)
===(other : YAML::Any)
===(other) ===, =~(other) =~, as(type : Class) as, as?(type : Class) as?, class class, dup dup, hash(hasher)
hash hash, in?(collection : Object) : Bool
in?(*values : Object) : Bool in?, inspect(io : IO) : Nil
inspect : String inspect, is_a?(type : Class) : Bool is_a?, itself itself, nil? : Bool nil?, not_nil!(message)
not_nil! not_nil!, pretty_inspect(width = 79, newline = "\n", indent = 0) : String pretty_inspect, pretty_print(pp : PrettyPrint) : Nil pretty_print, responds_to?(name : Symbol) : Bool responds_to?, tap(&) tap, to_json(io : IO) : Nil
to_json : String to_json, to_pretty_json(indent : String = " ") : String
to_pretty_json(io : IO, indent : String = " ") : Nil to_pretty_json, to_s(io : IO) : Nil
to_s : String to_s, to_yaml(io : IO) : Nil
to_yaml : String to_yaml, try(&) try, unsafe_as(type : T.class) forall T unsafe_as

### Class methods inherited from class `Object`

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

### Macros inherited from class `Object`

class_getter(*names, &block) class_getter, class_getter!(*names) class_getter!, class_getter?(*names, &block) class_getter?, class_property(*names, &block) class_property, class_property!(*names) class_property!, class_property?(*names, &block) class_property?, class_setter(*names) class_setter, def_clone def_clone, def_equals(*fields) def_equals, def_equals_and_hash(*fields) def_equals_and_hash, def_hash(*fields) def_hash, delegate(*methods, to object) delegate, forward_missing_to(delegate) forward_missing_to, getter(*names, &block) getter, getter!(*names) getter!, getter?(*names, &block) getter?, property(*names, &block) property, property!(*names) property!, property?(*names, &block) property?, setter(*names) setter

##
Constructor Detail

def self.new(host : String, consumer_key : String, consumer_secret : String, port : Int32 | Nil = 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 : RequestToken, oauth_verifier : String, extra_params : Hash(String, String) | Nil = 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 : RequestToken, oauth_callback : String | Nil = 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 : RequestToken, oauth_callback : String | Nil = nil, &block : URI::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 `URI::Params::Builder` to add extra parameters other than those defined by the standard.

def get_request_token(oauth_callback : String = "oob") : RequestToken #

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.