Authentication in Container Registry

Before you start using Container Registry, you need to authenticate for the corresponding interface:

• In the Management console, the minimum required folder role is viewer.
• In the Docker CLI, the minimum required role for the registry or repository is container-registry.images.puller.

For more information about roles, see Access management in Container Registry.

You can authenticate as a user or service account. Read about authentication methods and choose the appropriate one.

Authentication methods

You can authenticate:

• As a user:
  • Using an OAuth token (lifetime is one year).
  • Using an IAM token (lifetime is no longer than 12 hours).
• As a service account:
  • Using authorized keys (no expiration).
  • Using an IAM token (lifetime is no longer than 12 hours).
• Using a credentials store via a Docker Credential helper.

The authentication command looks like this:

docker login \
       --username <token type> \
       --password <token> \
       cr.yandex

• Pass the token type in <token type> to the username parameter. Acceptable values: oauth, iam, or json_key.
• Pass the token itself to the password parameter.
• After specifying all the parameters, set cr.yandex as the address for authentication. Otherwise, the request will be sent to the default service, Docker Hub.

Authenticate as a user

Authentication using an OAuth token

1. If you don't have an OAuth token, get one via link.

2. Run the command:

   docker login \
          --username oauth \
          --password <OAuth token> \
            cr.yandex
   

Authentication using an IAM token

1. Get an IAM token.

2. Run the command:

   docker login \
          --username iam \
          --password <IAM token> \
            cr.yandex
   

Authenticate as a service account

Authentication using authorized keys

Using a service account, your programs can access Yandex Cloud resources. Get a file with authorized keys for your service account via the CLI.

1. Get authorized keys for your service account:

   yc iam key create --service-account-name default-sa -o key.json
   id: aje8a87g4e...
   service_account_id: aje3932acd...
   created_at: "2019-05-31T16:56:47Z"
   key_algorithm: RSA_2048
   

2. Run the command:

   cat key.json | docker login \
   --username json_key \
   --password-stdin \
   cr.yandex
   
   Login Succeeded
   

   • The cat key.json command writes the contents of the key file to the output stream.
   • The --password-stdin flag allows the password to be read from the input stream.

Authentication using an IAM token

1. Get an IAM token.

2. Run the command:

   docker login \
          --username iam \
          --password <IAM token> \
          cr.yandex
   

Authenticate using a Docker Credential helper

The Docker Engine can keep user credentials in an external credentials store. This is more secure than storing credentials in the Docker configuration file. To use a credentials store, you need an external Docker Credential helper.

Yandex Cloud uses docker-credential-yc as a Docker Credential helper. It stores user credentials and lets you use private Yandex Cloud registries without running the docker login command. This authentication method supports operations on behalf of a user and service account. To work with docker-credential-yc, you need the Yandex Cloud command-line interface: YC CLI.

You don't need to install the docker-credential-yc separately: just install the YC CLI and configure the Credential helper following the description below.

Configuring a Credential helper

1. If you don't have a YC CLI profile yet, create one.

2. Configure Docker to use docker-credential-yc:

   yc container registry configure-docker
   Credential helper is configured in '/home/<user>/.docker/config.json'
   

   Settings are saved in the current user's profile.

   Warning

   The Credential helper only works when using Docker without sudo. For information about how to configure Docker to run as the current user without using the sudo command, see the official documentation.

3. Make sure that Docker is configured.

   The /home/<user>/.docker/config.json file must contain the following line:

   "cr.yandex": "yc"
   

4. You can now use Docker, for example, to push Docker images. You don't need to run docker login for that.

Additional Credential helper features

Using a Credential helper for a different YC CLI profile

You can use the Credential helper for another profile, without switching from the current one, by running the following command:

yc container registry configure-docker --profile <profile name>

For more information about YC CLI profile management, see the step-by-step instructions.

Disabling a Credential helper

To avoid using Credential helpers for authentication, remove the cr.yandex domain string from the credHelpers block in the /home/<user>/.docker/config.json file.