Constructors

Extends "Constructors" in Net::OAuth2::Profile.

Net::OAuth2::Profile::WebServer->new(%options)

 -Option           --Defined in          --Default
  auto_save                                <set token's changed flag>
  client_id          Net::OAuth2::Profile  <required>
  client_secret      Net::OAuth2::Profile  <required>
  grant_type         Net::OAuth2::Profile  'authorization_code'
  hd                 Net::OAuth2::Profile  undef
  redirect_uri                             undef
  referer                                  undef
  scope              Net::OAuth2::Profile  undef
  secrets_in_params  Net::OAuth2::Profile  <true>
  site               Net::OAuth2::Profile  undef
  state              Net::OAuth2::Profile  undef
  token_scheme       Net::OAuth2::Profile  'auth-header:Bearer'
  user_agent         Net::OAuth2::Profile  <created internally>
    

Accessors

Extends "Accessors" in Net::OAuth2::Profile.

$obj->auto_save()

$obj->bearer_token_scheme()

Inherited, see "Accessors" in Net::OAuth2::Profile

$obj->grant_type()

Inherited, see "Accessors" in Net::OAuth2::Profile

$obj->hd()

Inherited, see "Accessors" in Net::OAuth2::Profile

$obj->id()

Inherited, see "Accessors" in Net::OAuth2::Profile

$obj->redirect_uri()

$obj->referer( [$uri] )

$obj->scope()

Inherited, see "Accessors" in Net::OAuth2::Profile

$obj->secret()

Inherited, see "Accessors" in Net::OAuth2::Profile

$obj->site()

Inherited, see "Accessors" in Net::OAuth2::Profile

$obj->state()

Inherited, see "Accessors" in Net::OAuth2::Profile

$obj->user_agent()

Inherited, see "Accessors" in Net::OAuth2::Profile

Actions

Extends "Actions" in Net::OAuth2::Profile.

$obj->authorize(%options)

On initial contact of a new user, you have to redirect to the resource owner. Somewhere in the near future, your application will be contacted again by the same user but then with an authorization grant code.

Only the most common %options are listed... there may be more: read the docs on what your server expects.

 -Option       --Default
  client_id      new(client_id)
  response_type  'code'
  scope          undef
  state          undef
    

  my $auth = Net::OAuth2::Profile::WebServer->new(...);
  # From the Plack demo, included in this distribution (on CPAN)
  get '/get' => sub { redirect $auth->authorize };
  # In generic HTTP, see method authorize_response
  use HTTP::Status 'HTTP_TEMPORARY_REDIRECT';   # 307
  print HTTP::Response->new
    ( HTTP_TEMPORARY_REDIRECT => 'Get authorization grant'
    , [ Location => $auth->authorize ]
    )->as_string;

$obj->authorize_response( [$request] )

Convenience wrapper around authorize(), to produce a complete HTTP::Response object to be sent back.

$obj->get_access_token(CODE, %options)

 -Option       --Default
  client_id      new(client_id)
  client_secret  new(client_secret)
    

$obj->update_access_token($token, %options)

Ask the server for a new token. You may pass additional %options as pairs. However, this method is often triggered automatically, in which case you can to use the "refresh_token_params" option of new().

example:

  $auth->update_access_token($token);
  $token->refresh;   # nicer
    

Helpers

Extends "Helpers" in Net::OAuth2::Profile.

$obj->add_token($request, $token, $scheme)

Inherited, see "Helpers" in Net::OAuth2::Profile

$obj->build_request($method, $uri, $params)

Inherited, see "Helpers" in Net::OAuth2::Profile

$obj->params_from_response($response, $reason)

Inherited, see "Helpers" in Net::OAuth2::Profile

$obj->site_url( <$uri|$path>, $params )

Inherited, see "Helpers" in Net::OAuth2::Profile

The process

The client side of the process has three steps, nicely described in <https://tools.ietf.org/html/rfc6749|RFC6749>

1. Send an authorization request to resource owner

It needs a "client_id": usually the name of the service where you want get access to. The answer is a redirect, based on the "redirection_uri" which you usually pass on. Additional "scope", "state", and "hd" parameters can be needed or useful. The redirect will provide you with (amongst other things) a "code" parameter.

2. Translate the code into an access token

With the code, you go to an authorization server which will validate your existence. An access token (and sometimes a refresh token) are returned.

3. Address the protected resource

The access token, usually a 'bearer' token, is added to each request to the resource you want to address. The token may refresh itself when needed.

Saving the token

Your application must implement a persistent session, probably in a database or file. The session information is kept in an Net::OAuth2::AccessToken object, and does contain more facts than just the access token.

Let's discuss the three approaches.

no saving

The Plack example contained in the CPAN distribution of this module is a single process server. The tokens are administered in the memory of the process. It is nice to test your settings, but probably not realistic for any real-life application.

automatic saving

When your own code is imperative:

  my $auth = Net::OAuth2::Profile::WebServer->new
    ( ...
    , auto_save => \&save_session
    );
  sub save_session($$)
  {   my ($profile, $token) = @_;
      ...
  }

When your own code is object oriented:

  sub init(...)
  {  my ($self, ...) = @_;
     my $auth = Net::OAuth2::Profile::WebServer->new
       ( ...
       , auto_save => sub { $self->save_session(@_) }
       );
  }
  sub save_session($$)
  {   my ($self, $profile, $token) = @_;
      ...
  }

explicit saving

In this case, do not use new(auto_save).