=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 $auth = 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'
    );

  # Let user ask for a grant from the resource owner
  print $auth->authorize_response->as_string;
  # or, in Plack:   redirect $auth->authorize;

  # Prove your identity at the authorization server
  my $access_token  = $auth->get_access_token($info->{code});

  # communicate with the resource serve
  my $response      = $access_token->get('/me');
  $response->is_success
      or die "error: " . $response->status_line;

  print "Yay, it worked: " . $response->decoded_content;

=head1 DESCRIPTION

Use OAuth2 in a WebServer context.  Read the DETAILS section, far below
this man-page before you start implementing this interface.

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

=over 2

=item client_id => STRING

=item response_type => STRING

=item scope => STRING

=item state => STRING

=back

example: 

  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;

=item $obj-E<gt>B<authorize_response>([REQUEST])

Convenience wrapper around L<authorize()|Net::OAuth2::Profile::WebServer/"Actions">, to produce a complete
HTTP::Response object to be sent 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

=head3 HTTP

=over 4

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

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

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

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

=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 DETAILS

=head2 The process

The B<main complication> does not show in the example in the SYNOPSIS,
not in the plack example included in the distribution: your client session
can not survive the shown steps: your application behaves like a server,
not a client.  You need to implement losely coupled server-server
communication, which is less straight-forward.

First, your application must implement a persistent session (in a database
or file), which may get called on any weird moment to pass on information.
Your application must be visible from "outside" and use https.  More than
enough complications.  Full example needed ;-)

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 SEE ALSO

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

=head1 COPYRIGHTS

Copyrights 2013 on the perl code and the related documentation
 by [Mark Overmeer] for SURFnet bv, The Netherlands.  For other contributors see Changes.

Copyrights 2011-12 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>

