Mojolic...::OAuth2(3)

📦

version 2.02 · 4 versions

2.02 · opensuse-leap 16.0 (latest)
2.02 · fedora 43
2.02 · fedora 44
2.02 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ Mojolicious::Plugin::OAuth2 — like, the whole manual but make it make sense ✨

Okay bestie, sit down, grab a strawberry 🍓 — this is the <italic>Mojolicious::Plugin::OAuth2</italic> page (yes, the module name got squished to Mojolic...::OAuth2 in the header, we love a mysterious queen) and it's genuinely iconic. It's the plugin that lets you auth against OAuth2 APIs including OpenID Connect. Periodt. 💅

🌸 NAME 🌸

Mojolicious::Plugin::OAuth2 — auth against OAuth2 APIs including OpenID Connect. That's the whole vibe. 🔥

🦋 SYNOPSIS 🦋

💖 Example application

Okay so here's the whole thing in action, and no cap, it's giving main character energy:

use Mojolicious::Lite;

plugin OAuth2 => {
  providers => {
    facebook => {
      key    => 'some-public-app-id',
      secret => $ENV{OAUTH2_FACEBOOK_SECRET},
    },
  },
};

get '/connect' => sub {
  my $c         = shift;
  my %get_token = (redirect_uri => $c->url_for('connect')->userinfo(undef)->to_abs);

  return $c->oauth2->get_token_p(facebook => \%get_token)->then(sub {
    # Redirected to Facebook
    return unless my $provider_res = shift;

    # Token received
    $c->session(token => $provider_res->{access_token});
    $c->redirect_to('profile');
  })->catch(sub {
    $c->render('connect', error => shift);
  });
};

Wanna know all the config deets this plugin eats? Go peek at "register" — it's literally right there for you, bestie. 🫶

🧚 Testing

Your code can do offline testing (yesss, no network, slay) using the "mocked" provider:

$app->plugin(OAuth2 => {mocked => {key => 42}});
$app->routes->get('/profile' => sub {
  my $c = shift;

  state $mocked = $ENV{TEST_MOCKED} && 'mocked';
  return $c->oauth2->get_token_p($mocked || 'facebook')->then(sub {
    ...
  });
});

More deets live in Mojolicious::Plugin::OAuth2::Mock — go read it, iykyk. 💜

🎀 Connect button

You can drop a "connect link" right into your template with the "oauth2.auth_url" helper. Example template moment:

Click here to log in:
<%= link_to 'Connect!', $c->oauth2->auth_url('facebook', scope => 'user_about_me email') %>

🌈 DESCRIPTION 🌈

This Mojolicious plugin lets you easily authenticate against an OAuth2 <http://oauth.net> or OpenID Connect <https://openid.net/connect/> provider. It ships with configs for a few popular providers, but you can absolutely add your own too — we're not gatekeeping. 👑

Full list of bundled providers? That's in "register".

Heads up bestie: to support "OpenID Connect" you gotta install these optional modules manually: Crypt::OpenSSL::Bignum, Crypt::OpenSSL::RSA and Mojo::JWT. You can install them with App::cpanminus:

$ cpanm Crypt::OpenSSL::Bignum Crypt::OpenSSL::RSA Mojo::JWT

⭐ HELPERS ⭐

💅 oauth2.auth_url

$url = $c->oauth2->auth_url($provider_name => \%args);

Returns a Mojo::URL object containing the authorize URL. This is genuinely useful if you wanna add the authorize URL as a link on your webpage instead of doing a redirect like "oauth2.get_token" does. %args is optional, but it can contain:

host — useful if your provider uses different hosts for accessing different accounts. The default is specified in the provider configuration.

$url->host($host);

authorize_query — either a hash-ref or an array-ref, used to give extra query params to the URL.

$url->query($authorize_url);

redirect_uri — useful if you want to go back to a different page than what you came from. The default is:

$c->url_for->to_abs->to_string

scope — scope to ask for credentials to. Should be a space separated list.
state — a string that will be sent to the identity provider. When the user returns from the identity provider, this exact same string will be carried with the user, as a GET parameter called "state" in the URL that the user will return to.

🦋 oauth2.get_refresh_token_p

$promise = $c->oauth2->get_refresh_token_p($provider_name => \%args);

When Mojolicious::Plugin::OAuth2 is being used in OpenID Connect mode, this helper lets you refresh a token by specifying a "refresh_token" in %args. Usage is similar to "oauth2.get_token_p". Lowkey convenient, honestly. ✨

🔥 oauth2.get_token_p

$promise = $c->oauth2->get_token_p($provider_name => \%args)
             ->then(sub { my $provider_res = shift })
             ->catch(sub { my $err = shift; });

"oauth2.get_token_p" is used to either fetch an access token from an OAuth2 provider, handle errors, or redirect to the OAuth2 provider.

So $err in the rejection handler holds an error description if something went wrong. And $provider_res is a hash-ref containing the access token from the OAauth2 provider — or "undef" if this plugin performed a 302 redirect to the provider's connect website. (Yes, the original says "OAauth2". We're keeping it. Iconic typo, no notes. 😭)

In more detail, this method does one of two things:

When called from an action on your site, it will redirect you to the provider's "authorize_url". That site will probably have some sort of "Connect" and "Reject" button, letting the visitor either connect your site with his/her profile on the OAuth2 provider's page or not.
The OAuth2 provider will redirect the user back to your site after clicking the "Connect" or "Reject" button. $provider_res will then contain a key "access_token" on "Connect" and a false value on "Reject".

