=head1 NAME

Net::OAuth2::Profile::WebServer - OAuth2 for web-server use

=head1 INHERITANCE

 Net::OAuth2::Profile::WebServer
   is a Net::OAuth2::Profile

=head1 SYNOPSIS

  my $google = Net::OAuth2::Profile::WebServer->new
    ( name           => 'Google Contacts'
    , client_id      => $id
    , client_secret  => $secret
    , site           => 'https://accounts.google.com'
    , scope          => 'https://www.google.com/m8/feeds/'
    , authorize_path    => '/o/oauth2/auth'
    , access_token_path => '/o/oauth2/token'
    , protected_resource_url
        =>  'https://www.google.com/m8/feeds/contacts/default/full'
    );

=head1 DESCRIPTION

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

=over 4

=item 1. Send an authorization request to resource owner

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

=item 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.

=item 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.

=back

=head1 METHODS

=head2 Constructors

=over 4

=item Net::OAuth2::Profile::WebServer-E<gt>B<new>(OPTIONS)

 -Option       --Defined in          --Default
  client_id      Net::OAuth2::Profile  <required>
  client_secret  Net::OAuth2::Profile  <required>
  grant_type     Net::OAuth2::Profile  'authorization_code'
  redirect_uri                         undef
  referer                              undef
  scope          Net::OAuth2::Profile  undef
  site           Net::OAuth2::Profile  undef
  token_scheme   Net::OAuth2::Profile  'auth-header:OAuth'
  user_agent     Net::OAuth2::Profile  <created internally>

=over 2

=item client_id => STRING

=item client_secret => STRING

=item grant_type => STRING

=item redirect_uri => URI

=item referer => URI

Adds a C<Referer> header to each request.  Some servers check whether
provided redirection uris point to the same server the page where the
link was found.

=item scope => STRING

=item site => URI

=item token_scheme => SCHEME

=item user_agent => LWP::UserAgent object

=back

=back

=head2 Accessors

=over 4

=item $obj-E<gt>B<bearer_token_scheme>()

See L<Net::OAuth2::Profile/"Accessors">

=item $obj-E<gt>B<grant_type>()

See L<Net::OAuth2::Profile/"Accessors">

=item $obj-E<gt>B<id>()

See L<Net::OAuth2::Profile/"Accessors">

=item $obj-E<gt>B<redirect_uri>()

=item $obj-E<gt>B<referer>([URI])

=item $obj-E<gt>B<scope>()

See L<Net::OAuth2::Profile/"Accessors">

=item $obj-E<gt>B<secret>()

See L<Net::OAuth2::Profile/"Accessors">

=item $obj-E<gt>B<site>()

See L<Net::OAuth2::Profile/"Accessors">

=item $obj-E<gt>B<user_agent>()

See L<Net::OAuth2::Profile/"Accessors">

=back

=head2 Actions

=over 4

=item $obj-E<gt>B<request>(REQUEST, [MORE])

See L<Net::OAuth2::Profile/"Actions">

=item $obj-E<gt>B<request_auth>(TOKEN, (REQUEST | (METHOD, URI, [HEADER, CONTENT])))

See L<Net::OAuth2::Profile/"Actions">

=back

=head2 Action

=over 4

=item $obj-E<gt>B<authorize>(OPTIONS)

Request an authorization code for the session.  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

=over 2

=item client_id => STRING

=item response_type => STRING

=item scope => STRING

=item state => STRING

=back

=item $obj-E<gt>B<get_access_token>(CODE, OPTIONS)

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

=over 2

=item client_id => STRING

=item client_secret => STRING

=back

=item $obj-E<gt>B<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 C<refresh_token_params> option of L<new()|Net::OAuth2::Profile::WebServer/"Constructors">.

example: 

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

=back

=head2 Helpers

=over 4

=item $obj-E<gt>B<add_token>(REQUEST, TOKEN, SCHEME)

See L<Net::OAuth2::Profile/"Helpers">

=item $obj-E<gt>B<build_request>(METHOD, URI, PARAMS)

See L<Net::OAuth2::Profile/"Helpers">

=item $obj-E<gt>B<params_from_response>(RESPONSE, REASON)

See L<Net::OAuth2::Profile/"Helpers">

=item $obj-E<gt>B<site_url>((URI|PATH), PARAMS)

See L<Net::OAuth2::Profile/"Helpers">

=back

=head1 SEE ALSO

This module is part of Net-OAuth2 distribution version 0.50,
built on January 07, 2013. Website: F<http://perl.overmeer.net>.

=head1 COPYRIGHTS

Copyrights 2012-2013 on the perl code and the related documentation
 by [Mark Overmeer]. For other contributors see Changes.

Copyrights 2011 by Keith Grennan.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://www.perl.com/perl/misc/Artistic.html>

