Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings
This repository was archived by the owner on Nov 1, 2017. It is now read-only.

Give authorization API dedicated section and document common problems#439

Merged
izuzak merged 1 commit intomasterfromdocument-oauth-errors
Feb 17, 2014
Merged
Show file tree
Hide file tree
Changes fromall commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -34,5 +34,5 @@
No more implementing the [web flow][web-flow] just to get a token tied to your
app's rate limit.

[oauth-api]: /v3/oauth/#oauth-authorizations-api
[oauth-api]: /v3/oauth_authorizations/#oauth-authorizations-api
[web-flow]: /v3/oauth/#web-application-flow
2 changes: 1 addition & 1 deletioncontent/guides/basics-of-authentication.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -347,7 +347,7 @@ available as a separate project.
[sinatra auth github test]: https://github.com/atmos/sinatra-auth-github-test
[oauth scopes]: /v3/oauth/#scopes
[edit scopes post]: /changes/2013-10-04-oauth-changes-coming/
[check token valid]: /v3/oauth/#check-an-authorization
[check token valid]: /v3/oauth_authorizations/#check-an-authorization
[platform samples]: https://github.com/github/platform-samples/tree/master/api/ruby/basics-of-authentication
[new oauth app]: https://github.com/settings/applications/new
[app settings]: https://github.com/settings/applications
2 changes: 1 addition & 1 deletioncontent/guides/getting-started.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -517,7 +517,7 @@ Keep learning with the next API guide [Basics of Authentication][auth guide]!
[media types]: /v3/media/
[oauth]: /v3/oauth/
[webflow]: /v3/oauth/#web-application-flow
[authorizations api]: /v3/oauth/#create-a-new-authorization
[authorizations api]: /v3/oauth_authorizations/#create-a-new-authorization
[scopes]: /v3/oauth/#scopes
[repos-api]: /v3/repos/
[pages]: http://pages.github.com
Expand Down
2 changes: 1 addition & 1 deletioncontent/v3.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -213,7 +213,7 @@ $ curl https://api.github.com/?access_token=OAUTH-TOKEN
</pre>

Read [more about OAuth2](/v3/oauth/). Note that OAuth2 tokens can be [acquired
programmatically](/v3/oauth/#create-a-new-authorization), for applications that
programmatically](/v3/oauth_authorizations/#create-a-new-authorization), for applications that
are not websites.

### OAuth2 Key/Secret
Expand Down
2 changes: 1 addition & 1 deletioncontent/v3/auth.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -71,7 +71,7 @@ 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/applications).

[create-access]: /v3/oauth/#create-a-new-authorization
[create-access]: /v3/oauth_authorizations/#create-a-new-authorization
[curl]: http://curl.haxx.se/
[oauth-auth]: /v3/#authentication
[personal-access-tokens]: https://github.com/blog/1509-personal-api-tokens
221 changes: 60 additions & 161 deletionscontent/v3/oauth.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -110,10 +110,19 @@ The access token allows you to make requests to the API on a behalf of a user.

GET https://api.github.com/user?access_token=...

You can pass the token in the query params like shown above, but a
cleaner approach is to include it in the Authorization header

Authorization: token OAUTH-TOKEN

For example, in curl you can set the Authorization header like this:

curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/user

## Non-Web Application Flow

