Project: Distribution (Provisioning / Container Registry)
File: oauth.md

title: "Oauth2 Token Authentication" description: "Specifies the Distribution Registry v2 authentication" keywords: registry, on-prem, images, tags, repository, distribution, oauth2, advanced This document describes support for the OAuth2 protocol within the authorization server. should be used as a reference for the protocol and HTTP endpoints described here. Note: Not all token servers implement oauth2. If the request to the endpoint returns `404` using the HTTP `POST` method, refer to for using the HTTP `GET` method supported by all token servers. The format of the refresh token is completely opaque to the client and should be determined by the authorization server. The authorization should ensure the token is sufficiently long and is responsible for storing any information about long-lived tokens which may be needed for revoking. Any information stored inside the token will not be extracted and presented by clients. POST /token Content-Type: application/x-www-form-urlencoded <dl> <dt> <code>grant_type</code> </dt> <dd> (REQUIRED) Type of grant used to get token. When getting a refresh token using credentials this type should be set to "password" and have the accompanying username and password parameters. Type "authorization_code" is reserved for future use for authenticating to an authorization server without having to send credentials directly from the client. When requesting an access token with a refresh token this should be set to "refresh_token". </dd> <dt> <code>service</code> </dt> <dd> (REQUIRED) The name of the service which hosts the resource to get access for. Refresh tokens will only be good for getting tokens for this service. </dd> <dt> <code>client_id</code> </dt> <dd> (REQUIRED) String identifying the client. This client_id does not need to be registered with the authorization server but should be set to a meaningful value in order to allow auditing keys created by unregistered clients. Accepted syntax is defined in <a href="https://tools.ietf.org/html/rfc6749#appendix-A.1" rel="noopener noreferrer nofollow" target="_blank">RFC6749 Appendix A.1</a>. </dd> <dt> <code>access_type</code> </dt> <dd> (OPTIONAL) Access which is being requested. If "offline" is provided then a refresh token will be returned. The default is "online" only returning short lived access token. If the grant type is "refresh_token" this will only return the same refresh token and not a new one. </dd> <dt> <code>scope</code> </dt> <dd> (OPTIONAL) The resource in question, formatted as one of the space-delimited entries from the <code>scope</code> parameters from the <code>WWW-Authenticate</code> header shown

This query parameter should only be specified once but may contain multiple scopes using the scope list format defined in the scope grammar. If multiple <code>scope</code> is provided from <code>WWW-Authenticate</code> header the scopes should first be converted to a scope list before requesting the token. The above example would be specified as: <code>scope=repository:samalba/my-app:push</code>. When requesting a refresh token the scopes may be empty since the refresh token will not be limited by this scope, only the provided short lived access token will have the scope limitation. </dd> <dt> <code>refresh_token</code> </dt> <dd> (OPTIONAL) The refresh token to use for authentication when grant type "refresh_token" is used. </dd> <dt> <code>username</code> </dt> <dd> (OPTIONAL) The username to use for authentication when grant type "password" is used. </dd> <dt> <code>password</code> </dt> <dd> (OPTIONAL) The password to use for authentication when grant type "password" is used. </dd> </dl> <dl> <dt> <code>access_token</code> </dt> <dd> (REQUIRED) An opaque <code>Bearer</code> token that clients should supply to subsequent requests in the <code>Authorization</code> header. This token should not be attempted to be parsed or understood by the client but treated as opaque string. </dd> <dt> <code>scope</code> </dt> <dd> (REQUIRED) The scope granted inside the access token. This may be the same scope as requested or a subset. This requirement is stronger than specified in <a href="https://tools.ietf.org/html/rfc6749#section-4.2.2" rel="noopener noreferrer nofollow" target="_blank">RFC6749 Section 4.2.2</a> by strictly requiring the scope in the return value. </dd> <dt> <code>expires_in</code> </dt> <dd> (REQUIRED) The duration in seconds since the token was issued that it will remain valid. When omitted, this defaults to 60 seconds. For compatibility with older clients, a token should never be returned with less than 60 seconds to live. </dd> <dt> <code>issued_at</code> </dt> <dd> (Optional) The <a href="https://www.ietf.org/rfc/rfc3339.txt" rel="noopener noreferrer nofollow" target="_blank">RFC3339</a>-serialized UTC standard time at which a given token was issued. If <code>issued_at</code> is omitted, the expiration is from when the token exchange completed. </dd> <dt> <code>refresh_token</code> </dt> <dd> (Optional) Token which can be used to get additional access tokens for the same subject with different scopes. This token should be kept secure by the client and only sent to the authorization server which issues bearer tokens. This field will only be set when `access_type=offline` is provided in the request. </dd> </dl> ```none POST /token HTTP/1.1 Host: auth.docker.io Content-Type: application/x-www-form-urlencoded granttype=password&username=johndoe&password=A3ddj3w&service=hub.docker.io&clientid=dockerengine&access_type=offline HTTP/1.1 200 OK Content-Type: application/json {"refreshtoken":"kas9Da81Dfa8","accesstoken":"eyJhbGciOiJFUzI1NiIsInR5","expires_in":900,"scope":""} ``` ```none POST /token HTTP/1.1 Host: auth.docker.io Content-Type: application/x-www-form-urlencoded granttype=refreshtoken&refreshtoken=kas9Da81Dfa8&service=registry-1.docker.io&clientid=dockerengine&scope=repository:samalba/my-app:pull,push HTTP/1.1 200 OK Content-Type: application/json {"refreshtoken":"kas9Da81Dfa8","accesstoken":"eyJhbGciOiJFUzI1NiIsInR5":"expires_in":900,"scope":"repository:samalba/my-app:pull,repository:samalba/my-app:push"} ```