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

##
Constructors

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

  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 : HTTP::Params::Builder -> ) : String

  Builds an authorize URI, as specified by RFC 6749, Section 4.1.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, client_id : String, client_secret : String, port : Int32? = nil, scheme = "https", authorize_uri = "/oauth2/authorize", token_uri = "/oauth2/token", redirect_uri : String? = nil) #

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.

##
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 : HTTP::Params::Builder -> ) : String #

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

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