Skip to content

Instantly share code, notes, and snippets.

@leegao

leegao/github_oauth_busy_developer_guide.md

Forked from technoweenie/github_oauth_busy_developer_guide.md
Created June 7, 2010 11:46
Show Gist options
  • Save leegao/428576 to your computer and use it in GitHub Desktop.
Save leegao/428576 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
github_oauth_busy_developer_guide.md

GitHub OAuth Busy Developer's Guide

This is a quick guide to OAuth2 support in GitHub for developers. This is still experimental and could change at any moment. This Gist will serve as a living document until it becomes finalized at Develop.GitHub.com.

OAuth2 is a protocol that lets external apps request authorization to private details in your GitHub account without getting your password. All developers need to register their application before getting started.

Web Application Flow

  • Redirect to this link to request GitHub access:
https://github.com/login/oauth/authorize?
  client_id=...&
  redirect_uri=http://www.example.com/oauth_redirect
  • If 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 Flow

This is similar to the Web Application flow, but designed for javascript/ajax applications. The main difference is there is no temporary code used. The access token is included in the redirection from GitHub in a URI fragment.

  • Redirect to this link to request GitHub access (note the use of the type parameter):
https://github.com/login/oauth/authorize?
  client_id=...&
  type=user_agent&
  redirect_uri=http://www.example.com/oauth_redirect
  • If the user accepts your request, GitHub redirects back to your site with the access_code in a URI fragment. Given the example above, GitHub will redirect to: http://www.example.com/oauth_redirect#access_token=...

Desktop flow

The desktop flow relies on having an embedded browser in your application. The redirection is handled the same way, but a special GitHub callback URL is sent. Then your desktop application can watch for GitHub to redirect back to it.

  • Redirect to this link to request GitHub access (note the use of the type and redirect_uri parameteres):
https://github.com/login/oauth/authorize?
  client_id=...&
  type=user_agent&
  redirect_uri=https://github.com/login/oauth/success
  • If the user accepts your request, GitHub redirects back to your site with the access_code in a URI fragment. Given the example above, GitHub will redirect to: https://github.com/login/oauth/success#access_token=...

It is up to your desktop application to intercept this custom URL and parse the access_token for use in the rest of the application.

Scopes

  • (no scope) - public read-only access.
  • user - DB read/write access to profile info only.
  • public_repos - DB read/write access, and Git read access to public repos (not implemented yet).
  • repos - DB read/write access, and Git read access to public and private repos (not implemented yet).
  • gists - read/write access to public and private gists (not implemented yet).

Your application can request the scopes in the initial redirection:

https://github.com/login/oauth/authorize?
  client_id=...&
  scope=user,public_repos&
  redirect_uri=http://www.example.com/oauth_redirect

References

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment