From 9fbae5924471b63e4f33fbd87f797183ab68be92 Mon Sep 17 00:00:00 2001 From: hollietealok Date: Wed, 23 Jul 2014 11:55:56 -0700 Subject: [PATCH 1/2] Removed docker_io_oauth_api.md: Docker is not currently accepting registrations for third party auth while it's determined how this will be done, if at all, in the future. Docker-DCO-1.1-Signed-off-by: hollietealok (github: hollietealok) --- .../reference/api/docker_io_oauth_api.md | 254 ------------------ 1 file changed, 254 deletions(-) delete mode 100644 docs/sources/reference/api/docker_io_oauth_api.md diff --git a/docs/sources/reference/api/docker_io_oauth_api.md b/docs/sources/reference/api/docker_io_oauth_api.md deleted file mode 100644 index c5d07720b8..0000000000 --- a/docs/sources/reference/api/docker_io_oauth_api.md +++ /dev/null @@ -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 From 2b9d8248d6136645d3801693370e23d752f748f2 Mon Sep 17 00:00:00 2001 From: hollietealok Date: Tue, 29 Jul 2014 13:56:19 -0700 Subject: [PATCH 2/2] Removed OAuth doc from mkdocs.yml Docker-DCO-1.1-Signed-off-by: hollietealok (github: hollietealok) --- docs/mkdocs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b75e198906..bb69b16cf3 100755 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -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**']