view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

        state => URI::Encode->new->encode($state),
    );

    return redirect $uri;
}
```

If you do this, the "state" data will be sent back to you on the callback
as a request parameter. You can then use it to direct your user to the
proper resource or check it against forgery attacks - assuming you also
stored it in a session variable of some sort.


Route Handlers
--------------

The plugin defines the following route handler automatically:

* /auth/google/callback

This route handler is responsible for catching back a user that has just
authenticated herself with Google's OAuth. The route handler saves tokens
and user information in the session and then redirects the user to the URI
specified by callback_success.

If the validation of the token returned by Google failed or was denied,
the user will be redirected to the URI specified by callback_fail. Otherwise,
this route will point the user to callback_success.

### What data is under session('google_user')?

After getting basic authentication data, this module uses the Google Identity
Platform API, to fetch basic user profile data, like a unique id, email, name
and picture. `session('google_user')` looks like so (random hash order!):

```perl
    {
        access_token   => 'THIS IS THE ACCESS TOKEN TO USER',
        expires_in     => 3920,  # seconds!
        token_type     => 'Bearer',
        refresh_token  => 'USE THIS TO REFRESH ACCESS WITHOUT NEW AUTH',
        name           => "FirstName LastName",
        given_name     => "FirstName",
        family_name    => "LastName",
        picture        => "https://SOME-GOOGLE-URL/photo.jpg",
        locale         => "en",
        gender         => "female", # or "male", or "other"
        email          => "email@example.com",
        link           => "https://OLD-GOOGLE-PLUS-PROFILE-THIS-MIGHT-GO-AWAY",
        id             => "NUMERIC UNIQUE USER ID HERE",
        hd             => "HOSTED DOMAIN",
        verified_email => 1,
    }
```

##### NOTE: G+ is no more. Add 'legacy_gplus: 1' to keep old code running.

Up to version 0.06 of this module the `session('google_user')`
data structure was as returned by Google Plus' API. Google decided to
discontinue G+ and its API on March 7th 2019, so since version 0.07 
we fetch user information from Google's `oauth2/v2/userinfo` endpoint.

Those two structures are very different, so
**you will need to update your code** if you used any version of this module
prior to 0.07. If you don't want to, add the `legacy_gplus` option to
your configuration with a true value and `session('google_user')` will instead return
a data structure as closely matched as possible to the old version.
Note that some data may not be available anymore (particularly,
*circleByCount* and *etag*), in which case the structure
will return `undef` - but you tested those fields already, right?


Accessing Other Google APIs
---------------------------

Once the user is authenticated, your session data will contain the access
token:

```perl
    my $token = session('google_user')->{access_token};
```

You can use that access token to make calls to a Google API on behalf of
the user. See https://developers.google.com/identity/protocols/OAuth2WebServer
for more information on this.


Acknowledgements
----------------

This plugin was written following the same design as
Dancer::Plugin::Auth::Twitter and Dancer::Plugin::Auth::Facebook.


COPYRIGHT AND LICENCE
---------------------

Copyright (C) 2014-2019, Breno G. de Oliveira

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.