Mojolicious::Plugin::OAuth2 - Auth against OAuth2 APIs including OpenID Connect
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.
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.
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') %>
This Mojolicious plugin allows you to easily authenticate against a OAuth2 or OpenID 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
$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
statein the URL that the user will return to.
$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".
$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:
- 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. - The OAuth2 provider will redirect the user back to your site after clicking the
"Connect" or "Reject" button.
$provider_reswill 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
redirectto 0 to disable automatic redirect. -
scope
Scope to ask for credentials to. Should be a space separated list.
$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.
$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.
$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 => ...,
},
...
}
$hash_ref = $oauth2->providers;
Holds a hash of provider information. See "oauth2.providers".
$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_configmust 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, 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:
Authentication for https://www.dailymotion.com/ video site.
Authentication for https://salsa.debian.org/.
Authentication for https://www.eventbrite.com event site.
See also http://developer.eventbrite.com/docs/auth/.
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/.
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/.
Authentication with Github.
See also https://developer.github.com/v3/oauth/.
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/.
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.
Marcus Ramberg - [email protected]
Jan Henning Thorsen - [email protected]
This software is licensed under the same terms as Perl itself.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent