Merge pull request #7193 from hollietealok/doc_remove
Removed docker_io_oauth_api.md: Docker is not currently accepting regist...
This commit is contained in:
Aaron Huslage
commit
32fdcaa419
|
|
@ -121,7 +121,6 @@ pages:
|
|||
- ['reference/api/docker_remote_api_v1.1.md', '**HIDDEN**']
|
||||
- ['reference/api/docker_remote_api_v1.0.md', '**HIDDEN**']
|
||||
- ['reference/api/remote_api_client_libraries.md', 'Reference', 'Docker Remote API Client Libraries']
|
||||
- ['reference/api/docker_io_oauth_api.md', 'Reference', 'Docker Hub OAuth API']
|
||||
- ['reference/api/docker_io_accounts_api.md', 'Reference', 'Docker Hub Accounts API']
|
||||
|
||||
- ['jsearch.md', '**HIDDEN**']
|
||||
|
|
|
|||
|
|
@ -1,254 +0,0 @@
|
|||
page_title: docker.io OAuth API
|
||||
page_description: API Documentation for docker.io's OAuth flow.
|
||||
page_keywords: API, Docker, oauth, REST, documentation
|
||||
|
||||
# docker.io OAuth API
|
||||
|
||||
## 1. Brief introduction
|
||||
|
||||
Some docker.io API requests will require an access token to
|
||||
authenticate. To get an access token for a user, that user must first
|
||||
grant your application access to their docker.io account. In order for
|
||||
them to grant your application access you must first register your
|
||||
application.
|
||||
|
||||
Before continuing, we encourage you to familiarize yourself with [The
|
||||
OAuth 2.0 Authorization Framework](http://tools.ietf.org/html/rfc6749).
|
||||
|
||||
*Also note that all OAuth interactions must take place over https
|
||||
connections*
|
||||
|
||||
## 2. Register Your Application
|
||||
|
||||
You will need to register your application with docker.io before users
|
||||
will be able to grant your application access to their account
|
||||
information. We are currently only allowing applications selectively. To
|
||||
request registration of your application send an email to
|
||||
[support-accounts@docker.com](mailto:support-accounts%40docker.com) with
|
||||
the following information:
|
||||
|
||||
- The name of your application
|
||||
- A description of your application and the service it will provide to
|
||||
docker.io users.
|
||||
- A callback URI that we will use for redirecting authorization
|
||||
requests to your application. These are used in the step of getting
|
||||
an Authorization Code. The domain name of the callback URI will be
|
||||
visible to the user when they are requested to authorize your
|
||||
application.
|
||||
|
||||
When your application is approved you will receive a response from the
|
||||
docker.io team with your `client_id` and
|
||||
`client_secret` which your application will use in
|
||||
the steps of getting an Authorization Code and getting an Access Token.
|
||||
|
||||
# 3. Endpoints
|
||||
|
||||
## 3.1 Get an Authorization Code
|
||||
|
||||
Once You have registered you are ready to start integrating docker.io
|
||||
accounts into your application! The process is usually started by a user
|
||||
following a link in your application to an OAuth Authorization endpoint.
|
||||
|
||||
`GET /api/v1.1/o/authorize/`
|
||||
|
||||
Request that a docker.io user authorize your application. If the
|
||||
user is not already logged in, they will be prompted to login. The
|
||||
user is then presented with a form to authorize your application for
|
||||
the requested access scope. On submission, the user will be
|
||||
redirected to the specified `redirect_uri` with
|
||||
an Authorization Code.
|
||||
|
||||
Query Parameters:
|
||||
|
||||
|
||||
|
||||
- **client_id** – The `client_id` given to
|
||||
your application at registration.
|
||||
- **response_type** – MUST be set to `code`.
|
||||
This specifies that you would like an Authorization Code
|
||||
returned.
|
||||
- **redirect_uri** – The URI to redirect back to after the user
|
||||
has authorized your application. If omitted, the first of your
|
||||
registered `response_uris` is used. If
|
||||
included, it must be one of the URIs which were submitted when
|
||||
registering your application.
|
||||
- **scope** – The extent of access permissions you are requesting.
|
||||
Currently, the scope options are `profile_read`, `profile_write`,
|
||||
`email_read`, and `email_write`. Scopes must be separated by a space. If omitted, the
|
||||
default scopes `profile_read email_read` are
|
||||
used.
|
||||
- **state** – (Recommended) Used by your application to maintain
|
||||
state between the authorization request and callback to protect
|
||||
against CSRF attacks.
|
||||
|
||||
**Example Request**
|
||||
|
||||
Asking the user for authorization.
|
||||
|
||||
GET /api/v1.1/o/authorize/?client_id=TestClientID&response_type=code&redirect_uri=https%3A//my.app/auth_complete/&scope=profile_read%20email_read&state=abc123 HTTP/1.1
|
||||
Host: www.docker.io
|
||||
|
||||
**Authorization Page**
|
||||
|
||||
When the user follows a link, making the above GET request, they
|
||||
will be asked to login to their docker.io account if they are not
|
||||
already and then be presented with the following authorization
|
||||
prompt which asks the user to authorize your application with a
|
||||
description of the requested scopes.
|
||||
|
||||
|
||||
|
||||
Once the user allows or denies your Authorization Request the user
|
||||
will be redirected back to your application. Included in that
|
||||
request will be the following query parameters:
|
||||
|
||||
`code`
|
||||
: The Authorization code generated by the docker.io authorization
|
||||
server. Present it again to request an Access Token. This code
|
||||
expires in 60 seconds.
|
||||
`state`
|
||||
: If the `state` parameter was present in the
|
||||
authorization request this will be the exact value received from
|
||||
that request.
|
||||
`error`
|
||||
: An error message in the event of the user denying the
|
||||
authorization or some other kind of error with the request.
|
||||
|
||||
## 3.2 Get an Access Token
|
||||
|
||||
Once the user has authorized your application, a request will be made to
|
||||
your application's specified `redirect_uri` which
|
||||
includes a `code` parameter that you must then use
|
||||
to get an Access Token.
|
||||
|
||||
`POST /api/v1.1/o/token/`
|
||||
|
||||
Submit your newly granted Authorization Code and your application's
|
||||
credentials to receive an Access Token and Refresh Token. The code
|
||||
is valid for 60 seconds and cannot be used more than once.
|
||||
|
||||
Request Headers:
|
||||
|
||||
|
||||
|
||||
- **Authorization** – HTTP basic authentication using your
|
||||
application's `client_id` and
|
||||
`client_secret`
|
||||
|
||||
Form Parameters:
|
||||
|
||||
|
||||
|
||||
- **grant_type** – MUST be set to `authorization_code`
|
||||
- **code** – The authorization code received from the user's
|
||||
redirect request.
|
||||
- **redirect_uri** – The same `redirect_uri`
|
||||
used in the authentication request.
|
||||
|
||||
**Example Request**
|
||||
|
||||
Using an authorization code to get an access token.
|
||||
|
||||
POST /api/v1.1/o/token/ HTTP/1.1
|
||||
Host: www.docker.io
|
||||
Authorization: Basic VGVzdENsaWVudElEOlRlc3RDbGllbnRTZWNyZXQ=
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"grant_type": "code",
|
||||
"code": "YXV0aG9yaXphdGlvbl9jb2Rl",
|
||||
"redirect_uri": "https://my.app/auth_complete/"
|
||||
}
|
||||
|
||||
**Example Response**
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json;charset=UTF-8
|
||||
|
||||
{
|
||||
"username": "janedoe",
|
||||
"user_id": 42,
|
||||
"access_token": "t6k2BqgRw59hphQBsbBoPPWLqu6FmS",
|
||||
"expires_in": 15552000,
|
||||
"token_type": "Bearer",
|
||||
"scope": "profile_read email_read",
|
||||
"refresh_token": "hJDhLH3cfsUrQlT4MxA6s8xAFEqdgc"
|
||||
}
|
||||
|
||||
In the case of an error, there will be a non-200 HTTP Status and and
|
||||
data detailing the error.
|
||||
|
||||
## 3.3 Refresh a Token
|
||||
|
||||
Once the Access Token expires you can use your `refresh_token`
|
||||
to have docker.io issue your application a new Access Token,
|
||||
if the user has not revoked access from your application.
|
||||
|
||||
`POST /api/v1.1/o/token/`
|
||||
|
||||
Submit your `refresh_token` and application's
|
||||
credentials to receive a new Access Token and Refresh Token. The
|
||||
`refresh_token` can be used only once.
|
||||
|
||||
Request Headers:
|
||||
|
||||
|
||||
|
||||
- **Authorization** – HTTP basic authentication using your
|
||||
application's `client_id` and
|
||||
`client_secret`
|
||||
|
||||
Form Parameters:
|
||||
|
||||
|
||||
|
||||
- **grant_type** – MUST be set to `refresh_token`
|
||||
- **refresh_token** – The `refresh_token`
|
||||
which was issued to your application.
|
||||
- **scope** – (optional) The scope of the access token to be
|
||||
returned. Must not include any scope not originally granted by
|
||||
the user and if omitted is treated as equal to the scope
|
||||
originally granted.
|
||||
|
||||
**Example Request**
|
||||
|
||||
Refreshing an access token.
|
||||
|
||||
POST /api/v1.1/o/token/ HTTP/1.1
|
||||
Host: www.docker.io
|
||||
Authorization: Basic VGVzdENsaWVudElEOlRlc3RDbGllbnRTZWNyZXQ=
|
||||
Accept: application/json
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"grant_type": "refresh_token",
|
||||
"refresh_token": "hJDhLH3cfsUrQlT4MxA6s8xAFEqdgc",
|
||||
}
|
||||
|
||||
**Example Response**
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json;charset=UTF-8
|
||||
|
||||
{
|
||||
"username": "janedoe",
|
||||
"user_id": 42,
|
||||
"access_token": "t6k2BqgRw59hphQBsbBoPPWLqu6FmS",
|
||||
"expires_in": 15552000,
|
||||
"token_type": "Bearer",
|
||||
"scope": "profile_read email_read",
|
||||
"refresh_token": "hJDhLH3cfsUrQlT4MxA6s8xAFEqdgc"
|
||||
}
|
||||
|
||||
In the case of an error, there will be a non-200 HTTP Status and and
|
||||
data detailing the error.
|
||||
|
||||
# 4. Use an Access Token with the API
|
||||
|
||||
Many of the docker.io API requests will require a Authorization request
|
||||
header field. Simply ensure you add this header with "Bearer <`access_token`>":
|
||||
|
||||
GET /api/v1.1/resource HTTP/1.1
|
||||
Host: docker.io
|
||||
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
|
||||
Loading…
Reference in New Issue