Provided by: libmojolicious-plugin-oauth2-perl_2.02-1_all 
NAME
Mojolicious::Plugin::OAuth2 - Auth against OAuth2 APIs including OpenID Connect
SYNOPSIS
Example application
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);
});
};
See "register" for more details about the configuration this plugin takes.
Testing
Code using this plugin can perform offline testing, 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 {
...
});
});
See Mojolicious::Plugin::OAuth2::Mock for more details.
Connect button
You can add a "connect link" to your template using the "oauth2.auth_url" helper. Example
template:
Click here to log in:
<%= link_to 'Connect!', $c->oauth2->auth_url('facebook', scope => 'user_about_me email') %>
DESCRIPTION
This Mojolicious plugin allows you to easily authenticate against a OAuth2
<http://oauth.net> or OpenID Connect <https://openid.net/connect/> provider. It includes
configurations for a few popular providers, but you can add your own as well.
See "register" for a full list of bundled providers.
To support "OpenID Connect", the following optional modules must be installed manually:
Crypt::OpenSSL::Bignum, Crypt::OpenSSL::RSA and Mojo::JWT. The modules can be installed
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 which contain the authorize URL. This is useful if you want to
add the authorize URL as a link to your webpage instead of doing a redirect like
"oauth2.get_token" does. %args is optional, but 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 which can be 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 allows
for a token to be refreshed by specifying a "refresh_token" in %args. Usage is similar to
"oauth2.get_token_p".
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 OAuth2 provider. $err in the rejection handler holds a error
description if something went wrong. $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.
In more detail, this method will do one of two things:
1.
When called from an action on your site, it will redirect you to the provider's
"authorize_url". This site will probably have some sort of "Connect" and "Reject"
button, allowing the visitor to either connect your site with his/her profile on the
OAuth2 provider's page or not.
2.
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 need to match on of the provider names
under "Configuration" or a custom provider 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 allows
you to decode the response data encoded with the JWKS discovered from "well_known_url"
configuration.
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 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".
oauth2.providers
$hash_ref = $c->oauth2->providers;
This helper allow you to 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".
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.
Instead of just passing in %provider_config, it is 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 want to change proxy settings, timeouts or other
attributes.
Instead of just passing in %provider_config, it is possible to pass in a hash-ref
"providers" (%provider_config) and "ua" (a custom Mojo::UserAgent object).
Here is an example to add adddition information like "key" and "secret":
$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 the are already some predefined providers bundled with this
plugin:
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.
See also <http://developer.eventbrite.com/docs/auth/>.
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>.
See also <https://developers.facebook.com/docs/reference/dialogs/oauth/>.
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/>.
See also <https://www.instagram.com/developer/authentication/>.
github
Authentication with Github.
See also <https://developer.github.com/v3/oauth/>.
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>.
See also <https://developers.google.com/+/quickstart/>.
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>.
See also <https://vk.com/dev/authcode_flow_user>.
AUTHOR
Marcus Ramberg - "mramberg@cpan.org"
Jan Henning Thorsen - "jhthorsen@cpan.org"
LICENSE
This software is licensed under the same terms as Perl itself.
SEE ALSO
• <http://oauth.net/documentation/>
• <http://aaronparecki.com/articles/2012/07/29/1/oauth2-simplified>
• <http://homakov.blogspot.jp/2013/03/oauth1-oauth2-oauth.html>
• <http://en.wikipedia.org/wiki/OAuth#OAuth_2.0>
• <https://openid.net/connect/>