Use [Basic Authentication](/v3/auth#basic-authentication) to create an OAuth2
token using the [interface below](/v3/oauth/#create-a-new-authorization). With
token using the [interface below](/v3/oauth_authorizations/#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
Expand All@@ -129,7 +138,7 @@ subdirectory of the callback URL.

CALLBACK: http://example.com/path

GOOD:https://example.com/path
GOOD:http://example.com/path
GOOD: http://example.com/path/subdir/other
BAD: http://example.com/bar
BAD: http://example.com/
Expand DownExpand Up@@ -182,189 +191,79 @@ can specify multiple scopes by separating them with a comma:
client_id=...&
scope=user,public_repo

## OAuth Authorizations API

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

GET /authorizations

### Response

<%= headers 200, :pagination => default_pagination_rels %>
<%= json(:oauth_access) { |h| [h] } %>

## Get a single authorization

GET /authorizations/:id

### Response

<%= headers 200 %>
<%= json :oauth_access %>
## Common errors for the authorization request

## Create a new authorization
There are a few things that can go wrong in the process of obtaining an
OAuth token for a user. In the initial authorization request phase,
these are some errors you might see:

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](/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).
Read more about these tokens on the [GitHub Help page](https://help.github.com/articles/creating-an-access-token-for-command-line-use).
### Application Suspended

POST /authorizations
If the OAuth application you set up has been suspended (due to reported
abuse, spam, or a mis-use of the API), GitHub will redirect to the
registered callback URL with the following parameters summerizing the
error:

### Parameters

Name | Type | Description
-----|------|--------------
`scopes`|`array` | A list of scopes that this authorization is in.
`note`|`string` | A note to remind you what the OAuth token is for.
`note_url`|`string` | A URL to remind you what app the OAuth token is for.
`client_id`|`string` | The 20 character OAuth app client key for which to create the token.
`client_secret`|`string` | The 40 character OAuth app client secret for which to create the token.
http://your-application.com/callback?error=application_suspended

Please contact [support](https://github.com/contact) to solve issues
with suspended applications.

<%= json :scopes => ["public_repo"], :note => 'admin script' %>
### Redirect URI mismatch

### Response
If you provide a redirect_uri that doesn't match what you've registered
with your application, GitHub will redirect to the registered callback
URL with the following parameters summerizing the error:

<%= headers 201, :Location => "https://api.github.com/authorizations/1"
%>
<%= json :oauth_access %>
http://your-application.com/callback?error=redirect_uri_mismatch

## Get-or-create an authorization for a specific app
To correct this error, either provide a redirect_uri that matches what
you registered or leave out this parameter to use the default one
registered with your application.

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.
### Access denied

PUT /authorizations/clients/:client_id
If the user rejects access to your application, GItHub will redirect to
the registered callback URL with the following parameters summerizing
the error:

### Parameters
http://your-application.com/callback?error=access_denied

Name | Type | Description
-----|------|--------------
`client_secret`|`string`| The 40 character OAuth app client secret associated with the client ID specified in the URL.
`scopes`|`array` | A list of scopes that this authorization is in.
`note`|`string` | A note to remind you what the OAuth token is for.
`note_url`|`string` | A URL to remind you what app the OAuth token is for.
There's nothing you can do here as users are free to choose not to use
your application. More often that not, users will just close the window
or press back in their browser, so it is likely that you'll never see
this error.

## Common errors for the access token request

<%= json :client_secret => "abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd", :scopes => ["public_repo"], :note => 'admin script' %>
In the second phase of exchanging a code for an access token, there are
an additional set of errors that can occur. The format of these
responses is determined by the accept header you pass. The following
examples only show JSON responses.

###Response if returning a new token
###Invalid client credentials

<%= headers 201, :Location => "https://api.github.com/authorizations/1"
%>
<%= json :oauth_access %>
If the client\_id and or client\_secret you pass are incorrect you will
receive this error response.

### 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

### Parameters

Name | Type | Description
-----|------|--------------
`scopes`|`array` | Replaces the authorization scopes with these.
`add_scopes`|`array` | A list of scopes to add to this authorization.
`remove_scopes`|`array` | A list of scopes to remove from this authorization.
`note`|`string` | A note to remind you what the OAuth token is for.
`note_url`|`string` | A URL to remind you what app the OAuth token is for.


You can only send one of these scope keys at a time.

<%= json :add_scopes => ['repo'], :note => 'admin script' %>

### Response

<%= headers 200 %>
<%= json :oauth_access %>

## Delete an authorization

DELETE /authorizations/:id

### Response

<%= headers 204 %>

## Check an authorization

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](/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`.

GET /applications/:client_id/tokens/:access_token

### Response

<%= headers 200 %>
<%= json(:oauth_access_with_user) %>

## Revoke all authorizations for an application

OAuth application owners can revoke every token for an OAuth application. You
must use [Basic Authentication](/v3/auth#basic-authentication) when calling
this method. The username is the OAuth application `client_id` and the password
is its `client_secret`. Tokens are revoked via a background job, and it might
take a few minutes for the process to complete.

DELETE /applications/:client_id/tokens

### Response

<%= headers 204 %>

## Revoke an authorization for an application

OAuth application owners can also revoke a single token for an OAuth
application. You must use [Basic Authentication](/v3/auth#basic-authentication)
for this method, where the username is the OAuth application `client_id` and
the password is its `client_secret`.

DELETE /applications/:client_id/tokens/:access_token

### Response
<%= json :error => :invalid_client_credentials %>

<%= headers 204 %>
To solve this error, go back and make sure you have the correct
credentials for your oauth application. Double check the `client_id` and
`client_secret` to make sure they are correct and being passed correctly
to GitHub.

## More Information
### Bad verification code

If the verification code you pass is incorrect, expired, or doesn't
match what you received in the first request for authorization you will
receive this error.

It can be a little tricky to get started with OAuth. Here are a few
links that might be of help:
<%= json :error => :bad_verification_code %>

* [OAuth 2 spec](http://tools.ietf.org/html/rfc6749)
* [Facebook Login API](http://developers.facebook.com/docs/technical-guides/login/)
* [Ruby OAuth2 lib](https://github.com/intridea/oauth2)
* [Simple Ruby/Sinatra example](https://gist.github.com/9fd1a6199da0465ec87c)
* [Python Flask example](https://gist.github.com/ib-lundgren/6507798) using [requests-oauthlib](https://github.com/requests/requests-oauthlib)
* [Simple Python example](https://gist.github.com/e3fbd47fbb7ee3c626bb) using [python-oauth2](https://github.com/dgouldin/python-oauth2)
* [Ruby OmniAuth example](https://github.com/intridea/omniauth)
* [Ruby Sinatra extension](https://github.com/atmos/sinatra_auth_github)
* [Ruby Warden strategy](https://github.com/atmos/warden-github)
To solve this error, start the [OAuth process over from the beginning](#redirect-users-to-request-github-access)
and get a new code.

[app-listing]: https://github.com/settings/applications
[oauth changes blog]: /changes/2013-10-04-oauth-changes-coming/
[basics auth guide]: /guides/basics-of-authentication/
[deployments]: /v3/repos/deployments
Loading
[8]ページ先頭
©2009-2025 Movatter.jp