Net::O...bServer(3pm)

✨ Net::OAuth2::Profile::WebServer ✨

okay bestie, so this is the Net::OAuth2::Profile::WebServer page from the User Contributed Perl Documentation (yes the header line literally says Net::O...bServer(3pm) and that's just the name being all shy and abbreviated, we love that for it 💅). It's a Perl module, it does OAuth2 for web-server use, and it's giving <em>extremely</em> capable. Sit down, hydrate, let's go 🍓

---

🌸 NAME 🌸

Net::OAuth2::Profile::WebServer — OAuth2 for web-server use. That's the whole vibe. No cap.

---

🦋 INHERITANCE 🦋

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

so it's a Net::OAuth2::Profile underneath, just with main-character energy layered on top 👑

---

✨ SYNOPSIS ✨

here's the whole plot in one code block, bestie:

  # See examples/psgi/
  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
  # The $info are the parameters from the callback to your service, it
  # will contain a 'code' value.
  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;

(also yes the comment says "resource serve" and I'm keeping it exactly as-is, that's canon 🫶)

---

💖 DESCRIPTION 💖

Use OAuth2 in a WebServer context. Real talk though: read the DETAILS section, the one <em>far below</em> this man-page, before you start implementing this interface. Fr fr. Do not skip it, it will absolutely humble you.

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

---

🎀 METHODS 🎀

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

---

🧚 Constructors

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

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

here's the whole options table, every single one, nothing skipped, periodt:

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

and now, the ✨ commentary ✨:

• auto_save => CODE — when a new token arrives, or gets refreshed, it usually has to get saved into a database or a file. The moment you <em>receive</em> a new token is clear, easy, fine. But being aware of <em>refreshes</em> in your main program is a whole hassle 😭. You can read more about configuring this in the DETAILS section below.
• client_id => STRING
• client_secret => STRING
• grant_type => STRING
• hd => STRING
• redirect_uri => URI
• referer => URI — adds a "Referer" header to each request. Some servers check whether the redirection uris you provided point to the same server as the page where the link was found. So it's a little ✨trust me bro✨ header. 👀
• scope => STRING
• secrets_in_params => BOOLEAN
• site => URI
• state => STRING
• token_scheme => SCHEME
• user_agent => LWP::UserAgent object

---

🦄 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 the initial contact of a new user, you have to redirect to the resource owner. Somewhere in the near future, your application is going to get contacted again by that same user, but this time carrying an authorization grant code 🎟️. That's the whole arc.

Only the <em>most common</em> %options are listed here... there may be more: go read the docs on what your server expects, bestie, iykyk.

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

• client_id => STRING
• response_type => STRING
• scope => STRING
• state => STRING

example (iconic behaviour, study it):

  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] )

A convenience wrapper around authorize(), and it produces a complete HTTP::Response object ready to be sent back. chef's kiss 🧑🍳💋

$obj->get_access_token(CODE, %options)

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

• client_id => STRING
• client_secret => STRING

$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 <em>automatically</em>, and in that case you can use the "refresh_token_params" option of new() instead.

example:

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

(and yes, $token->refresh really is the nicer one, the comment said it, not me 💅)

---

🌈 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

---

💜 DETAILS 💜

OAuth2 is a server-server protocol, not the usual client-server set-up. The consequence is that the protocol handlers on <em>both</em> sides will not wait for one another during the communication: the remote uses callback urls to pass on the response. Your side of the communication, your webservice, needs to re-group these separate processing steps into logical sessions. It's giving ✨choreography✨, not a conga line.

---

🩰 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 to 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 <em>must</em> 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. So much more. It's a whole person.

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. Cute for a demo, not for production, bestie 🙈

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). That's it, that's the rule 🚫

---

👑 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/

---

and that's the whole page, babes 🫶 this was perl v5.32.1, dated 2021-10-15, and it's officially a wrap. go write something iconic with it 💖✨