Authentication in Container Registry

Written by

Improved by

Updated at May 5, 2025

Authentication methods
Authenticating as a user
Authenticate using a Docker credential helper
- Configuring a credential helper
- Additional credential helper features

Before you start using Container Registry, you need to configure Docker and get authenticated to use the appropriate interface:

In the management console, the minimum required role for a folder is viewer.
In the Docker CLI or Yandex Managed Service for Kubernetes, the minimum required role for a registry or repository is container-registry.images.puller.

Assign the required role to the Yandex Cloud user. Read about authentication methods and choose the appropriate one.

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

Authentication methods

You can authenticate:

As a user:
- Using an OAuth token (with a 12-month lifetime).
- Using an IAM token (with a 12 hours lifetime or less).
Using a Docker credential helper.

Authenticating as a user

Using an OAuth token

Using an IAM token

Note

An OAuth token lives 12 months. After that, you need to get a new one and get authenticated again.

If you do not have Docker yet, install it.
If you do not have an OAuth token yet, get one by following this link.
Run this command:
```
echo <OAuth_token> | docker login \
  --username oauth \
  --password-stdin \
 cr.yandex
```
Where:
- <OAuth_token>: Body of the previously obtained OAuth token.
- --username: Token type. oauth means that an OAuth token is used for authentication.
- cr.yandex: The endpoint that Docker will access when working with the image registry. If it not specified, the request will be sent to Docker Hub as the default service.

Note

The IAM token has a short lifetime: no more than 12 hours. This makes it a good method for applications that automatically request an IAM token.

If you do not have Docker yet, install it.
Get an IAM token.
Run this command:
```
echo <IAM_token> | docker login \
  --username iam \
  --password-stdin \
  cr.yandex
```
Where:
- <IAM_token>: Body of the previously obtained IAM token.
- --username: Token type. iam means that an IAM token is used for authentication.
- cr.yandex: The endpoint that Docker will access when working with the image registry. If it not specified, the request will be sent to Docker Hub as the default service.

When running the command, you may get this error message: docker login is not supported with yc credential helper.

In such a case, disable Docker credential helper. For more information, see Troubleshooting in Container Registry.

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 credential store, you need external Docker credential helper software.

Yandex Cloud CLI uses docker-credential-yc as a Docker credential helper for Yandex Cloud. It stores user credentials and allows you to use private Yandex Cloud registries without running the docker login command.

Configuring a credential helper

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

Configure Docker to use docker-credential-yc:
```
yc container registry configure-docker
```
Result:
```
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 if you use Docker without sudo. To learn how to configure Docker to run under the current user without sudo, see the official documentation.
Make sure that Docker is configured.

The following line must appear in the ${HOME}/.docker/config.json configuration file:
```
"cr.yandex": "yc"
```
You can now use Docker, for example, to push Docker images.

Additional credential helper features

Using a credential helper for a different Yandex Cloud 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 Yandex Cloud CLI profile management, see the step-by-step instructions.

Disabling a credential helper

To avoid using a credential helper for authentication, edit the ${HOME}/.docker/config.json configuration file to delete the cr.yandex domain line from the credHelpers section.

Authentication in Container Registry

Authentication methodsAuthentication methods

Authenticating as a userAuthenticating as a user

Authenticate using a Docker credential helperAuthenticate using a Docker credential helper

Configuring a credential helperConfiguring a credential helper

Additional credential helper featuresAdditional credential helper features

Using a credential helper for a different Yandex Cloud CLI profileUsing a credential helper for a different Yandex Cloud CLI profile

Disabling a credential helperDisabling a credential helper

Was the article helpful?