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:
commit
32fdcaa419
|
@ -121,7 +121,6 @@ pages:
|
||||||
- ['reference/api/docker_remote_api_v1.1.md', '**HIDDEN**']
|
- ['reference/api/docker_remote_api_v1.1.md', '**HIDDEN**']
|
||||||
- ['reference/api/docker_remote_api_v1.0.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/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']
|
- ['reference/api/docker_io_accounts_api.md', 'Reference', 'Docker Hub Accounts API']
|
||||||
|
|
||||||
- ['jsearch.md', '**HIDDEN**']
|
- ['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.
|
|
||||||
|
|
||||||
![](/reference/api/_static/io_oauth_authorization_page.png)
|
|
||||||
|
|
||||||
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