Authentication in Container Registry

Written by

Yandex Cloud

Improved by

Alexey K.

Updated at July 23, 2026

View in Markdown

Authentication methods
Authenticating as a user
Authenticating with 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 select the one that works best for you.

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

Authentication methods

You can get authenticated:

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

Authenticating as a user

Using an OAuth token

Using an IAM token

OAuth token authentication is deprecated

This authentication method will no longer be supported. Consider using IAM tokens or API keys.

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: Endpoint that Docker will access when working with the image registry. If it not specified, the request will be sent to the default service, Docker Hub.

Note

The IAM token has a short lifetime of up to 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: Endpoint that Docker will access when working with the image registry. If it not specified, the request will be sent to the default service, Docker Hub.

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

If this occurs, disable the Docker credential helper. For more information, see Troubleshooting in Container Registry.

Authenticating with a Docker credential helper

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

The Yandex Cloud CLI provides docker-credential-yc as a Docker credential helper for Yandex Cloud. It stores user credentials and enables 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 used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

Configure Docker to use docker-credential-yc:
```
yc container registry configure-docker
```
Result:
```
Credential helper is configured in '/home/<user>/.docker/config.json'
```
The current user’s profile stores the settings.

Warning

The credential helper only works if you use Docker without sudo. To learn how to configure Docker to run on behalf of the current user without sudo, see this Docker guide.
Make sure Docker is configured.

The ${HOME}/.docker/config.json configuration file should now contain this line:
```
"cr.yandex": "yc"
```
You can now use Docker, e.g., to push Docker images.

Additional credential helper features

Using the 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 profile management, see these Yandex Cloud CLI step-by-step guides.

Disabling a credential helper

To stop using a credential helper for authentication, remove the cr.yandex domain line from credHelpers in the ${HOME}/.docker/config.json configuration file.

Authentication in Container Registry

Authentication methodsAuthentication methods

Authenticating as a userAuthenticating as a user

Authenticating with a Docker credential helperAuthenticating with a Docker credential helper

Configuring a credential helperConfiguring a credential helper

Additional credential helper featuresAdditional credential helper features

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

Disabling a credential helperDisabling a credential helper

Was the article helpful?