Repository files navigation

GitHub OAuth2 strategy for Überauth.

1. Setup your application atGitHub Developer.

2. Add:ueberauth_github to your list of dependencies inmix.exs:

   defdepsdo[{:ueberauth_github,"~> 0.8"}]end

3. Add GitHub to your Überauth configuration:

   config:ueberauth,Ueberauth,providers:[github:{Ueberauth.Strategy.Github,[]}]

4. Update your provider configuration:

   config:ueberauth,Ueberauth.Strategy.Github.OAuth,client_id:System.get_env("GITHUB_CLIENT_ID"),client_secret:System.get_env("GITHUB_CLIENT_SECRET")

   Or, to read the client credentials at runtime:

   config:ueberauth,Ueberauth.Strategy.Github.OAuth,client_id:{:system,"GITHUB_CLIENT_ID"},client_secret:{:system,"GITHUB_CLIENT_SECRET"}

5. Include the Überauth plug in your router:

   defmoduleMyApp.RouterdouseMyApp.Web,:routerpipeline:browserdoplugUeberauth...endend

6. Create the request and callback routes if you haven't already:

   scope"/auth",MyAppdopipe_through:browserget"/:provider",AuthController,:requestget"/:provider/callback",AuthController,:callbackend

7. Your controller needs to implement callbacks to deal withUeberauth.AuthandUeberauth.Failure responses.

For an example implementation see theÜberauth Example application.

Depending on the configured url you can initiate the request through:

/auth/github

Or with options:

/auth/github?scope=user,public_repo

By default the requested scope is"user,public\_repo". This provides both readand write access to the GitHub user profile details and public repos. For aread-only scope, either use"user:email" or an empty scope"". Empty scopewill only request minimum public information which even excludes user's email addresswhich results in anil foremail inside returned%Ueberauth.Auth.Info{}.See more atGitHub's OAuth Documentation.

Scope can be configured either explicitly as ascope query value on therequest path or in your configuration:

config:ueberauth,Ueberauth,providers:[github:{Ueberauth.Strategy.Github,[default_scope:"user,public_repo,notifications"]}]

It is also possible to disable the sending of theredirect_uri to GitHub.This is particularly useful when your production application sits behind aproxy that handles SSL connections. In this case, theredirect_uri sent byUeberauth will start withhttp instead ofhttps, and if you configuredyour GitHub OAuth application's callback URL to use HTTPS, GitHub will throw anuri_mismatch error.

To preventUeberauth from sending theredirect_uri, you should add thefollowing to your configuration:

config:ueberauth,Ueberauth,providers:[github:{Ueberauth.Strategy.Github,[send_redirect_uri:false]}]

GitHub now allows you to keep your email address private. If you don't mindthat you won't know a users email address you can specifyallow_private_emails. This will set the users email asid+username@users.noreply.github.com.

config:ueberauth,Ueberauth,providers:[github:{Ueberauth.Strategy.Github,[allow_private_emails:true]}]

Copyright (c) 2015 Daniel Neighman

This library is released under the MIT License. See theLICENSE.md file