view release on metacpan or  search on metacpan

README.pod  view on Meta::CPAN

    ...
  }

=head1 DESCRIPTION

This plugin implements the various OAuth2 grant types flow as described at
L<http://tools.ietf.org/html/rfc6749>. It is a complete implementation of
RFC6749, with the exception of the "Extension Grants" as the description of
that grant type is rather hand-wavy.

The bulk of the functionality is implemented in the L<Net::OAuth2::AuthorizationServer>
distribution, you should see that for more comprehensive documentation and
examples of usage.

The examples here use the "Authorization Code Grant" flow as that is considered
the most secure and most complete form of OAuth2.

=cut

use strict;
use warnings;
use base qw/ Mojolicious::Plugin /;

use Mojo::URL;
use Mojo::Parameters;
use Mojo::Util qw/ b64_decode url_unescape /;
use Net::OAuth2::AuthorizationServer;
use Carp qw/ croak /;

our $VERSION = '0.52';

my ( $AuthCodeGrant,$PasswordGrant,$ImplicitGrant,$ClientCredentialsGrant,$Grant,$JWTCallback );

=head1 METHODS

=head2 register

Registers the plugin with your app - note that you must pass callbacks for
certain functions that the plugin expects to call if you are not using the
plugin in its simplest form.

  $self->register($app, \%config);

Registering the plugin will call the L<Net::OAuth2::AuthorizationServer>
and create a C<auth_code_grant> that can be accessed using the defined
C<authorize_route> and C<access_token_route>. The arguments passed to the
plugin are passed straight through to the C<auth_code_grant> method in
the L<Net::OAuth2::AuthorizationServer> module.

=head2 oauth

Checks if there is a valid Authorization: Bearer header with a valid access
token and if the access token has the requisite scopes. The scopes are optional:

  unless ( my $oauth_details = $c->oauth( @scopes ) ) {
    return $c->render( status => 401, text => 'Unauthorized' );
  }

This calls the L<Net::OAuth2::AuthorizationServer::AuthorizationCodeGrant>
module (C<verify_token_and_scope> method) to validate the access/refresh token.

=head2 oauth2_auth_request

This is a helper to allow you get get the redirect URI instead of directing
a user to the authorize_route - it requires the details of the client:

  my $redirect_uri = $c->oauth2_auth_request({
    client_id     => $client_id,
    redirect_uri  => 'https://foo',
    response_type => 'token',
    scope         => 'list,of,scopes',
    state         => 'foo=bar&baz=boz',
  });

  if ( $redirect_uri ) {
   # do something with $redirect_uri
  } else {
    # something didn't work, e.g. bad client, scopes, etc
  }

You can use this helper instead of directing a user to the authorize_route if
you need to do something more involved with the redirect_uri rather than
having the plugin direct to the user to the resulting redirect uri

=cut

my $warned_dep = 0;

sub register {
  my ( $self,$app,$config ) = @_;

  my $auth_route   = $config->{authorize_route}    // '/oauth/authorize';
  my $atoken_route = $config->{access_token_route} // '/oauth/access_token';

  if ( $config->{users} && ! $config->{jwt_secret} ) {
    croak "You MUST provide a jwt_secret to use the password grant (users supplied)";
  }

  my $Server = Net::OAuth2::AuthorizationServer->new;

  # note that access_tokens and refresh_tokens will not be shared between
  # the various grant type objects, so if you need to support
  # both then you *must* either supply a jwt_secret or supply callbacks
  $AuthCodeGrant = $Server->auth_code_grant(
    ( map { +"${_}_cb" => ( $config->{$_} // undef ) } qw/
      verify_client store_auth_code verify_auth_code
      store_access_token verify_access_token
      login_resource_owner confirm_by_resource_owner
    / ),
    %{ $config },
  );

  $PasswordGrant = $Server->password_grant(
    ( map { +"${_}_cb" => ( $config->{$_} // undef ) } qw/
      verify_client verify_user_password
      store_access_token verify_access_token
      login_resource_owner confirm_by_resource_owner
    / ),
    %{ $config },
  );