

Overview — Üeberauth GitHub v0.8.3

 try {

 if (localStorage.getItem('night-mode') === 'true') {

 document.body.classList.add('night-mode');

 }

 } catch (error) { }

 

Überauth GitHub

===============

[![Build Status](https://travis-ci.org/ueberauth/ueberauth_github.svg?branch=master)](https://travis-ci.org/ueberauth/ueberauth_github)

[![Module Version](https://img.shields.io/hexpm/v/ueberauth_github.svg)](https://hex.pm/packages/ueberauth_github)

[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/ueberauth_github/)

[![Total Download](https://img.shields.io/hexpm/dt/ueberauth_github.svg)](https://hex.pm/packages/ueberauth_github)

[![License](https://img.shields.io/hexpm/l/ueberauth_github.svg)](https://github.com/ueberauth/ueberauth_github/blob/master/LICENSE.md)

[![Last Updated](https://img.shields.io/github/last-commit/ueberauth/ueberauth_github.svg)](https://github.com/ueberauth/ueberauth_github/commits/master)

> GitHub OAuth2 strategy for Überauth.

> 

> 

 Installation

---------------

1. Setup your application at [GitHub Developer](https://developer.github.com).

2. Add `:ueberauth_github` to your list of dependencies in `mix.exs`:

```

def deps do

 [

 {: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:

```

defmodule MyApp.Router do

 use MyApp.Web, :router

 pipeline :browser do

 plug Ueberauth

 ...

 end

end

```

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

```

scope "/auth", MyApp do

 pipe\_through :browser

 get "/:provider", AuthController, :request

 get "/:provider/callback", AuthController, :callback

end

```

7. Your controller needs to implement callbacks to deal with [`Ueberauth.Auth`](https://hexdocs.pm/ueberauth/0.10.3/Ueberauth.Auth.html)

and [`Ueberauth.Failure`](https://hexdocs.pm/ueberauth/0.10.3/Ueberauth.Failure.html) responses.

For an example implementation see the [Überauth Example](https://github.com/ueberauth/ueberauth_example) application.

 Calling

----------

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 read

and write access to the GitHub user profile details and public repos. For a

read-only scope, either use `"user:email"` or an empty scope `""`. Empty scope

will only request minimum public information which even excludes user's email address

which results in a `nil` for `email` inside returned `%Ueberauth.Auth.Info{}`.

See more at [GitHub's OAuth Documentation](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/about-scopes-for-oauth-apps/).

Scope can be configured either explicitly as a `scope` query value on the

request 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 the `redirect_uri` to GitHub.

This is particularly useful when your production application sits behind a

proxy that handles SSL connections. In this case, the `redirect_uri` sent by

[`Ueberauth`](https://hexdocs.pm/ueberauth/0.10.3/Ueberauth.html) will start with `http` instead of `https`, and if you configured

your GitHub OAuth application's callback URL to use HTTPS, GitHub will throw an

`uri_mismatch` error.

To prevent [`Ueberauth`](https://hexdocs.pm/ueberauth/0.10.3/Ueberauth.html) from sending the `redirect_uri`, you should add the

following to your configuration:

```

config :ueberauth, Ueberauth,

 providers: [

 github: {Ueberauth.Strategy.Github, [send\_redirect\_uri: false]}

 ]

```

 Private Emails

-----------------

GitHub now allows you to keep your email address private. If you don't mind

that you won't know a users email address you can specify

`allow_private_emails`. This will set the users email as

`id+username@users.noreply.github.com`.

```

config :ueberauth, Ueberauth,

 providers: [

 github: {Ueberauth.Strategy.Github, [allow\_private\_emails: true]}

 ]

```

 Copyright and License

------------------------

Copyright (c) 2015 Daniel Neighman

This library is released under the MIT License. See the [LICENSE.md](./LICENSE.md) file

[← Previous Page

 

License](license.html)





Ueberauth.Strategy.Github — Üeberauth GitHub v0.8.3

 try {

 if (localStorage.getItem('night-mode') === 'true') {

 document.body.classList.add('night-mode');

 }

 } catch (error) { }

 

Ueberauth.Strategy.Github (Üeberauth GitHub v0.8.3)

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github.ex#L1 "View Source")

=====================================================================================================================================================================================

Provides an Ueberauth strategy for authenticating with GitHub.

### 

 Setup

Create an application in Github for you to use.

Register a new application at: [your github developer page](https://github.com/settings/developers)

and get the `client_id` and `client_secret`.

Include the provider in your configuration for Ueberauth;

```

config :ueberauth, Ueberauth,

 providers: [

 github: { Ueberauth.Strategy.Github, [] }

 ]

```

Then include the configuration for GitHub:

```

config :ueberauth, Ueberauth.Strategy.Github.OAuth,

 client\_id: System.get\_env("GITHUB\_CLIENT\_ID"),

 client\_secret: System.get\_env("GITHUB\_CLIENT\_SECRET")

```

If you haven't already, create a pipeline and setup routes for your callback handler

```

pipeline :auth do

 Ueberauth.plug "/auth"

end

scope "/auth" do

 pipe\_through [:browser, :auth]

 get "/:provider/callback", AuthController, :callback

end

```

Create an endpoint for the callback where you will handle the

[`Ueberauth.Auth`](https://hexdocs.pm/ueberauth/0.10.3/Ueberauth.Auth.html) struct:

```

defmodule MyApp.AuthController do

 use MyApp.Web, :controller

 def callback\_phase(%{ assigns: %{ ueberauth\_failure: fails } } = conn, \_params) do

 # do things with the failure

 end

 def callback\_phase(%{ assigns: %{ ueberauth\_auth: auth } } = conn, params) do

 # do things with the auth

 end

end

```

You can edit the behaviour of the Strategy by including some options when you

register your provider.

To set the `uid_field`:

```

config :ueberauth, Ueberauth,

 providers: [

 github: { Ueberauth.Strategy.Github, [uid\_field: :email] }

 ]

```

Default is `:id`.

To set the default 'scopes' (permissions):

```

config :ueberauth, Ueberauth,

 providers: [

 github: { Ueberauth.Strategy.Github, [default\_scope: "user,public\_repo"] }

 ]

```

Default is empty ("") which "Grants read-only access to public information

(includes public user profile info, public repository info, and gists)"

[Link to this section](#summary)

 Summary

==========================================

[Functions](#functions)

------------------------

[credentials(conn)](#credentials/1)

Includes the credentials from the GitHub response.

[default\_options()](#default_options/0)

Callback implementation for [`Ueberauth.Strategy.default_options/0`](https://hexdocs.pm/ueberauth/0.10.3/Ueberauth.Strategy.html#c:default_options/0).

[extra(conn)](#extra/1)

Stores the raw information (including the token) obtained from the GitHub

callback.

[handle\_cleanup!(conn)](#handle_cleanup!/1)

Cleans up the private area of the connection used for passing the raw GitHub

response around during the callback.

[handle\_request!(conn)](#handle_request!/1)

Handles the initial redirect to the github authentication page.

[info(conn)](#info/1)

Fetches the fields to populate the info section of the [`Ueberauth.Auth`](https://hexdocs.pm/ueberauth/0.10.3/Ueberauth.Auth.html)

struct.

[uid(conn)](#uid/1)

Fetches the `:uid` field from the GitHub response.

[Link to this section](#functions)

Functions

=============================================

[Link to this function](#credentials/1 "Link to this function")

credentials(conn)

=================

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github.ex#L151 "View Source")

Includes the credentials from the GitHub response.

[Link to this function](#default_options/0 "Link to this function")

default\_options()

==================

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github.ex#L74 "View Source")

Callback implementation for [`Ueberauth.Strategy.default_options/0`](https://hexdocs.pm/ueberauth/0.10.3/Ueberauth.Strategy.html#c:default_options/0).

[Link to this function](#extra/1 "Link to this function")

extra(conn)

===========

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github.ex#L203 "View Source")

Stores the raw information (including the token) obtained from the GitHub

callback.

[Link to this function](#handle_cleanup!/1 "Link to this function")

handle\_cleanup!(conn)

======================

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github.ex#L133 "View Source")

Cleans up the private area of the connection used for passing the raw GitHub

response around during the callback.

[Link to this function](#handle_request!/1 "Link to this function")

handle\_request!(conn)

======================

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github.ex#L93 "View Source")

Handles the initial redirect to the github authentication page.

To customize the scope (permissions) that are requested by github include

them as part of your url:

```

"/auth/github?scope=user,public\_repo,gist"

```

[Link to this function](#info/1 "Link to this function")

info(conn)

==========

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github.ex#L170 "View Source")

Fetches the fields to populate the info section of the [`Ueberauth.Auth`](https://hexdocs.pm/ueberauth/0.10.3/Ueberauth.Auth.html)

struct.

[Link to this function](#uid/1 "Link to this function")

uid(conn)

=========

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github.ex#L144 "View Source")

Fetches the `:uid` field from the GitHub response.

This defaults to the option `:uid_field` which in-turn defaults to `:id`





Ueberauth.Strategy.Github.OAuth — Üeberauth GitHub v0.8.3

 try {

 if (localStorage.getItem('night-mode') === 'true') {

 document.body.classList.add('night-mode');

 }

 } catch (error) { }

 

Ueberauth.Strategy.Github.OAuth (Üeberauth GitHub v0.8.3)

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github/oauth.ex#L1 "View Source")

=================================================================================================================================================================================================

An implementation of OAuth2 for GitHub.

To add your `:client_id` and `:client_secret` include these values in your

configuration:

```

config :ueberauth, Ueberauth.Strategy.Github.OAuth,

 client\_id: System.get\_env("GITHUB\_CLIENT\_ID"),

 client\_secret: System.get\_env("GITHUB\_CLIENT\_SECRET")

```

[Link to this section](#summary)

 Summary

==========================================

[Functions](#functions)

------------------------

[authorize\_url(client, params)](#authorize_url/2)

Callback implementation for [`OAuth2.Strategy.authorize_url/2`](https://hexdocs.pm/oauth2/2.0.0/OAuth2.Strategy.html#c:authorize_url/2).

[authorize\_url!(params \\ [], opts \\ [])](#authorize_url!/2)

Provides the authorize url for the request phase of Ueberauth.

[client(opts \\ [])](#client/1)

Construct a client for requests to GitHub.

[get(token, url, headers \\ [], opts \\ [])](#get/4)

[get\_token(client, params, headers)](#get_token/3)

Callback implementation for [`OAuth2.Strategy.get_token/3`](https://hexdocs.pm/oauth2/2.0.0/OAuth2.Strategy.html#c:get_token/3).

[get\_token!(params \\ [], options \\ [])](#get_token!/2)

[Link to this section](#functions)

Functions

=============================================

[Link to this function](#authorize_url/2 "Link to this function")

authorize\_url(client, params)

==============================

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github/oauth.ex#L84 "View Source")

Callback implementation for [`OAuth2.Strategy.authorize_url/2`](https://hexdocs.pm/oauth2/2.0.0/OAuth2.Strategy.html#c:authorize_url/2).

[Link to this function](#authorize_url!/2 "Link to this function")

authorize\_url!(params \\ [], opts \\ [])

=========================================

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github/oauth.ex#L61 "View Source")

Provides the authorize url for the request phase of Ueberauth.

No need to call this usually.

[Link to this function](#client/1 "Link to this function")

client(opts \\ [])

==================

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github/oauth.ex#L37 "View Source")

Construct a client for requests to GitHub.

Optionally include any OAuth2 options here to be merged with the defaults:

```

Ueberauth.Strategy.Github.OAuth.client(

 redirect\_uri: "http://localhost:4000/auth/github/callback"

)

```

This will be setup automatically for you in [`Ueberauth.Strategy.Github`](Ueberauth.Strategy.Github.html).

These options are only useful for usage outside the normal callback phase of

Ueberauth.

[Link to this function](#get/4 "Link to this function")

get(token, url, headers \\ [], opts \\ [])

==========================================

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github/oauth.ex#L67 "View Source")

[Link to this function](#get_token/3 "Link to this function")

get\_token(client, params, headers)

===================================

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github/oauth.ex#L88 "View Source")

Callback implementation for [`OAuth2.Strategy.get_token/3`](https://hexdocs.pm/oauth2/2.0.0/OAuth2.Strategy.html#c:get_token/3).

[Link to this function](#get_token!/2 "Link to this function")

get\_token!(params \\ [], options \\ [])

========================================

[View Source](https://github.com/ueberauth/ueberauth_github/blob/#v{@version}/lib/ueberauth/strategy/github/oauth.ex#L74 "View Source")





API Reference — Üeberauth GitHub v0.8.3

 try {

 if (localStorage.getItem('night-mode') === 'true') {

 document.body.classList.add('night-mode');

 }

 } catch (error) { }

 

 API Reference Üeberauth GitHub v0.8.3

=======================================

 Modules

----------

[Ueberauth.Strategy.Github](Ueberauth.Strategy.Github.html)

Provides an Ueberauth strategy for authenticating with GitHub.

[Ueberauth.Strategy.Github.OAuth](Ueberauth.Strategy.Github.OAuth.html)

An implementation of OAuth2 for GitHub.

[Next Page →

 

Changelog](changelog.html)

