Home • Explore • Blog • CI
☰



docker
1st chunk of `content/reference/api/registry/auth.md`
cd325bd2d77182483c99af263e63d9e220e41b924571c491000000010000085d
---
title: Registry authentication
description: "Specifies the Docker Registry v2 authentication"
keywords: registry, images, tags, repository, distribution, Bearer authentication, advanced
---

This document outlines the registry authentication scheme:




1. Attempt to begin a push/pull operation with the registry.
2. If the registry requires authorization it will return a `401 Unauthorized`
   HTTP response with information on how to authenticate.
3. The registry client makes a request to the authorization service for a
   Bearer token.
4. The authorization service returns an opaque Bearer token representing the
   client's authorized access.
5. The client retries the original request with the Bearer token embedded in
   the request's Authorization header.
6. The Registry authorizes the client by validating the Bearer token and the
   claim set embedded within it and begins the push/pull session as usual.

## Requirements

- Registry clients which can understand and respond to token auth challenges
  returned by the resource server.
- An authorization server capable of managing access controls to their
  resources hosted by any given service (such as repositories in a Docker
  Registry).
- A Docker Registry capable of trusting the authorization server to sign tokens
  which clients can use for authorization and the ability to verify these
  tokens for single use or for use during a sufficiently short period of time.

## Authorization server endpoint descriptions

The described server is meant to serve as a standalone access control manager
for resources hosted by other services which want to authenticate and manage
authorizations using a separate access control manager.

A service like this is used by the official Docker Registry to authenticate
clients and verify their authorization to Docker image repositories.

As of Docker 1.6, the registry client within the Docker Engine has been updated
to handle such an authorization workflow.

## How to authenticate

Registry V1 clients first contact the index to initiate a push or pull. Under
Title: Registry Authentication Scheme
Summary
This document outlines the Docker Registry v2 authentication scheme. The process involves the Docker Daemon communicating with both the Registry and an Authorization Service to obtain a Bearer token for authentication. It details the requirements for registry clients, authorization servers, and Docker Registries. It also describes the authorization server endpoint and explains how to authenticate.