NAME

Net::OAuth2::AccessToken - OAuth2 bearer token

SYNOPSIS

my $auth    = Net::OAuth2::Profile::WebServer->new(...);

my $session = $auth->get_access_token($code, ...);
# $session is a Net::OAuth2::AccessToken object
if($session->error)
{   print $session->error_description;
}

my $response = $session->get($request);
my $response = $session->get($header, $content);
print $session->to_string;  # JSON

# probably better to set new(auto_refresh), but you may do:
$session->refresh if $session->expired;

DESCRIPTION

This object represents a received (bearer) token, and offers ways to use it and maintain it. A better name for this module would include client or session.

A "bearer token" is an abstract proof of your existence: different services or potentially different physical servers are able to exchange information about your session based on this, for instance whether someone logged-in while showing the token.

METHODS

Constructors

Net::OAuth2::AccessToken->new(%options)

-Option           --Default
 access_token       undef
 auto_refresh       <false>
 changed            <false>
 error              undef
 error_description  <value of error>
 error_uri          undef
 expires_at         undef
 expires_in         undef
 profile            <required>
 refresh_always     BOOLEAN
 refresh_token      false
 scope              undef
 token_type         undef

access_token => STRING

auto_refresh => BOOLEAN

Refresh the token when expired.

changed => BOOLEAN

[0.52] The token (session) needs to be saved.

error => STRING

Set when an error has occured, the token is not valid. This is not numerical.

error_description => STRING

A humanly readible explanation on the error. This defaults to the string set with the error option, which is not nice to read.

error_uri => URI

Where to find more details about the error.

expires_at => TIMESTAMP

Expire this token after TIMESTAMP (as produced by the time() function)

expires_in => SECONDS

Expire the token SECONDS after the initiation of this object.

profile => Net::OAuth2::Profile object

refresh_always => BOOLEAN

[0.53] Auto-refresh the token at each use.

refresh_token => STRING

[0.53] Token which can be used to refresh the token, after it has expired or earlier.

scope => URL

token_type => TYPE

Net::OAuth2::AccessToken->session_thaw($session, %options)

Pass in the output of a session_freeze() call in the past (maybe even for an older version of this module) and get the token object revived. This $session is a HASH.

You may pass any of the parameters for new() as %options, to overrule the values inside the $session.

-Option --Default
 profile  <required>

profile => Net::OAuth2::Profile object

example:

my $auth    = Net::OAuth2::Profile::WebServer->new(...);
my $token   = $auth->get_access_token(...);
my $session = $token->session_freeze;
# now save $session in database or file
...
# restore session
my $auth    = Net::OAuth2::Profile::WebServer->new(...);
my $token   = Net::OAuth2::AccessToken->session_thaw($session
  , profile => $auth);

Accessors

$obj->access_token()

Returns the (base64 encoded version of the) access token. The token will get updated first, if it has expired and refresh_token is enabled, or when new(auto_refresh) is set.

It does not matter that the token is base64 encoded or not: it will always need to be base64 encoded during transport.

$obj->attribute(NAME)

[0.58] Sometimes, the token gets attributes which are not standard; they have no official accessor (yet?). You can get them with this generic accessor.

$obj->changed( [BOOLEAN] )

[0.52] The session (token) needs to be saved, because any of the crucial parameters have been modified and auto_save is not defined by the profile.

$obj->hd()

$obj->profile()

$obj->scope()

$obj->state()

$obj->token_type()

errors

When the token is received (hence this object created) it be the result of an error. It is the way the original code was designed...

$obj->error()

$obj->error_description()

$obj->error_uri()

Expiration

$obj->auto_refresh()

$obj->expired( [$after] )

Returns true when the token has an expiration set and that time has passed. We use this token $after this check: to avoid the token to timeout inbetween, we take (by default 15 seconds) margin.

$obj->expires_at( [$timestamp] )

Returns the expiration timestamp of this token (true) or undef (false) when it is not set.

$obj->expires_in()

Returns the number of seconds left, before the token is expired. That may be negative.

$obj->refresh_always()

$obj->refresh_token()

$obj->update_token( $token, $tokentype, $expires_at, [$refresh_token] )

Change the token.

Actions

$obj->refresh()

Refresh the token, even if it has not expired yet. Returned is the new access_token value, which may be undef on failure.

$obj->session_freeze(%options)

This returns a SESSION (a flat HASH) containing all token parameters which needs to be saved to be able to restore this token later. This SESSION can be passed to session_thaw() to get revived.

The changed flag will be cleared by this method.

Be sure that your storage is character-set aware. For instance, you probably want to set 'mysql_enable_utf8' when you store this in a MySQL database. Perl's JSON module will output utf8 by default.

$obj->to_json()

Freeze this object into JSON. The JSON syntax is also used by the OAuth2 protocol, so a logical choice to provide. However, generically, the session_freeze() method provided.

HTTP

The token can be encoded in transport protocol in different ways. Using these method will add the token to the HTTP messages sent.

$obj->delete( $uri, [$header, [$content]] )

$obj->get( $uri, [$header, [$content]] )

$obj->post( $uri, [$header, [$content]] )

$obj->put( $uri, [$header, [$content]] )

$obj->request($request)

COPYRIGHTS

Copyrights 2013-2019 on the perl code and the related documentation by [Mark Overmeer <markov@cpan.org>] for SURFnet bv, The Netherlands. For other contributors see "Changes".

Copyrights 2011-2012 by Keith Grennan.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/