Discuss with expertTry it for free
© 2026 Direct Cursus Technology L.L.C.

Authenticating with the Yandex Cloud CLI on a server with no GUI

Written by
Updated at August 19, 2026
View in Markdown

Warning

To get authenticated in the CLI with a Yandex account, federated account, or local user account, you need a browser and a GUI.

If using the CLI on a server without a GUI, the recommended option is to authenticate with a service account.

If you cannot use a service account, authenticate via an SSH tunnel or X11 forwarding.

This subsection discusses the following methods for authentication on a server with no GUI:

Authentication via X11 forwarding

This example describes X11 forwarding authentication on a Ubuntu server.

  1. If connecting to a VM from macOS or Windows, install and run an X server, e.g., XQuartz for macOS or VcXsrv for Windows. Linux has this feature available by default.

  2. Connect to the server over SSH:

    ssh -i <key_file> <username>@<server_public_IP_address>

  3. Open /etc/ssh/sshd_config:

    sudo nano /etc/ssh/sshd_config

  4. Uncomment these lines:

    X11Forwarding yes
X11DisplayOffset 10
X11UseLocalhost yes

  5. Install the X server packages:

    sudo apt get update
sudo apt-get install xauth xorg

  6. Disconnect from the server and reconnect to your X server using the -X flag:

    ssh -X -i <key_file> <username>@<server_public_IP_address>

  7. Optionally, make sure X11 forwarding works correctly by running this command:

    xeyes

    An Xeyes window will open; close it.

  8. Install the Chromium browser and make sure you can start it:

    sudo apt update && sudo apt install chromium-browser
export XAUTHORITY=$HOME/.Xauthority
chromium

    A browser window will open; close it.

  9. Install the CLI and an X11 integration package:

    curl -sSL https://storage.yandexcloud.net/yandexcloud-yc/install.sh | bash
exec -l $SHELL
sudo apt install xdg-utils

  10. Start the authentication process:

    yc init --username=<email_address>

    For more information, see Authentication in the Yandex Cloud CLI with a Yandex account.

    yc init --federation-id=<federation_ID>

    For more information, see Authenticating with the Yandex Cloud CLI as a federated user.

    yc init --userpool-id=<user_pool_ID>

    For more information, see Authenticating in the Yandex Cloud CLI as a local user.

    A browser window with the authentication page will now open.

  11. Complete the CLI configuration.

Example of authenticating over an SSH tunnel

To authenticate to a Linux VM, follow these steps:

  1. Connect to the VM over SSH.

  2. On your VM, create a file named /usr/local/bin/xdg-open with the following contents:

    #!/bin/sh
echo $* > /dev/tty

  3. Assign permissions to execute the file:

    sudo chmod +x /usr/local/bin/xdg-open

  4. Install the CLI:

    curl -sSL https://storage.yandexcloud.net/yandexcloud-yc/install.sh | bash
exec -l $SHELL

  5. Start the authentication process:

    yc init --username=<email_address>

    For more information, see Authentication in the Yandex Cloud CLI with a Yandex account.

    yc init --federation-id=<federation_ID>

    For more information, see Authenticating with the Yandex Cloud CLI as a federated user.

    yc init --userpool-id=<user_pool_ID>

    For more information, see Authenticating in the Yandex Cloud CLI as a local user.

  6. Select the profile you want to set up authentication for or create a new one:

    Welcome! This command will take you through the configuration process.
Pick desired action:
[1] Re-initialize this profile 'default' with new settings
[2] Create a new profile

  7. The CLI prompts you to continue authentication in the browser. Press Enter to continue:

    You are going to be authenticated via username '<email_address>'.
Authentication web site will be opened.
After your successful authentication, you will be redirected to 'https://console.yandex.cloud'.

Press 'enter' to continue...

    You are going to be authenticated via federation-id 'aje1f0hsgds3a********'.
Your federation authentication web site will be opened.
After your successful authentication, you will be redirected to 'https://console.yandex.cloud'.

Press 'enter' to continue...

    You are going to be authenticated via userpool-id 'ek0auknfc0mh********'.
Your userpool authentication web site will be opened.
After your successful authentication, you will be redirected to cloud console.

Press 'enter' to continue...

  8. Once you press Enter, you will get a URL that looks like this:

    https://auth.yandex.cloud/oauth/authorize?client_id=yc.oauth.public-sdk&code_challenge=y22kspX4VrKLmdg9hGr_Bwgte_a3RXtw1En********&code_challenge_method=S256&redirect_uri=http%3A%2F%2F127.0.0.1%3A42121%2Fauth%2Fcallback&response_type=code&scope=openid&state=aExf0z********&yc_federation_hint=federation-id

    Save this URL. You will need it for browser authentication. You will also need the port which you can find in the redirect_uri query parameter following the 127.0.0.1 IP address. In our example, it is 42121.

  9. On your local computer, open a new terminal window and run the command to set up an SSH tunnel, specifying the port obtained in the previous step, username, and VM IP address:

    ssh -N -L <port>:127.0.0.1:<port> <username>@<VM_IP_address>

    After the connection is established, the command returns no result and remains active for as long as the SSH tunnel is operating. Do not close this terminal window until the CLI setup is complete.

  10. Use your local computer's browser to open the authentication URL you got earlier.

  11. Return to the VM SSH session terminal window where the yc init command is active. If authentication is successful, the CLI will go to the next profile configuration step.

  12. Complete the CLI configuration.

  13. In the local terminal window, terminate the SSH tunnel by pressing Ctrl + C.

Useful links

Previous
IAM token from an environment variable
Next
Running commands