Commit aa38cfe
committed
Document and announce enhancements for 2FA
1 parent 1e31049 commit aa38cfe
5 files changed
Lines changed: 182 additions & 11 deletions
File tree
- content
- changes
- v3
- layouts
- lib
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -0,0 +1,50 @@ | |||
| 1 | + --- | ||
| 2 | + kind: change | ||
| 3 | + title: Two-Factor Authentication and the API | ||
| 4 | + created_at: 2013-09-03 | ||
| 5 | + author_name: mastahyeti | ||
| 6 | + --- | ||
| 7 | + | ||
| 8 | + As [announced earlier today][dotcom-blog-post], GitHub.com now supports two-factor | ||
| 9 | + authentication (2FA) for increased security. For users with this feature | ||
| 10 | + enabled, GitHub.com will prompt for a 2FA code in addition to a username and | ||
| 11 | + password during authentication. We've also rolled out some improvements to the | ||
| 12 | + API to ensure that 2FA requirements in the API are consistent with GitHub.com. | ||
| 13 | + | ||
| 14 | + ## Authenticating with the API | ||
| 15 | + | ||
| 16 | + For users without 2FA enabled, and for applications using the [OAuth web | ||
| 17 | + flow](/v3/oauth/#web-application-flow) for authentication, everything is | ||
| 18 | + business as usual. You'll continue to authenticate with the API just as you | ||
| 19 | + always have. (That was easy.) | ||
| 20 | + | ||
| 21 | + If you enable 2FA _and_ use Basic Authentication to access the API, we're | ||
| 22 | + providing multiple options to make the flow simple and easy. | ||
| 23 | + | ||
| 24 | + ## Basic Authentication and 2FA | ||
| 25 | + | ||
| 26 | + ### Personal Access Tokens | ||
| 27 | + | ||
| 28 | + Personal access tokens provide the simplest option for using 2FA with Basic | ||
| 29 | + Authentication. You can create these tokens via the [application settings page | ||
| 30 | + on GitHub.com](https://github.com/settings/applications), and you can revoke | ||
| 31 | + them at any time. For more information about authenticating to the API with | ||
| 32 | + personal access tokens, be sure to check out our [help article on the | ||
| 33 | + topic][personal-access-tokens]. | ||
| 34 | + | ||
| 35 | + ### Tightly-integrated 2FA | ||
| 36 | + | ||
| 37 | + For developers wishing to integrate GitHub 2FA directly into their application, | ||
| 38 | + the API's Basic Authentication now supports the [ability to send the user's 2FA | ||
| 39 | + code][basic-auth-2fa], in addition to the username and password. | ||
| 40 | + | ||
| 41 | + ## We're here to help | ||
| 42 | + | ||
| 43 | + We think GitHub users are going to love the additional security provided by | ||
| 44 | + two-factor authentication. As always, if you have any questions or feedback, | ||
| 45 | + [let us know][contact]. We're here to help! | ||
| 46 | + | ||
| 47 | + [basic-auth-2fa]: /v3/auth/#working-with-two-factor-authentication | ||
| 48 | + [contact]: https://github.com/contact?form[subject]=2FA+and+the+API | ||
| 49 | + [dotcom-blog-post]: https://github.com/blog/1614-two-factor-authentication | ||
| 50 | + [personal-access-tokens]: https://help.github.com/articles/creating-an-access-token-for-command-line-use | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -0,0 +1,76 @@ | |||
| 1 | + --- | ||
| 2 | + title: Authentication | GitHub API | ||
| 3 | + --- | ||
| 4 | + | ||
| 5 | + # Authentication | ||
| 6 | + | ||
| 7 | + * TOC | ||
| 8 | + {:toc} | ||
| 9 | + | ||
| 10 | + While the API provides multiple methods for authentication, we strongly | ||
| 11 | + recommend using [OAuth](/v3/oauth/) for production applications. The other | ||
| 12 | + methods provided are intended to be used for scripts or testing (i.e., cases | ||
| 13 | + where full OAuth would be overkill). Third party applications that rely on | ||
| 14 | + GitHub for authentication should not ask for or collect GitHub credentials. | ||
| 15 | + Instead, they should use the [OAuth web flow](/v3/oauth). | ||
| 16 | + | ||
| 17 | + ## Basic Authentication | ||
| 18 | + | ||
| 19 | + The API supports Basic Authentication as defined in | ||
| 20 | + [RFC2617](http://www.ietf.org/rfc/rfc2617.txt) with a few slight differences. | ||
| 21 | + The main difference is that the RFC requires unauthenticated requests to be | ||
| 22 | + answered with `401 Unauthorized` responses. In many places, this would disclose | ||
| 23 | + the existence of user data. Instead, the GitHub API responds with `404 Not Found`. | ||
| 24 | + This may cause problems for HTTP libraries that assume a `401 Unauthorized` | ||
| 25 | + response. The solution is to manually craft the `Authorization` header. | ||
| 26 | + | ||
| 27 | + ### Via Username and Password | ||
| 28 | + | ||
| 29 | + To use Basic Authentication with the GitHub API, simply send the username and | ||
| 30 | + password associated with the account. | ||
| 31 | + | ||
| 32 | + For example, if you're accessing the API via [cURL][curl], the following command | ||
| 33 | + would authenticate with `mojombo` as the username. (cURL will prompt you to | ||
| 34 | + enter the password.) | ||
| 35 | + | ||
| 36 | + <pre class='terminal'> | ||
| 37 | + curl -u mojombo https://api.github.com/user | ||
| 38 | + </pre> | ||
| 39 | + | ||
| 40 | + ### Via OAuth Tokens | ||
| 41 | + | ||
| 42 | + Alternatively, you can authenticate using [personal access | ||
| 43 | + tokens][personal-access-tokens] or OAuth tokens. To do so, provide the token as | ||
| 44 | + the username and provide a blank password or a password of `x-oauth-basic`. For | ||
| 45 | + example: | ||
| 46 | + | ||
| 47 | + <pre class='terminal'> | ||
| 48 | + curl -u 3816d821c80a6847ca84550052c1ff6246e8169b:x-oauth-basic https://api.github.com/user | ||
| 49 | + </pre> | ||
| 50 | + | ||
| 51 | + This approach is useful if your tools only support Basic Authentication but you | ||
| 52 | + want to take advantage of OAuth access token security features. | ||
| 53 | + | ||
| 54 | + ## Working with two-factor authentication | ||
| 55 | + | ||
| 56 | + For users with two-factor authentication enabled, Basic Authentication requires | ||
| 57 | + an extra step. When you attempt to authenticate with Basic Authentication, the | ||
| 58 | + server will respond with a `401` and an `X-GitHub-OTP: required;:2fa-type` | ||
| 59 | + header. This indicates that a two-factor authentication code is needed (in | ||
| 60 | + addition to the username and password). The `:2fa-type` in this header indicates | ||
| 61 | + whether the account receives its two-factor authentication codes via SMS or via | ||
| 62 | + an application. | ||
| 63 | + | ||
| 64 | + In additon to the Basic Authentication credentials, you must send the user's | ||
| 65 | + authentication code (i.e., one-time password) in the `X-GitHub-OTP` header. | ||
| 66 | + Because these authentication codes expire quickly, we recommend using the | ||
| 67 | + Authorizations API to [create an access token][create-access] and using that | ||
| 68 | + token to [authenticate via OAuth][oauth-auth] for most API access. | ||
| 69 | + | ||
| 70 | + Alternately, you can create access tokens from the Personal Access Token | ||
| 71 | + section of your [application settings page](https://github.com/settings/application). | ||
| 72 | + | ||
| 73 | + [create-access]: /v3/oauth/#create-a-new-authorization | ||
| 74 | + [curl]: http://curl.haxx.se/ | ||
| 75 | + [oauth-auth]: /v3/#authentication | ||
| 76 | + [personal-access-tokens]: https://github.com/blog/1509-personal-api-tokens | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -9,7 +9,7 @@ title: OAuth | GitHub API | |||
| 9 | 9 | ||
| 10 | 10 | OAuth2 is a protocol that lets external apps request authorization to | |
| 11 | 11 | private details in a user's GitHub account without getting their | |
| 12 | - password. This is preferred over Basic Authentication because tokens can | ||
| 12 | + password. This is preferred over [Basic Authentication](/v3/auth#basic-authentication) because tokens can | ||
| 13 | 13 | be limited to specific types of data, and can be revoked by users at any | |
| 14 | 14 | time. | |
| 15 | 15 | ||
@@ -97,10 +97,12 @@ The access token allows you to make requests to the API on a behalf of a user. | |||
| 97 | 97 | ||
| 98 | 98 | ## Non-Web Application Flow | |
| 99 | 99 | ||
| 100 | - Use basic authentication to create an OAuth2 token using the [interface | ||
| 101 | - below](/v3/oauth/#create-a-new-authorization). With this technique, a username | ||
| 102 | - and password need not be stored permanently, and the user can revoke access at | ||
| 103 | - any time. | ||
| 100 | + Use [Basic Authentication](/v3/auth#basic-authentication) to create an OAuth2 | ||
| 101 | + token using the [interface below](/v3/oauth/#create-a-new-authorization). With | ||
| 102 | + this technique, a username and password need not be stored permanently, and the | ||
| 103 | + user can revoke access at any time. (Make sure to understand how to [work with | ||
| 104 | + two-factor authentication](/v3/auth/#working-with-two-factor-authentication) if | ||
| 105 | + you or your users have two-factor authentication enabled.) | ||
| 104 | 106 | ||
| 105 | 107 | ## Redirect URLs | |
| 106 | 108 | ||
@@ -185,8 +187,11 @@ can specify multiple scopes by separating them by a comma. | |||
| 185 | 187 | ||
| 186 | 188 | ## OAuth Authorizations API | |
| 187 | 189 | ||
| 188 | - There is an API for users to manage their own tokens. You can only | ||
| 189 | - access your own tokens, and only through Basic Authentication. | ||
| 190 | + There is an API for users to manage their own tokens. You can only access your | ||
| 191 | + own tokens, and only via [Basic Authentication](/v3/auth#basic-authentication). | ||
| 192 | + (Make sure to understand how to [work with two-factor | ||
| 193 | + authentication](/v3/auth/#working-with-two-factor-authentication) if you or your | ||
| 194 | + users have two-factor authentication enabled.) | ||
| 190 | 195 | ||
| 191 | 196 | ## List your authorizations | |
| 192 | 197 | ||
@@ -210,7 +215,7 @@ access your own tokens, and only through Basic Authentication. | |||
| 210 | 215 | ||
| 211 | 216 | If you need a small number of tokens, implementing the [web flow](#web-application-flow) | |
| 212 | 217 | can be cumbersome. Instead, tokens can be created using the Authorizations API using | |
| 213 | - Basic Authentication. To create tokens for a particular OAuth application, you | ||
| 218 | + [Basic Authentication](/v3/auth#basic-authentication). To create tokens for a particular OAuth application, you | ||
| 214 | 219 | must provide its client ID and secret, found on the OAuth application settings | |
| 215 | 220 | page, linked from your [OAuth applications listing on GitHub][app-listing]. OAuth tokens | |
| 216 | 221 | can also be created through the web UI via the [Application settings page](https://github.com/settings/applications). | |
@@ -245,6 +250,45 @@ token. | |||
| 245 | 250 | %> | |
| 246 | 251 | <%= json :oauth_access %> | |
| 247 | 252 | ||
| 253 | + ## Get-or-create an authorization for a specific app | ||
| 254 | + | ||
| 255 | + This method will create a new authorization for the specified OAuth application, | ||
| 256 | + only if an authorization for that application doesn't already exist for the | ||
| 257 | + user. (The URL includes the 20 character client ID for the OAuth app that is | ||
| 258 | + requesting the token.) It returns the user's token for the application if one | ||
| 259 | + exists. Otherwise, it creates one. | ||
| 260 | + | ||
| 261 | + PUT /authorizations/clients/:client_id | ||
| 262 | + | ||
| 263 | + ### Input | ||
| 264 | + | ||
| 265 | + client_secret | ||
| 266 | + : **String** - The 40 character OAuth app client secret associated with the | ||
| 267 | + client ID specified in the URL. | ||
| 268 | + | ||
| 269 | + scopes | ||
| 270 | + : _Optional_ **array** - A list of scopes that this authorization is in. | ||
| 271 | + | ||
| 272 | + note | ||
| 273 | + : _Optional_ **string** - A note to remind you what the OAuth token is for. | ||
| 274 | + | ||
| 275 | + note_url | ||
| 276 | + : _Optional_ **string** - A URL to remind you what app the OAuth token is for. | ||
| 277 | + | ||
| 278 | + <%= json :client_secret => "abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd", :scopes => ["public_repo"], :note => 'admin script' %> | ||
| 279 | + | ||
| 280 | + ### Response if returning a new token | ||
| 281 | + | ||
| 282 | + <%= headers 201, :Location => "https://api.github.com/authorizations/1" | ||
| 283 | + %> | ||
| 284 | + <%= json :oauth_access %> | ||
| 285 | + | ||
| 286 | + ### Response if returning an existing token | ||
| 287 | + | ||
| 288 | + <%= headers 200, :Location => "https://api.github.com/authorizations/1" | ||
| 289 | + %> | ||
| 290 | + <%= json :oauth_access %> | ||
| 291 | + | ||
| 248 | 292 | ## Update an existing authorization | |
| 249 | 293 | ||
| 250 | 294 | PATCH /authorizations/:id | |
@@ -289,7 +333,7 @@ You can only send one of these scope keys at a time. | |||
| 289 | 333 | OAuth applications can use a special API method for checking OAuth token | |
| 290 | 334 | validity without running afoul of normal rate limits for failed login attempts. | |
| 291 | 335 | Authentication works differently with this particular endpoint. You must use | |
| 292 | - Basic Authentication when accessing it, where the username is the OAuth | ||
| 336 | + [Basic Authentication](/v3/auth#basic-authentication) when accessing it, where the username is the OAuth | ||
| 293 | 337 | application `client_id` and the password is its `client_secret`. Invalid tokens | |
| 294 | 338 | will return `404 NOT FOUND`. | |
| 295 | 339 | ||
@@ -300,7 +344,6 @@ will return `404 NOT FOUND`. | |||
| 300 | 344 | <%= headers 200 %> | |
| 301 | 345 | <%= json(:oauth_access_with_user) %> | |
| 302 | 346 | ||
| 303 | - | ||
| 304 | 347 | ## More Information | |
| 305 | 348 | ||
| 306 | 349 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -49,6 +49,7 @@ <h3><a href="#" class="js-expand-btn collapsed"> </a><a href="/v3/">Overvie | |||
| 49 | 49 | <li><a href="/v3/media/">Media Types</a></li> | |
| 50 | 50 | <li><a href="/v3/meta/">Meta</a></li> | |
| 51 | 51 | <li><a href="/v3/oauth/">OAuth</a></li> | |
| 52 | + <li><a href="/v3/auth/">Other Authentication Methods</a></li> | ||
| 52 | 53 | <li><a href="/v3/rate_limit/">Rate Limit</a></li> | |
| 53 | 54 | <li><a href="/v3/troubleshooting/">Troubleshooting</a></li> | |
| 54 | 55 | </ul> | |
| 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 | |
0 commit comments