OAuth
OAuth2 is a protocol that lets external apps request authorization to private details in a user's GitHub account without getting their password. This is preferred over Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.
All developers need to register their application before getting started. A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.
Web Application Flow
This is a description of the OAuth flow from 3rd party web sites.
Redirect users to a this link to request GitHub access.
GET https://github.com/login/oauth/authorize? client_id=...& redirect_uri=http://www.example.com/oauth_redirectIf the user accepts your request, GitHub redirects back to your site with a temporary code in a code parameter. Exchange this for an access token:
POST https://github.com/login/oauth/access_token? client_id=...& redirect_uri=http://www.example.com/oauth_redirect& client_secret=...& code=... RESPONSE: access_token=...You have the access token, so now you can make requests on the user's behalf:
GET https://github.com/api/v2/json/user/show? access_token=...
Javascript/Desktop Flow
These flows are disabled for now...
Redirect URLs
The redirect_uri parameter is optional. If left out, GitHub will
redirect users to the callback URL configured in the OAuth
Application settings. If provided, the redirect URL must match the
callback URL's host.
CALLBACK: http://foo.com
GOOD: https://foo.com
GOOD: http://foo.com/bar
BAD: http://foo:com:8080
BAD: http://bar.com
Scopes
Scopes let you specify exactly what type of access you need. This will be displayed to the user on the authorize form.
- (no scope) - public read-only access (includes user profile info, public repo info, and gists).
user- DB read/write access to profile info only.public_repo- DB read/write access, and Git read access to public repos.repo- DB read/write access, and Git read access to public and private repos.gist- write access to gists.
Your application can request the scopes in the initial redirection. You can specify multiple scopes by separating them by a comma.
https://github.com/login/oauth/authorize?
client_id=...&
scope=user,public_repo