The method takes these arguments: $provider_name needs to match one of the provider names under "Configuration" or a custom provider you defined when registering the plugin.

%args can have:

host — useful if your provider uses different hosts for accessing different accounts. The default is specified in the provider configuration.
redirect — set "redirect" to 0 to disable automatic redirect.
scope — scope to ask for credentials to. Should be a space separated list.

🧚 oauth2.jwt_decode

$claims = $c->oauth2->jwt_decode($provider, sub { my $jwt = shift; ... });
$claims = $c->oauth2->jwt_decode($provider);

When Mojolicious::Plugin::OAuth2 is being used in OpenID Connect mode, this helper lets you decode the response data encoded with the JWKS discovered from the "well_known_url" configuration. Decoding era. 💜

🌸 oauth2.logout_url

$url = $c->oauth2->logout_url($provider_name => \%args);

When Mojolicious::Plugin::OAuth2 is being used in OpenID Connect mode, this helper creates the URL to redirect to in order to end the session. The OpenID Connect Provider will redirect to the "post_logout_redirect_uri" provided in %args. Additional keys for %args are "id_token_hint" and "state". Bye bestie 👋

🎀 oauth2.providers

$hash_ref = $c->oauth2->providers;

This helper lets you access the raw providers mapping, which looks something like this:

{
  facebook => {
    authorize_url => "https://graph.facebook.com/oauth/authorize",
    token_url     => "https://graph.facebook.com/oauth/access_token",
    key           => ...,
    secret        => ...,
  },
  ...
}

👑 ATTRIBUTES 👑

⭐ providers

$hash_ref = $oauth2->providers;

Holds a hash of provider information. See "oauth2.providers". Same energy, different access point. 💅

💖 METHODS 💖

🌈 register

$app->plugin(OAuth2 => \%provider_config);
$app->plugin(OAuth2 => {providers => \%provider_config, proxy => 1, ua => Mojo::UserAgent->new});

Will register this plugin in your application with a given %provider_config. The keys in %provider_config are provider names and the values are configuration for each provider. Note that the value will be merged with the predefined providers below. Merging, bestie! 🌸

Instead of just passing in %provider_config, it's possible to pass in a more complex config, with these keys:

providers — the %provider_config must be present under this key.
proxy — setting this to a true value will automatically detect proxy settings using "detect" in Mojo::UserAgent::Proxy.
ua — a custom Mojo::UserAgent, in case you wanna change proxy settings, timeouts or other attributes.

Instead of just passing in %provider_config, it's possible to pass in a hash-ref "providers" (%provider_config) and "ua" (a custom Mojo::UserAgent object).

Here's an example to add adddition information like "key" and "secret" (yes, "adddition" — we stan a legend who types fast 🫶):

$app->plugin(OAuth2 => {
  providers => {
    custom_provider => {
      key           => 'APP_ID',
      secret        => 'SECRET_KEY',
      authorize_url => 'https://provider.example.com/auth',
      token_url     => 'https://provider.example.com/token',
    },
    github => {
      key    => 'APP_ID',
      secret => 'SECRET_KEY',
    },
  },
});

For OpenID Connect <https://openid.net/connect/>, "authorize_url" and "token_url" are configured from the "well_known_url" so these are replaced by the "well_known_url" key.

$app->plugin(OAuth2 => {
  providers => {
    azure_ad => {
      key            => 'APP_ID',
      secret         => 'SECRET_KEY',
      well_known_url => 'https://login.microsoftonline.com/tenant-id/v2.0/.well-known/openid-configuration',
    },
  },
});

To make it a bit easier, there are already some predefined providers bundled with this plugin. Gift. 🎁

💜 dailymotion

Authentication for <https://www.dailymotion.com/> video site.

💜 debian_salsa

Authentication for <https://salsa.debian.org/>.

💜 eventbrite

Authentication for <https://www.eventbrite.com> event site.

💜 facebook

OAuth2 for Facebook's graph API, <http://graph.facebook.com/>. You can find "key" (App ID) and "secret" (App Secret) from the app dashboard here: <https://developers.facebook.com/apps>.

💜 instagram

OAuth2 for Instagram API. You can find "key" (Client ID) and "secret" (Client Secret) from the app dashboard here: <https://www.instagram.com/developer/clients/manage/>.

💜 github

Authentication with Github.

💜 google

OAuth2 for Google. You can find the "key" (CLIENT ID) and "secret" (CLIENT SECRET) from the app console here under "APIs & Auth" and "Credentials" in the menu at <https://console.developers.google.com/project>.

💜 vkontakte

OAuth2 for Vkontakte. You can find "key" (App ID) and "secret" (Secure key) from the app dashboard here: <https://vk.com/apps?act=manage>.

🫶 AUTHOR 🫶

Marcus Ramberg — "mramberg@cpan.org"

Jan Henning Thorsen — "jhthorsen@cpan.org"

Legends, both of them. 👑

🎀 LICENSE 🎀

This software is licensed under the same terms as Perl itself.

🔍 SEE ALSO 🔍

That's the whole page, bestie — no skips, no cuts, we ate and left zero crumbs. 🍓 And for the sign-off deets: this was perl v5.42.0, dated 2022-02-09, tagged Mojolic...::OAuth2(3) at the bottom like a little footer bow. 🎀✨ mwah 💋

📦 where this page comes from

opensuse-leap 16.0: perl-Mojolicious-Plugin-OAuth2 2.02-bp160.1.11 · Artistic-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms