view release on metacpan or  search on metacpan

lib/Dancer/Plugin/Auth/Google.pm  view on Meta::CPAN

    return ($data, $error);
}

register_plugin;
__END__

=head1 NAME

Dancer::Plugin::Auth::Google - Authenticate with Google

=head1 SYNOPSIS

    package MyApp;
    use Dancer ':syntax';
    use Dancer::Plugin::Auth::Google;

    auth_google_init;  # <-- don't forget to call this first!

    get '/' => sub {
        if (session('google_user')) {
            return 'you are logged in, ' . session('google_user')->{name};
        }
        else {
            return redirect auth_google_authenticate_url;
        }
    };

    get '/fail' => sub {
        "Oh, noes! Your authentication failed :("
    };


=head1 DESCRIPTION

This plugin provides a simplpe way to authenticate your users through Google's
OAuth API. It provides you with a helper to build easily a redirect to the
authentication URI, defines automatically a callback route handler and saves
the authenticated user to your session when done.


=head1 PREREQUISITES

In order for this plugin to work, you need the following:

=head2 Session backend

For the authentication process to work, B<you need a session backend> so the plugin
can store the authenticated user's information.

Use the session backend of your choice, it doesn't make a difference, see
L<Dancer::Session> for details about supported session engines, or search the CPAN
for new ones.

=head2 Google Application

Anyone with a valid Google account can register an application. Go to
L<http://console.developers.google.com>, then select a project or create
a new one. After that, in the sidebar on the left, select "Credentials".

First, go to the I<OAuth consent screen> tab and set it up with you website's
logo, desired credentials (the "email" and "profile" ones are granted
by default) and, specially, your B<authorized domains>. We'll need those for
the next step!

Now go to the I<Credentials> tab and click the B<Create credentials>
button/dropdown and select B<OAuth client ID>.

=for HTML
<p><img src="https://raw.githubusercontent.com/garu/Dancer-Plugin-Auth-Google/master/share/create-new-id.png"></p>

A dialog will appear. In the "Application type" section of the dialog,
select I<"Web application">.

Under the "Authorized JavaScript origins" field, put the domains of both
your development server and your production one
(e.g.: http://localhost:3000 and http://mywebsite.com). You will only be
able to include domains listed under your I<authorized domain list>,
which you set on the previous step (though localhost domains are ok).

Same thing goes for the "Redirect URIs": those B<**MUST**> be the same
as you will set in your app and Google won't redirect to any page that
is not listed (don't worry, you can edit this later too).

=for HTML
<p><img src="https://raw.githubusercontent.com/garu/Dancer-Plugin-Auth-Google/master/share/authorized-uris.png"></p>

Again, make sure the "Redirect URIs" contains both your development
url (e.g. C<http://localhost:3000/auth/google/callback>) and production
(e.g. C<http://mywebsite.com/auth/google/callback>). It's usually a good
practice to add I<both> HTTP and HTTPS callback urls.

After you're finished, copy the "Client ID" and "Client Secret" data
of your newly created app. It should be listed on that same panel
(you can check it anytime by going to the "Credentials" option)

=head2 Configuration

After you set up your app, you need to configure this plugin. To do
that, copy the "Client ID" and "Client Secret" generated on the
previous step into your Dancer's configuration under
Plugins / Auth::Google, like so:

    # config.yml
    plugins:
        'Auth::Google':
            client_id:        'your-client-id'
            client_secret:    'your-client-secret'
            scope:            'profile'
            access_type:      'online'
            callback_url:     'http://localhost:3000/auth/google/callback'
            callback_success: '/'
            callback_fail:    '/fail'
            legacy_gplus:     0

Of those, only "client_id", "client_secret" and "callback_url" are mandatory.
If you omit the other ones, they will assume their default values, as listed
above.

Specifically, it is a good practice to change the C<callback_url> depending on
whether you're on a development or production environment. Dancer makes this
trivial by letting you split your settings, leaving the basic plugin
settings on C<config.yml> and specific C<callback_url> definitions on
C<environments/development.yml> and C<environments/production.yml>:

    # environments/development.yml