Get started
Yandex Container Registry

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.

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

Authentication methods

You can authenticate:

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

Note

The validity period of an OAuth token is one year. Then you must get new OAuth token and repeat the authentication process.

  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

Note

The IAM token has a short lifetime — no more than 12 hours. That's why this is a good method for applications that automatically request 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

Note

Authorized keys do not expire, but you can always get new authorized keys and authenticate again if something goes wrong.

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

Note

The IAM token has a short lifetime — no more than 12 hours. That's why this is a good method for applications that automatically request 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.

In this article: