Document and announce enhancements for 2FA

jasonrudolph · jasonrudolph · commit aa38cfe98232 · 2013-09-03T13:48:17.000-04:00
diff --git a/content/changes/2013-09-03-two-factor-authentication.md b/content/changes/2013-09-03-two-factor-authentication.md
@@ -0,0 +1,50 @@
+---
+kind: change
+title: Two-Factor Authentication and the API
+created_at: 2013-09-03
+author_name: mastahyeti
+---
+
+As [announced earlier today][dotcom-blog-post], GitHub.com now supports two-factor
+authentication (2FA) for increased security. For users with this feature
+enabled, GitHub.com will prompt for a 2FA code in addition to a username and
+password during authentication. We've also rolled out some improvements to the
+API to ensure that 2FA requirements in the API are consistent with GitHub.com.
+
+## Authenticating with the API
+
+For users without 2FA enabled, and for applications using the [OAuth web
+flow](/v3/oauth/#web-application-flow) for authentication, everything is
+business as usual. You'll continue to authenticate with the API just as you
+always have. (That was easy.)
+
+If you enable 2FA _and_ use Basic Authentication to access the API, we're
+providing multiple options to make the flow simple and easy.
+
+## Basic Authentication and 2FA
+
+### Personal Access Tokens
+
+Personal access tokens provide the simplest option for using 2FA with Basic
+Authentication. You can create these tokens via the [application settings page
+on GitHub.com](https://github.com/settings/applications), and you can revoke
+them at any time. For more information about authenticating to the API with
+personal access tokens, be sure to check out our [help article on the
+topic][personal-access-tokens].
+
+### Tightly-integrated 2FA
+
+For developers wishing to integrate GitHub 2FA directly into their application,
+the API's Basic Authentication now supports the [ability to send the user's 2FA
+code][basic-auth-2fa], in addition to the username and password.
+
+## We're here to help
+
+We think GitHub users are going to love the additional security provided by
+two-factor authentication. As always, if you have any questions or feedback,
+[let us know][contact]. We're here to help!
+
+[basic-auth-2fa]: /v3/auth/#working-with-two-factor-authentication
+[contact]: https://github.com/contact?form[subject]=2FA+and+the+API
+[dotcom-blog-post]: https://github.com/blog/1614-two-factor-authentication
+[personal-access-tokens]: https://help.github.com/articles/creating-an-access-token-for-command-line-use
diff --git a/content/v3/auth.md b/content/v3/auth.md
@@ -0,0 +1,76 @@
+---
+title: Authentication | GitHub API
+---
+
+# Authentication
+
+* TOC
+{:toc}
+
+While the API provides multiple methods for authentication, we strongly
+recommend using [OAuth](/v3/oauth/) for production applications. The other
+methods provided are intended to be used for scripts or testing (i.e., cases
+where full OAuth would be overkill). Third party applications that rely on
+GitHub for authentication should not ask for or collect GitHub credentials.
+Instead, they should use the [OAuth web flow](/v3/oauth).
+
+## Basic Authentication
+
+The API supports Basic Authentication as defined in
+[RFC2617](http://www.ietf.org/rfc/rfc2617.txt) with a few slight differences.
+The main difference is that the RFC requires unauthenticated requests to be
+answered with `401 Unauthorized` responses. In many places, this would disclose
+the existence of user data. Instead, the GitHub API responds with `404 Not Found`.
+This may cause problems for HTTP libraries that assume a `401 Unauthorized`
+response. The solution is to manually craft the `Authorization` header.
+
+### Via Username and Password
+
+To use Basic Authentication with the GitHub API, simply send the username and
+password associated with the account.
+
+For example, if you're accessing the API via [cURL][curl], the following command
+would authenticate with `mojombo` as the username. (cURL will prompt you to
+enter the password.)
+
+<pre class='terminal'>
+curl -u mojombo https://api.github.com/user
+</pre>
+
+### Via OAuth Tokens
+
+Alternatively, you can authenticate using [personal access
+tokens][personal-access-tokens] or OAuth tokens. To do so, provide the token as
+the username and provide a blank password or a password of `x-oauth-basic`. For
+example:
+
+<pre class='terminal'>
+curl -u 3816d821c80a6847ca84550052c1ff6246e8169b:x-oauth-basic https://api.github.com/user
+</pre>
+
+This approach is useful if your tools only support Basic Authentication but you
+want to take advantage of OAuth access token security features.
+
+## Working with two-factor authentication
+
+For users with two-factor authentication enabled, Basic Authentication requires
+an extra step. When you attempt to authenticate with Basic Authentication, the
+server will respond with a `401` and an `X-GitHub-OTP: required;:2fa-type`
+header. This indicates that a two-factor authentication code is needed (in
+addition to the username and password). The `:2fa-type` in this header indicates
+whether the account receives its two-factor authentication codes via SMS or via
+an application.
+
+In additon to the Basic Authentication credentials, you must send the user's
+authentication code (i.e., one-time password) in the `X-GitHub-OTP` header.
+Because these authentication codes expire quickly, we recommend using the
+Authorizations API to [create an access token][create-access] and using that
+token to [authenticate via OAuth][oauth-auth] for most API access.
+
+Alternately, you can create access tokens from the Personal Access Token
+section of your [application settings page](https://github.com/settings/application).
+
+[create-access]: /v3/oauth/#create-a-new-authorization
+[curl]: http://curl.haxx.se/
+[oauth-auth]: /v3/#authentication
+[personal-access-tokens]: https://github.com/blog/1509-personal-api-tokens
diff --git a/content/v3/oauth.md b/content/v3/oauth.md
@@ -9,7 +9,7 @@ title: OAuth | GitHub API
 
 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
+password. This is preferred over [Basic Authentication](/v3/auth#basic-authentication) because tokens can
 be limited to specific types of data, and can be revoked by users at any
 time.
 
@@ -97,10 +97,12 @@ The access token allows you to make requests to the API on a behalf of a user.
 
 ## Non-Web Application Flow
 
-Use basic authentication to create an OAuth2 token using the [interface
-below](/v3/oauth/#create-a-new-authorization).  With this technique, a username
-and password need not be stored permanently, and the user can revoke access at
-any time.
+Use [Basic Authentication](/v3/auth#basic-authentication) to create an OAuth2
+token using the [interface below](/v3/oauth/#create-a-new-authorization).  With
+this technique, a username and password need not be stored permanently, and the
+user can revoke access at any time. (Make sure to understand how to [work with
+two-factor authentication](/v3/auth/#working-with-two-factor-authentication) if
+you or your users have two-factor authentication enabled.)
 
 ## Redirect URLs
 
@@ -185,8 +187,11 @@ can specify multiple scopes by separating them by a comma.
 
 ## OAuth Authorizations API
 
-There is an API for users to manage their own tokens.  You can only
-access your own tokens, and only through Basic Authentication.
+There is an API for users to manage their own tokens.  You can only access your
+own tokens, and only via [Basic Authentication](/v3/auth#basic-authentication).
+(Make sure to understand how to [work with two-factor
+authentication](/v3/auth/#working-with-two-factor-authentication) if you or your
+users have two-factor authentication enabled.)
 
 ## List your authorizations
 
@@ -210,7 +215,7 @@ access your own tokens, and only through Basic Authentication.
 
 If you need a small number of tokens, implementing the [web flow](#web-application-flow)
 can be cumbersome. Instead, tokens can be created using the Authorizations API using
-Basic Authentication. To create tokens for a particular OAuth application, you
+[Basic Authentication](/v3/auth#basic-authentication). To create tokens for a particular OAuth application, you
 must provide its client ID and secret, found on the OAuth application settings
 page, linked from your [OAuth applications listing on GitHub][app-listing]. OAuth tokens
 can also be created through the web UI via the [Application settings page](https://github.com/settings/applications).
@@ -245,6 +250,45 @@ token.
 %>
 <%= json :oauth_access %>
 
+## Get-or-create an authorization for a specific app
+
+This method will create a new authorization for the specified OAuth application,
+only if an authorization for that application doesn't already exist for the
+user. (The URL includes the 20 character client ID for the OAuth app that is
+requesting the token.) It returns the user's token for the application if one
+exists. Otherwise, it creates one.
+
+    PUT /authorizations/clients/:client_id
+
+### Input
+
+client_secret
+: **String** - The 40 character OAuth app client secret associated with the
+client ID specified in the URL.
+
+scopes
+: _Optional_ **array** - A list of scopes that this authorization is in.
+
+note
+: _Optional_ **string** - A note to remind you what the OAuth token is for.
+
+note_url
+: _Optional_ **string** - A URL to remind you what app the OAuth token is for.
+
+<%= json :client_secret => "abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd", :scopes => ["public_repo"], :note => 'admin script' %>
+
+### Response if returning a new token
+
+<%= headers 201, :Location => "https://api.github.com/authorizations/1"
+%>
+<%= json :oauth_access %>
+
+### Response if returning an existing token
+
+<%= headers 200, :Location => "https://api.github.com/authorizations/1"
+%>
+<%= json :oauth_access %>
+
 ## Update an existing authorization
 
     PATCH /authorizations/:id
@@ -289,7 +333,7 @@ You can only send one of these scope keys at a time.
 OAuth applications can use a special API method for checking OAuth token
 validity without running afoul of normal rate limits for failed login attempts.
 Authentication works differently with this particular endpoint. You must use
-Basic Authentication when accessing it, where the username is the OAuth
+[Basic Authentication](/v3/auth#basic-authentication) when accessing it, where the username is the OAuth
 application `client_id` and the password is its `client_secret`. Invalid tokens
 will return `404 NOT FOUND`.
 
@@ -300,7 +344,6 @@ will return `404 NOT FOUND`.
 <%= headers 200 %>
 <%= json(:oauth_access_with_user) %>
 
-
 ## More Information
 
 
diff --git a/layouts/default.html b/layouts/default.html
@@ -49,6 +49,7 @@ <h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/">Overvie
               <li><a href="/v3/media/">Media Types</a></li>
               <li><a href="/v3/meta/">Meta</a></li>
               <li><a href="/v3/oauth/">OAuth</a></li>
+              <li><a href="/v3/auth/">Other Authentication Methods</a></li>
               <li><a href="/v3/rate_limit/">Rate Limit</a></li>
               <li><a href="/v3/troubleshooting/">Troubleshooting</a></li>
             </ul>
diff --git a/lib/resources.rb b/lib/resources.rb
@@ -35,7 +35,8 @@ module Helpers
         :jasonrudolph => '592e1e6f041f9a4ec51846fd82013aea',
         :Caged        => '97c3a8eea9b7eaa9e1e93ea3cd47399f',
         :foca         => 'd0ca2bf32bda9e9ea8c4473ffc3aaa0d',
-        :ymendel      => 'b1b1d33e0655e841d4fd8467359c58d0'
+        :ymendel      => 'b1b1d33e0655e841d4fd8467359c58d0',
+        :mastahyeti   => '8caa0afdae1a934c30a1998472c63134'
       }
 
       DefaultTimeFormat = "%B %-d, %Y".freeze

Original file line number	Diff line number	Diff line change
`@@ -35,7 +35,8 @@ module Helpers`
`35`	`35`	`:jasonrudolph => '592e1e6f041f9a4ec51846fd82013aea',`
`36`	`36`	`:Caged => '97c3a8eea9b7eaa9e1e93ea3cd47399f',`
`37`	`37`	`:foca => 'd0ca2bf32bda9e9ea8c4473ffc3aaa0d',`
`38`		`- :ymendel => 'b1b1d33e0655e841d4fd8467359c58d0'`
	`38`	`+ :ymendel => 'b1b1d33e0655e841d4fd8467359c58d0',`
	`39`	`+ :mastahyeti => '8caa0afdae1a934c30a1998472c63134'`
`39`	`40`	`}`
`40`	`41`
`41`	`42`	`DefaultTimeFormat = "%B %-d, %Y".freeze`