Dancer::Plugin::Auth::Github - Authenticate with Github
package YourDancerApplication; use Dancer ':syntax'; use Dancer::Plugin::Auth::Github; #You must use a session backend. #You should be able to use any backend support by dancer. set 'session' => 'Simple'; #make sure you call this first. #initializes the config auth_github_init(); hook before => sub { #we don't want to be in a redirect loop return if request->path =~ m{/auth/github/callback}; if (not session('github_user')) { redirect auth_github_authenticate_url; } }; #by default success will redirect to this route get '/' => sub { "Hello, ".session('github_user')->{'login'}; #For all the github_user properties #look at http://developer.github.com/v3/users/ #See the Response for "Get the authenticated user" }; #additionally the plugin adds session('github_access_token') #so you can use it if you're doing other things with GitHub Api. #by default authentication failure will redirect to this route get '/auth/github/failed' => sub { return "Github authentication Failed" }; ...
This plugin helps you setup authentication with github OAuth api in your dancer application. It has a helper method that returns the URL you must redirect to for authentication with github, it then defines a callback that handles the rest and if the user was authenticated, his/her info is stored in a session object session('github_user'). The plugin also adds session('github_access_token) if you're doing anything else with github api.
session('github_user')
session('github_access_token)
In order for this plugin to work, you need the following:
Github application
You must register your github application here https://github.com/settings/applications/new. You also need to set the callback url in your application settings to yourdomain.com/auth/github/callback. Note, for testing purposes GitHub allows you to use http://127.0.0.1:3000 as your application url.
yourdomain.com/auth/github/callback
http://127.0.0.1:3000
Configuration
The plugin needs to be configured with your client_id and client_secret (provided by Github once you register your application).
client_id
client_secret
Set this in your Dancer's configuration under plugins/Auth::Github:
plugins/Auth::Github
# config.yml ... plugins: "Auth::Github": client_id: "abcde" client_secret: "abcde" scope: "" github_auth_failed: "/fail" github_auth_success: "/"
There is an optional scope, which can be one of the scopes here . Don't include scope if you just need the authenticated user .github_auth_success and github_auth_failed are optional and default to '/' and '/auth/github/failed', respectively.
github_auth_success
github_auth_failed
Session backend
You need to setup a session backend in your dancer application for everything to work. This plugin stores the authenticated user in a session with the name github_user
github_user
You should be able to use any session backend, see Dancer::Session for details about various Dancer session backends, or http://search.cpan.org/search?query=Dancer-Session.
The plugin exports the following symbols to your application's namespace:
This function should be called before all your route handlers. It loads up the configuration from your config.yml
config.yml
This function returns an URL that is used to authenticate with github You could put it in a hook like this:
hook 'before' => sub { # we don't want a redirect loop here #Github will call /auth/github/callback once the user is authenticated return if request->path =~ m{/auth/github/callback}; if (not session('github_user')) { redirect auth_github_authenticate_url(); } };
(See this page for more on before hooks)
before hooks
The plugin defines the following route handler automatically
When a user authenticates on Github, Github redirects back to this url. (Note: You must set the callback url to this one). The route handler will save the access token and then retrieve the authenticated user's information in the session.
If the authentication succeeded, then the plugin will redirect to url setup in the config : github_auth_success, if it failed, then the user is redirected to github_auth_fail. By default github_auth_success = / and github_auth_fail = "/auth/github/failed"
github_auth_fail
github_auth_success = /
github_auth_fail = "/auth/github/failed"
When the authentication succeeds two session objects are created. session('github_user') . For all the github_user properties see this page. session('github_access_token') is also created, if you need to do other things with the api.
session('github_access_token')
Gideon Israel Dsouza, <gideon at cpan.org>, http://www.gideondsouza.com
<gideon at cpan.org>
Please report any bugs or feature requests to bug-dancer-plugin-auth-github at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Dancer-Plugin-Auth-Github. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-dancer-plugin-auth-github at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Dancer::Plugin::Auth::Github
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Dancer-Plugin-Auth-Github
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Dancer-Plugin-Auth-Github
CPAN Ratings
http://cpanratings.perl.org/d/Dancer-Plugin-Auth-Github
Search CPAN
http://search.cpan.org/dist/Dancer-Plugin-Auth-Github/
This project is more or less a port of Dancer::Plugin::Auth::Twitter written by Alexis Sukrieh which itself is a port of Catalyst::Authentication::Credential::Twitter written by Jesse Stay.
Copyright 2013 Gideon Israel Dsouza.
This project is open source here on github.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
1 POD Error
The following errors were encountered while parsing the POD:
alternative text 'http://search.cpan.org/search?query=Dancer-Session' contains non-escaped | or /
To install Dancer::Plugin::Auth::Github, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dancer::Plugin::Auth::Github
CPAN shell
perl -MCPAN -e shell install Dancer::Plugin::Auth::Github
For more information on module installation, please visit the detailed CPAN module installation guide.