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

💅 Net::O...rofile(3pm) — User Contributed Perl Documentation ✨

okay so bestie, you've stumbled into Net::O...rofile(3pm) (yes the man page name got truncated, we don't talk about it 💀) — it's part of the User Contributed Perl Documentation, and it's literally the blueprint for OAuth2 access profiles. let's get into it 🫶

---

🌸 NAME 🌸

Net::OAuth2::Profile — OAuth2 access profiles. that's it, that's the name, slay.

---

🧬 INHERITANCE 🧬

Net::OAuth2::Profile is extended by:

• Net::OAuth2::Profile::Password
• Net::OAuth2::Profile::WebServer

it's giving parent energy 👑

---

📜 SYNOPSIS 📜

See Net::OAuth2::Profile::WebServer
and Net::OAuth2::Profile::Password

fr fr, the actual tea lives in those two. go look 👀

---

✨ DESCRIPTION ✨

So this is the base class for OAuth profiles. currently implemented, aka the main characters:

• Net::OAuth2::Profile::WebServer
• Net::OAuth2::Profile::Password

and if you wanna actually understand the process and all the parameters, the OAuth2 documentation at Google <https://developers.google.com/accounts/docs/OAuth2WebServer> is right there. it's giving homework but make it auth 🔐

---

🛠️ METHODS 🛠️

🎀 Constructors 🎀

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

Next to the %options listed below, you can also provide settings for each of the <${commands}> "access_token", "protected_resource", "authorize", and "refresh_token". For each command, you can set:

• ${command}_url => URI|STRING — the absolute uri that needs to be used to be addressed to execute the $command. May be specified as a URI object or a STRING.
• ${command}_path => PATH — same as the previous one, but relative to the "site" option value.
• ${command}_method => 'GET'|'POST' — which method to use for the call (by default POST).
• ${command}_param => [] — extra parameters for the command.

here's the whole options-and-defaults vibe check, verbatim:

 -Option           --Default
  client_id          <required>
  client_secret      <required>
  grant_type         <required>
  hd                 undef
  scope              undef
  secrets_in_params  <true>
  site               undef
  state              undef
  token_scheme       'auth-header:Bearer'
  user_agent         <created internally>

and now the ✨detailed✨ deets:

• client_id => STRING — your id, bestie.
• client_secret => STRING — the secret. keep it secret. 🙈
• grant_type => STRING — which flavour of grant you're doing.
• hd => STRING — a passthrough parameter that lets you restrict one's login to a particular Google Apps domain. The application making the call should check that the returned value for hd matches the expected domain, because the user can change the hd parameter in the original request. 😭 yes really. See <https://developers.google.com/identity/protocols/OpenIDConnect#hd-param> for more details.
• scope => STRING — what you're asking permission for.
• secrets_in_params => BOOLEAN — the client secrets are passed both via an Authentication header and via query parameters in the URI. The former is required to be accepted by rfc6749, the latter is optional. However: many servers use the query parameters only. QQ Catalyst, on the other hand, does refuse requests with these parameters in the query. So, with this flag explicitly set to false, only the Auth header gets included. 👑
• site => URI — the site.
• state => STRING — the state.
• token_scheme => SCHEME — see add_token() for the supported SCHEMEs. Scheme "auth-header" is probably the only sane default, because that works with any kind of http requests, where the other options have limited or possible disturbing application. Before [0.53], the default was 'auth-header:OAuth'. Specify the method to submit authenticated requests to the service. By default, add the access token as a header, such as: Authorization: Bearer TOKEN. Some services require that the header will be different, i.e. Authorization: OAuth TOKEN, for which case specify token_scheme 'auth-header:Oauth'. To add the access token as a uri-parameter: 'uri-query:oauth_token' (in this case, the parameter name will be oauth_token). Merge the access token inside a form body via 'form-body:oauth_token'.
• user_agent => LWP::UserAgent object — your lil UA buddy.

---

🦋 Accessors 🦋

look at all these getters, they ate 💅

• $obj->bearer_token_scheme()
• $obj->grant_type()
• $obj->hd()
• $obj->id()
• $obj->scope()
• $obj->secret()
• $obj->site()
• $obj->state()
• $obj->user_agent()

---

⚡ Actions ⚡

🌐 HTTP 🌐

$obj->request( $request, [$more] )

Send the $request (an HTTP::Request object) to the server, calling the LWP::UserAgent method "request()". Heads up bestie: this method will NOT add security token information to the message. 🚨

$obj->request_auth( $token, <$request | <$method, $uri, [$header, $content]>> )

Send an authorized request: the $token information gets included in the request object. Returns the answer (HTTP::Response).

example, periodt:

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

# possible...
my $resp  = $auth->request_auth($token, GET => $uri, $header, $content);
my $resp  = $auth->request_auth($token, $request);

# nicer (?)
my $resp  = $token->get($uri, $header, $content);
my $resp  = $token->request($request);

---

🧚 Helpers 🧚

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

Merge information from the $token into the $request, following the the bearer token $scheme. (yes, "the the", we're keeping it, it's iconic 😌) Supported schemes:

• auth-header or auth-header:REALM — adds an "Authorization" header to requests. The default REALM is "OAuth", but "Bearer" and "OAuth2" may work as well.
• uri-query or uri-query:FIELD — adds the token to the query parameter list. The default FIELD name used is "oauth_token".
• form-body or form-body:FIELD — adds the token to the www-form-urlencoded body of the request. The default FIELD name used is "oauth_token".

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

Returns an HTTP::Request object. $params is a HASH or an ARRAY-of-PAIRS of query parameters. 🎁

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

Decode information from the $response by the server (an HTTP::Response object). The $reason for this answer is used in error messages. lowkey helpful when things go sideways 💀

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

Construct a URL to address the site. When a full $uri is passed, it appends the $params as query parameters. When a $path is provided, it is relative to new(site). 🔗

---

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

---

okay that's the whole page, you're officially an OAuth2 profile expert now, no cap 🎀 and just so we're keeping receipts: this is perl v5.32.1, dated 2021-10-15, from Net::O...rofile(3pm). go forth and auth responsibly bestie, mwah 💖✨🦋