mirror of
https://github.com/moby/moby.git
synced 2025-12-07 19:42:23 +03:00
Added documentation for docker.io OAuth & Accounts
OAuth docs: documented the OAuth authorization flow and how to register your application Account docs: documented getting/updating user profile data documented getting/updating user email data Docker-DCO-1.1-Signed-off-by: Josh hawn <josh.hawn@docker.com> (github: jlhawn)
This commit is contained in:
Josh Hawn
233
docs/sources/reference/api/docker_io_oauth_api.rst
Normal file
233
docs/sources/reference/api/docker_io_oauth_api.rst
Normal file
@@ -0,0 +1,233 @@
|
||||
: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>`_.
|
||||
|
||||
|
||||
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 list of one or more redirect URIs that we will use for redirecting
|
||||
authorization requests to your application. These are used in the step
|
||||
of getting an Authorization Code.
|
||||
|
||||
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=http%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.jpg
|
||||
|
||||
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": "http://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 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
|
||||
Reference in New Issue
Block a user