NAME
Catalyst::Authentication::Credential::GooglePlus - Authenticates a user using a Google Plus token.
SYNOPSIS
'Plugin::Authentication' => { default => { credential => { class => 'GooglePlus', token_field => 'id_token', public_cert_url => 'https://www.googleapis.com/oauth2/v1/certs', }, store => { class => 'DBIx::Class', user_model => 'DB::User', ... }, }, },
DESCRIPTION
Retrieves Google's public certificates, and then retrieves the key from the cert using Crypt::OpenSSL::X509. Finally, uses the pubkey to decrypt a Google token using JSON::WebToken.
See https://github.com/errietta/Catalyst-Plugin-Authentication-Credential-GooglePlus-example for an example.
METHODS
authenticate
Retrieves a JSON web token from either $authinfo, or GET or POST query parameters. If null, throws exception.
Otherwise, decodes (with "decode") the token, and calls find_user on the given Catalyst::Authentication::Realm object with the data retrieved from decoding the token.
ARGUMENTS
- $c
-
Catalyst object.
- $realm
-
Catalyst::Authentication::Realm (or subclass) object.
- $authinfo
-
Optional, authentication info that can contain the token. If not given, the token is retrieved from GET or POST parameters.
RETURNS
User found by calling "find_user" in Catalyst::Authentication::Realm with the decoded token's information, if any.
retrieve_certs
Retrieves a pair of JSON-encoded certificates from the given $url (defaults to Google's public cert url), and returns the decoded JSON object.
If a cache plugin is loaded, the certificate pair is cached; however one of the certificates is expired, a new pair is fetched from $url.
ARGUMENTS
- url
-
Optional. Location where certificates are located.
This can also be configured as the 'Authentication::Credential::Google::public_cert_url' key in your catalyst configuration.
Defaults to https://www.googleapis.com/oauth2/v1/certs.
RETURNS
Decoded JSON object containing certificates.
get_key_from_cert
Given a pair of certificates $certs (defaults to "retrieve_certs"), this function returns the public key of the cert identified by $kid.
ARGUMENTS
- $kid
-
Required. Index of the certificate hash $hash where the cert we want is located.
- $certs
-
Optional. A (hashref) pair of certificates. It's retrieved using "retrieve_certs" if not given, or if the pair is expired.
- $recursive
-
This will be set to true if this function calls itself to renew an expired certificate. Used to prevent infinite recursion.
RETURNS
Public key of certificate.
is_cert_expired
Returns if a given Crypt::OpenSSL::X509 certificate is expired.
decode
Returns the decoded information contained in a user's token.
ARGUMENTS
- $token
-
Required. The user's token from Google+.
- $certs
-
Optional. A pair of public key certs retrieved from Google. If not given, or if the certificates have expired, a new pair of certificates is retrieved.
- $pubkey
-
Optional. A public key string with which to decode the token. If not given, the public key will be retrieved from $certs.
RETURNS
Decoded JSON object from the decrypted token.
CAVEATS
- We currently have no automated (unit) tests..
- The code that verifies the key from Google ("get_key_from_cert" only checks if the key has expired. It does not check that the key is signed by the right people - i.e. a correctly formatted self-signed key would still work...
AUTHOR
Errietta Kostala <e.kostala@shadowcat.co.uk>
CONTRIBUTORS
- Matt S. Trout <mst@shadowcat.co.uk>
- Chris Jackson <c.jackson@shadowcat.co.uk>
- Jess Robinson <j.robinson@shadowcat.co.uk>
SPONSORS
- Shadowcat Systems LTD. (http://shadow.cat)
- Tara L Andrews, Digital Humanities, University of Bern
COPYRIGHT
Copyright (c) 2015 the Catalyst::Plugin::Authentication::Credential::GooglePlus "AUTHOR" and "CONTRIBUTORS" as listed above.
LICENSE
This library is free software and may be distributed under the same terms as perl itself. See http://dev.perl.org/licenses/.