# class OAuth2::Client

- OAuth2::Client
- Reference
- Object

##
Overview

An OAuth2 client.

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

This class also provides methods to build authorize URIs and get access tokens with different methods, as specified by RFC 6749.

###
Example

    require "oauth2"

    client_id = "some_client_id"
    client_secret = "some_client_secret"
    redirect_uri = "http://some.callback"

    # Create oauth client, optionally pass custom URIs if needed,
    # if the authorize or token URIs are not the standard ones
    # (they can also be absolute URLs)
    oauth2_client = OAuth2::Client.new("api.example.com", client_id, client_secret,
      redirect_uri: redirect_uri)

    # Build an authorize URI
    authorize_uri = oauth2_client.get_authorize_uri

    # 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 `authorization_code` parameter that we need to use.
    authorization_code = request.params["code"]

    # Get the access token
    access_token = oauth2_client.get_access_token_using_authorization_code(authorization_code)

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

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

    # If the token expires, we can refresh it
    new_access_token = oauth2_client.get_access_token_using_refresh_token(access_token.refresh_token)

You can also use an `OAuth2::Session` to automatically refresh expired tokens before each request.

##
Defined in:

oauth2/client.cr

##
Constant Summary

DEFAULT_HEADERS = `HTTP::Headers {"Accept" => "application/json", "Content-Type" => "application/x-www-form-urlencoded"}`

##
Constructors

- .new(host : String, client_id : String, client_secret : String, port : Int32 | Nil = nil, scheme : String = "https", authorize_uri : String = "/oauth2/authorize", token_uri : String = "/oauth2/token", redirect_uri : String | Nil = nil, auth_scheme : AuthScheme = :http_basic)

  Creates an OAuth client.

##
Instance Method Summary

- #get_access_token_using_authorization_code(authorization_code : String) : AccessToken

  Gets an access token using an authorization code, as specified by RFC 6749, Section 4.1.3.

- #get_access_token_using_client_credentials(scope = nil) : AccessToken

  Gets an access token using client credentials, as specified by RFC 6749, Section 4.4.2.

- #get_access_token_using_refresh_token(refresh_token, scope = nil) : AccessToken

  Gets an access token using a refresh token, as specified by RFC 6749, Section 6.

- #get_access_token_using_resource_owner_credentials(username : String, password : String, scope = nil) : AccessToken

  Gets an access token using the resource owner credentials, as specified by RFC 6749, Section 4.3.2.

- #get_authorize_uri(scope = nil, state = nil) : String

  Builds an authorize URI, as specified by RFC 6749, Section 4.1.1.

- #get_authorize_uri(scope = nil, state = nil, &block : URI::Params::Builder -> ) : String

  Builds an authorize URI, as specified by RFC 6749, Section 4.1.1.

- #http_client : HTTP::Client

  Returns the `HTTP::Client` to use with this client.

- #http_client=(http_client : HTTP::Client | Nil)

  Sets the `HTTP::Client` to use with this client.

- #make_token_request(&block : URI::Params::Builder, HTTP::Headers -> _) : HTTP::Client::Response

  Makes a token exchange request with custom headers and form fields

- #redirect_uri : String | Nil

  Gets the redirect_uri

### 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, root : String)
from_json(string_or_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, client_id : String, client_secret : String, port : Int32 | Nil = nil, scheme : String = "https", authorize_uri : String = "/oauth2/authorize", token_uri : String = "/oauth2/token", redirect_uri : String | Nil = nil, auth_scheme : AuthScheme = :http_basic) #

Creates an OAuth client.

Any or all of the customizable URIs authorize_uri and 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.

As per https://tools.ietf.org/html/rfc6749#section-2.3.1, `AuthScheme::HTTPBasic` is the default auth_scheme (the mechanism used to transmit the client credentials to the server). `AuthScheme::RequestBody` should only be used if the server does not support HTTP Basic.

##
Instance Method Detail

def get_access_token_using_authorization_code(authorization_code : String) : AccessToken #

Gets an access token using an authorization code, as specified by RFC 6749, Section 4.1.3.

def get_access_token_using_client_credentials(scope = nil) : AccessToken #

Gets an access token using client credentials, as specified by RFC 6749, Section 4.4.2.

def get_access_token_using_refresh_token(refresh_token, scope = nil) : AccessToken #

Gets an access token using a refresh token, as specified by RFC 6749, Section 6.

def get_access_token_using_resource_owner_credentials(username : String, password : String, scope = nil) : AccessToken #

Gets an access token using the resource owner credentials, as specified by RFC 6749, Section 4.3.2.

def get_authorize_uri(scope = nil, state = nil) : String #

Builds an authorize URI, as specified by RFC 6749, Section 4.1.1.

def get_authorize_uri(scope = nil, state = nil, &block : URI::Params::Builder -> ) : String #

Builds an authorize URI, as specified by RFC 6749, Section 4.1.1.

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

def http_client : HTTP::Client #

Returns the `HTTP::Client` to use with this client.

By default, this returns a new instance every time. To reuse the same instance, one can be assigned with `#http_client=`.

def http_client=(http_client : HTTP::Client | Nil) #

Sets the `HTTP::Client` to use with this client.

def make_token_request(&block : URI::Params::Builder, HTTP::Headers -> _) : HTTP::Client::Response #

Makes a token exchange request with custom headers and form fields

def redirect_uri : String | Nil #

Gets the redirect_uri