Jan Henning Thorsen > Mojolicious-Plugin-OAuth2-1.53 > Mojolicious::Plugin::OAuth2

Download:
Mojolicious-Plugin-OAuth2-1.53.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 1.53   Source  

NAME ^

Mojolicious::Plugin::OAuth2 - Auth against OAuth2 APIs

DESCRIPTION ^

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

Breaking changes

Between 1.51 (2015-03-18) and 1.53 (2015-09-08) we decided to remove the back compat hack for "get_token", making it act only as documented.

The two helpers get_authorize_url() and get_token() will be removed soon. They have been deprecated since 1.4 (2015-03-01).

References

SYNOPSIS ^

Example web application

  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'));
      },
    );
  };

Example blocking web application

  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;
    }
  };

Custom 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") %>

Configuration

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:

Testing

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:

HELPERS ^

oauth2.auth_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:

oauth2.get_token

  $data = $c->oauth2->get_token($provider_name => \%args);
  $c    = $c->oauth2->get_token($provider_name => \%args, sub {
            my ($c, $err, $data) = @_;
            # do stuff with $data->{access_token} if it exists.
          });

"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.

In more detail, this method will do one of two things:

  1. 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.
  2. 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 (or die in blocking mode) 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:

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

Holds a hash of provider information. See oauth2.providers.

METHODS ^

register

Will register this plugin in your application. See "SYNOPSIS".

AUTHOR ^

Marcus Ramberg - mramberg@cpan.org

Jan Henning Thorsen - jhthorsen@cpan.org

LICENSE ^

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

syntax highlighting: