Refresh token

A refresh token is a type of credential that allows an OAuth application to automatically obtain a new IAM token after the user's IAM token expires. A refresh token is issued for a user and sent to an OAuth application, which then authenticates the user in Yandex Cloud.

An example of an OAuth application supporting refresh tokens is the Yandex Cloud CLI. Refresh tokens can only be issued for federated users in the Yandex Cloud Organization organization.

With the Yandex Cloud CLI and API, you can view the list of refresh tokens issued for a user and revoke such tokens.

Refresh token lifetimeRefresh token lifetime

A refresh token is valid for 31 days. If used to obtain an IAM token, a refresh token is automatically reissued when there are less than seven days left before its expiration.

If your refresh token has expired, you must obtain a new one. A new refresh token will be created automatically when next obtain an IAM token. In this case, the user will have to re-authenticate in the browser.

Refresh tokens are automatically deleted seven days after their expiration.

Enabling the use of refresh tokens in the Yandex Cloud CLIEnabling the use of refresh tokens in the Yandex Cloud CLI

To use refresh tokens in the Yandex Cloud CLI, you must enable this option at the Cloud Organization level. To do this:

To allow federated users to use refresh tokens in the Yandex Cloud CLI, each user must initialize DPoP after you enable this option at the organization level.

Using DPoP to protect refresh tokens in the Yandex Cloud CLIUsing DPoP to protect refresh tokens in the Yandex Cloud CLI

The DPoP mechanism helps to prove that a request for an IAM token made with a refresh token is legitimate. This verification is based on a special DPoP key created on the user device to confirm the authenticity of both the user making the request and the source device.

If the Allow DPoP key storage only on YubiKeys option is disabled, to protect your refresh tokens, you can use DPoP keys saved both on a YubiKey and user's local file system (a less secure option).

To enhance the protection of refresh tokens, enable Allow DPoP key storage only on YubiKeys to only use DPoP keys stored on a specialized YubiKey device, which ensures the keys are not retrievable.

Initializing DPoP protection for refresh tokens in the Yandex Cloud CLIInitializing DPoP protection for refresh tokens in the Yandex Cloud CLI

The DPoP key used to verify the user and device sending a request for an IAM token must be created on the user device. The mechanism for creating, storing, and using such a DPoP key must be implemented within an OAuth application that uses refresh tokens.

To initialize DPoP protection for a federated user's refresh tokens in the Yandex Cloud CLI:

1. Make sure the use of refresh tokens is enabled in Cloud Organization at your organization level.

2. Initialize DPoP protection for refresh tokens on the user device:

   Yandex Cloud CLI

   1. Create a CLI profile for the federated user and authenticate as this user in Yandex Cloud.

   2. Initialize the DPoP protection:

      yc init --dpop
      

      The Yandex Cloud CLI will prompt you to configure the DPoP protection:

      Welcome! This command will take you through the configuration process.
      Do you want to initialize file system auth keys? [y/N]
      

   3. Complete the configuration process. To do this, type y and press ENTER.

      Follow the configurator tips to generate and save a DPoP key in your local file system or a YubiKey.

Once initialization is complete, a refresh token will be created for the user the next time they request a new IAM token. Later on, the Yandex Cloud CLI will automatically update IAM tokens for the federated user, requiring no regular authentication in the browser.

If the DPoP key is stored in the file system, the IAM token is reissued immediately. When using a YubiKey, the IAM token can only be reissued after confirming the action on the YubiKey.