mirror of
https://github.com/moby/moby.git
synced 2022-11-09 12:21:53 -05:00
b6a5082bd1
Added emphasis of https for OAuth interactions. Updated example URIs to use HTTPS Included redirect hostname on authorization page. Docker-DCO-1.1-Signed-off-by: Josh hawn <josh.hawn@docker.com> (github: jlhawn)
253 lines
8.8 KiB
ReStructuredText
253 lines
8.8 KiB
ReStructuredText
:title: docker.io OAuth API
|
|
:description: API Documentation for docker.io's OAuth flow.
|
|
:keywords: API, Docker, oauth, REST, documentation
|
|
|
|
|
|
===================
|
|
docker.io OAuth API
|
|
===================
|
|
|
|
.. contents:: Table of Contents
|
|
|
|
|
|
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 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.
|
|
|
|
.. http: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 client_id: The ``client_id`` given to your application at
|
|
registration.
|
|
:query response_type: MUST be set to ``code``. This specifies that you
|
|
would like an Authorization Code returned.
|
|
:query 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.
|
|
:query 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.
|
|
:query 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.
|
|
|
|
.. sourcecode:: http
|
|
|
|
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.
|
|
|
|
.. image:: _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.
|
|
|
|
.. http: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.
|
|
|
|
:reqheader Authorization: HTTP basic authentication using your
|
|
application's ``client_id`` and ``client_secret``
|
|
|
|
:form grant_type: MUST be set to ``authorization_code``
|
|
:form code: The authorization code received from the user's redirect
|
|
request.
|
|
:form redirect_uri: The same ``redirect_uri`` used in the authentication
|
|
request.
|
|
|
|
**Example Request**
|
|
|
|
Using an authorization code to get an access token.
|
|
|
|
.. sourcecode:: http
|
|
|
|
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**
|
|
|
|
.. sourcecode:: http
|
|
|
|
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.
|
|
|
|
.. http: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.
|
|
|
|
:reqheader Authorization: HTTP basic authentication using your
|
|
application's ``client_id`` and ``client_secret``
|
|
|
|
:form grant_type: MUST be set to ``refresh_token``
|
|
:form refresh_token: The ``refresh_token`` which was issued to your
|
|
application.
|
|
:form 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.
|
|
|
|
.. sourcecode:: http
|
|
|
|
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**
|
|
|
|
.. sourcecode:: http
|
|
|
|
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``>":
|
|
|
|
.. sourcecode:: http
|
|
|
|
GET /api/v1.1/resource HTTP/1.1
|
|
Host: docker.io
|
|
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
|