Mojolicious::Plugin::OAuth2 - Auth against OAuth2 APIs
This Mojolicious plugin allows you to easily authenticate against a OAuth2 provider. It includes configurations for a few popular providers, but you can add your own easily as well.
Note that OAuth2 requires https, so you need to have the optional Mojolicious dependency required to support it. Run the command below to check if IO::Socket::SSL is installed.
$ mojo version
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
use Mojolicious::Lite; plugin "OAuth2" => { facebook => { key => "some-public-app-id", secret => $ENV{OAUTH2_FACEBOOK_SECRET}, }, }; get "/connect" => sub { my $c = shift; $c->delay( sub { my $delay = shift; my $args = {redirect_uri => $c->url_for('connect')->userinfo(undef)->to_abs}; $c->oauth2->get_token(facebook => $args, $delay->begin); }, sub { my ($delay, $err, $data) = @_; return $c->render("connect", error => $err) unless $data->{access_token}; return $c->session(token => $c->redirect_to('profile')); }, ); };
use Mojolicious::Lite; plugin "OAuth2" => { facebook => { key => "some-public-app-id", secret => $ENV{OAUTH2_FACEBOOK_SECRET}, }, }; get "/connect" => sub { my $c = shift; my $args = {redirect_uri => $c->url_for('connect')->userinfo(undef)->to_abs}; if (my $err = $c->param('error')) { # do stuff with error from OAuth2 provider } elsif (my $data = $c->oauth2->get_token(facebook => $args)) { # do stuff with $data->{access_token}; } else { # already redirected by OAuth2 plugin return; } };
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 plugin takes a hash as config, where the keys are provider names and the values are configuration for each provider. Here is a complete example:
plugin "OAuth2" => { custom_provider => { key => "APP_ID", secret => "SECRET_KEY", authorize_url => "https://provider.example.com/auth", token_url => "https://provider.example.com/token", }, };
To make it a bit easier, Mojolicious::Plugin::OAuth2 has already values for authorize_url and token_url for the following providers:
authorize_url
token_url
dailymotion
Authentication for Dailymotion video site.
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.
key
secret
See also https://developers.facebook.com/docs/reference/dialogs/oauth/.
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/.
THIS API IS EXPERIMENTAL AND CAN CHANGE WITHOUT NOTICE.
To enable a "mocked" OAuth2 api, you need to give the special "mocked" provider a "key":
plugin "OAuth2" => { mocked => {key => 42} };
The code above will add two new routes to your application:
GET /mocked/oauth/authorize
This route is a web page which contains a link that takes you back to "redirect_uri", with a "code". The "code" default to "fake_code", but can be configured:
$c->app->oauth2->providers->{mocked}{return_code} = "...";
The route it self can also be customized:
plugin "OAuth2" => { mocked => {authorize_url => '...'} };
POST /mocked/oauth/token
This route is will return a "access_token" which is available in your "oauth2.get_token" callback. The default is "fake_token", but it can be configured:
$c->app->oauth2->providers->{mocked}{return_token} = "...";
plugin "OAuth2" => { mocked => {token_url => '...'} };
$url = $c->oauth2->auth_url($provider => \%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:
%args
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.
$data = $c->oauth2->get_token($provider_name => \%args); $c = $c->oauth2->get_token($provider_name => \%args, sub { my ($c, $err, $data) = @_; });
"oauth2.get_token" is used to either fetch access token from OAuth2 provider, handle errors or redirect to OAuth2 provider. This method can be called in either blocking or non-blocking mode. $err holds a error description if something went wrong. Blocking mode will die($err) instead of returning it to caller. $data is a hash-ref containing the access token from the OAauth2 provider. $data in blocking mode can also be undef if a redirect has been issued by this module.
$err
die($err)
$data
undef
In more detail, this method will do one of two things:
If called from an action on your site, it will redirect you to the $provider_name'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.
$provider_name
The OAuth2 provider will redirect the user back to your site after clicking the "Connect" or "Reject" button. $data will then contain a key "access_token" on "Connect" and a false value on "Reject" mode, or will die in blocking mode.
Will redirect to the provider to allow for authorization, then fetch the token. The token gets provided as a parameter to the callback function. Usually you want to store the token in a session or similar to use for API requests. Supported arguments:
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 => ..., }, ... }
Holds a hash of provider information. See oauth2.providers.
Will register this plugin in your application. See "SYNOPSIS".
Marcus Ramberg - mramberg@cpan.org
mramberg@cpan.org
Jan Henning Thorsen - jhthorsen@cpan.org
jhthorsen@cpan.org
This software is licensed under the same terms as Perl itself.
To install Mojolicious::Plugin::OAuth2, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mojolicious::Plugin::OAuth2
CPAN shell
perl -MCPAN -e shell install Mojolicious::Plugin::OAuth2
For more information on module installation, please visit the detailed CPAN module installation guide.