|
| 1 | +--- |
| 2 | +title: OAuth | developer.github.com |
| 3 | +--- |
| 4 | + |
| 5 | +# OAuth |
| 6 | + |
| 7 | +OAuth2 is a protocol that lets external apps request authorization to |
| 8 | +private details in a user's GitHub account without getting their |
| 9 | +password. This is preferred over Basic Authentication because tokens can |
| 10 | +be limited to specific types of data, and can be revoked by users at any |
| 11 | +time. |
| 12 | + |
| 13 | +All developers need to [register their |
| 14 | +application](https://github.com/account/applications/new) before getting |
| 15 | +started. A registered OAuth application is assigned a unique Client ID |
| 16 | +and Client Secret. The Client Secret should not be shared. |
| 17 | + |
| 18 | +## Web Application Flow |
| 19 | + |
| 20 | +This is a description of the OAuth flow from 3rd party web sites. |
| 21 | + |
| 22 | +### 1. Redirect users to request GitHub access |
| 23 | + |
| 24 | + GET https://github.com/login/oauth/authorize |
| 25 | + |
| 26 | +### Parameters |
| 27 | + |
| 28 | +client\_id |
| 29 | +: _Required_ **string** - The client ID you received from GitHub when |
| 30 | +you [registered](https://github.com/account/applications/new). |
| 31 | + |
| 32 | +redirect\_uri |
| 33 | +: _Optional_ **string** - URL in your app where user's will be sent |
| 34 | +after authorization. See details below about [redirect |
| 35 | +urls](#redirect-urls). |
| 36 | + |
| 37 | +scope |
| 38 | +: _Optional_ **string** - Comma separated list of [scopes](#scopes). |
| 39 | + |
| 40 | +### 2. GitHub redirects back to your site |
| 41 | + |
| 42 | +If the user accepts your request, GitHub redirects back to your site |
| 43 | +with a temporary code in a code parameter. Exchange this for an access |
| 44 | +token: |
| 45 | + |
| 46 | + POST https://github.com/login/oauth/access_token |
| 47 | + |
| 48 | +### Parameters |
| 49 | + |
| 50 | +client\_id |
| 51 | +: _Required_ **string** - The client ID you received from GitHub when |
| 52 | +you [registered](https://github.com/account/applications/new). |
| 53 | + |
| 54 | +redirect\_uri |
| 55 | +: _Optional_ **string** |
| 56 | + |
| 57 | +client\_secret |
| 58 | +: _Required_ **string** - The client secret you received from GitHub |
| 59 | +when you [registered](https://github.com/account/applications/new). |
| 60 | + |
| 61 | +code |
| 62 | +: _Required_ **string** - The code you received as a response to [Step 1](#redirect-users-to-request-github-access). |
| 63 | + |
| 64 | +### Response |
| 65 | + |
| 66 | +access\_token |
| 67 | +: _Required_ **string** - OAuth access token. |
| 68 | + |
| 69 | +### 3. Use the access token to access the API |
| 70 | + |
| 71 | +The access token allows you to make requests to the API on a behalf of a user. |
| 72 | + |
| 73 | + GET https://api.github.com/user?access_token=... |
| 74 | + |
| 75 | +## Desktop Application Flow |
| 76 | + |
| 77 | +Use basic authentication for now... |
| 78 | + |
| 79 | +## Redirect URLs |
| 80 | + |
| 81 | +The `redirect_uri` parameter is optional. If left out, GitHub will |
| 82 | +redirect users to the callback URL configured in the OAuth Application |
| 83 | +settings. If provided, the redirect URL must match the callback URL's |
| 84 | +host. |
| 85 | + |
| 86 | + CALLBACK: http://foo.com |
| 87 | + |
| 88 | + GOOD: https://foo.com |
| 89 | + GOOD: http://foo.com/bar |
| 90 | + BAD: http://foo:com:8080 |
| 91 | + BAD: http://bar.com |
| 92 | + |
| 93 | +## Scopes |
| 94 | + |
| 95 | +Scopes let you specify exactly what type of access you need. This will |
| 96 | +be displayed to the user on the authorize form. |
| 97 | + |
| 98 | +(no scope) |
| 99 | +: public read-only access (includes public user profile info, public |
| 100 | +repo info, and gists). |
| 101 | + |
| 102 | +user |
| 103 | +: DB read/write access to profile info only. |
| 104 | + |
| 105 | +public\_repo |
| 106 | +: DB read/write access, and Git read access to public repos. |
| 107 | + |
| 108 | +repo |
| 109 | +: DB read/write access, and Git read access to public and private repos. |
| 110 | + |
| 111 | +gist |
| 112 | +: write access to gists. |
| 113 | + |
| 114 | +NOTE: Your application can request the scopes in the initial redirection. You |
| 115 | +can specify multiple scopes by separating them by a comma. |
| 116 | + |
| 117 | + https://github.com/login/oauth/authorize? |
| 118 | + client_id=...& |
| 119 | + scope=user,public_repo |
| 120 | + |
| 121 | + |
| 122 | +## More Information |
| 123 | + |
| 124 | +It can be a little tricky to get started with OAuth. Here are a few |
| 125 | +links that might be of help: |
| 126 | + |
| 127 | +* [OAuth 2 spec](http://tools.ietf.org/html/draft-ietf-oauth-v2-07) |
| 128 | +* [Facebook API](http://developers.facebook.com/docs/authentication/) |
| 129 | +* [Ruby OAuth2 lib](https://github.com/intridea/oauth2) |
| 130 | +* [simple ruby/sinatra example](https://gist.github.com/9fd1a6199da0465ec87c) |
| 131 | +* [simple python example](https://gist.github.com/e3fbd47fbb7ee3c626bb) using [python-oauth2](http://github.com/dgouldin/python-oauth2) |
| 132 | +* [Ruby OmniAuth example](http://github.com/intridea/omniauth) |
| 133 | +* [Ruby Sinatra extension](http://github.com/atmos/sinatra_auth_github) |
| 134 | +* [Ruby Warden strategy](http://github.com/atmos/warden-github) |
| 135 | +* [Node.js demo using Nozzle](http://github.com/fictorial/nozzle/blob/master/demo/08-github-oauth2.js) |
0 commit comments