Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ueberauth/ueberauth_github
GitHub OAuth2 Strategy for Überauth
https://github.com/ueberauth/ueberauth_github
github oauth oauth2 strategy ueberauth ueberauth-strategies
Last synced: 2 months ago
JSON representation
GitHub OAuth2 Strategy for Überauth
- Host: GitHub
- URL: https://github.com/ueberauth/ueberauth_github
- Owner: ueberauth
- License: mit
- Created: 2015-11-15T19:50:08.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2023-05-27T21:19:02.000Z (over 1 year ago)
- Last Synced: 2024-10-05T00:47:50.702Z (3 months ago)
- Topics: github, oauth, oauth2, strategy, ueberauth, ueberauth-strategies
- Language: Elixir
- Homepage:
- Size: 80.1 KB
- Stars: 102
- Watchers: 8
- Forks: 53
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- fucking-awesome-elixir - ueberauth_github - A GitHub strategy for Überauth. (Authentication)
- awesome-elixir - ueberauth_github - A GitHub strategy for Überauth. (Authentication)
- freaking_awesome_elixir - Elixir - A GitHub strategy for Ãberauth. (Authentication)
README
# Überauth GitHub
[](https://travis-ci.org/ueberauth/ueberauth_github)
[](https://hex.pm/packages/ueberauth_github)
[](https://hexdocs.pm/ueberauth_github/)
[](https://hex.pm/packages/ueberauth_github)
[](https://github.com/ueberauth/ueberauth_github/blob/master/LICENSE.md)
[](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`:
```elixir
def deps do
[
{:ueberauth_github, "~> 0.8"}
]
end
```
3. Add GitHub to your Überauth configuration:
```elixir
config :ueberauth, Ueberauth,
providers: [
github: {Ueberauth.Strategy.Github, []}
]
```
4. Update your provider configuration:
```elixir
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:
```elixir
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:
```elixir
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:
```elixir
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`
and `Ueberauth.Failure` 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:
```elixir
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` 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` from sending the `redirect_uri`, you should add the
following to your configuration:
```elixir
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
`[email protected]`.
```elixir
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