Contact UsGet started

OS Login

Written by
Updated at May 12, 2025

OS Login facilitates SSH connections to virtual machines in Yandex Cloud. Here and below, virtual machines (or VMs) will refer both to actual Yandex Compute Cloud VMs and individual nodes in node groups within Yandex Managed Service for Kubernetes clusters used to run user containers.

With OS Login, you can manage SSH access to VMs relying solely on the Yandex Identity and Access Management mechanisms. There is no need to upload SSH keys to each new VM when it is created. OS Login links the VM user account to a Yandex Cloud Organization account, i.e., an organization user account or service account.

OS Login benefits:

  • Instant update of user access permissions within a VM when revoking or assigning roles. If you revoke the roles, the user will lose access to all VMs with OS Login access enabled.
  • Multiple available options to access VMs: you can use both short-lived SSH certificates and SSH keys including those added to the organization user profile.

OS Login structure

OS Login includes the following elements: OS Login agent, organization-level OS Login operation mode settings, as well as OS Login profiles and SSH keys of users and service accounts in the organization.

OS Login agent

The OS Login agent is based on the guest agent for Google Compute Engine. To monitor the changes introduced by the Yandex Cloud team, see the project's repository on GitHub.

The OS Login agent is integrated into a number of Linux images available when creating a VM.

OS Login operating mode settings at the Cloud Organization level

OS Login supports the following operation modes used both individually and in combination:

  • Mode 1: Access via OS Login using SSH certificates (recommended).
    This mode allows you to connect to a VM with an SSH certificate through the Yandex Cloud CLI or a standard SSH client.

  • Mode 2: Access via OS Login using SSH keys.
    Allows you to connect to a VM through the Yandex Cloud CLI or a standard SSH client using an SSH key stored in the OS Login profile of a user or service account.

OS Login profiles for users and service accounts

OS Login profile defines the parameters to apply when creating a user account within a VM.

Enabling OS Login access for an organization automatically creates default OS Login profiles for all user and service accounts in that organization.

The username (login) an account gets in the OS Login profile by default depends on the account type:

  • A user account's login is derived from the user's name in the organization. Any characters except Latin letters, numbers, hyphens, and underscores, as well as a hyphen prepending the name are ignored. Uppercase Latin letters are converted to lowercase.
  • For a service account, the login will be its name prefixed by yc-sa-, e.g., yc-sa-my-robot will be the default login for my-robot.

A single user or service account in a Cloud Organization can have multiple OS Login profiles: different profiles allow you to connect to VMs as different local users of those VMs. To learn more about creating additional OS Login profiles, see Creating an OS Login profile.

You can manage user OS Login profiles via the Cloud Center interface as well as the Yandex Cloud CLI and API. OS Login profiles of service accounts can be managed only via the Yandex Cloud CLI or API.

Note

The minimum required role allowing you to view the list of OS Login user profiles is the organization-manager.osLogins.viewer role assigned for your organization. For information about other roles allowing you to view the list of OS Login profiles, see Access management in Yandex Cloud Organization.

SSH keys of users and service accounts

The organization administrator can enable Mode 2 to allow the use of public SSH keys for users and service accounts to connect to VMs via OS Login. With this mode on, the administrator will have to load the public SSH keys of users and service accounts into their OS Login profiles.

An organization administrator can also allow users to manage their public SSH keys themselves by additionally enabling the Allow members to use their own SSH keys option in the organization's security settings.

OS Login prerequisites

Note

OS Login works only with Linux-based VMs. VMs with other OS types, including Windows, are not supported.

To start connecting to a VM via OS Login, make sure to do the following:

  • Enable OS Login access to the VM at the organization level.
  • Deploy the VM from an image with an integrated OS Login agent.
    If the VM is created from an image without an integrated OS Login agent, you can install the agent yourself.
  • When creating a VM, select Access by OS Login under Access in the management console. If this option is disabled, the selected image does not support OS Login access.

Note

If OS Login access is enabled at the organization level, all new VMs created in this organization will get the OS_LOGIN value in the serial_port_settings.ssh_authorization field by default. If the OS Login access is disabled, the default value of this field will be INSTANCE_METADATA.

Connecting via OS Login

To connect to a VM with OS Login access enabled, you can use either a standard SSH client or the Yandex Cloud CLI.

Connecting with a standard SSH client

Users or, if acting under service accounts, third-party tools, such as Terraform or Ansible, can use a standard SSH client to connect to a VM with enabled OS Login access using a short-lived SSH certificate or SSH key saved in the OS Login profile of that user or service account.

To connect to a VM via a standard SSH client with an SSH certificate, you need to export the certificate and use it when connecting.

Example of connecting using a short-lived SSH certificate
# 1. Getting the `my-oslogin-vm` VM public IP address and organization ID
PUB_IP=$(yc compute instance get my-oslogin-vm \
  --format=json | jq -r '.network_interfaces[0].primary_v4_address.one_to_one_nat.address')
ORG_ID=$(yc organization-manager organization list --format=json | jq -r '.[0].id')

# 2. Getting a short-lived SSH certificate
yc compute ssh certificate export --organization-id $ORG_ID --directory ~/Downloads/cert

# 3. Connecting to a VM using its public IP address
ssh -i ~/Downloads/cert/yc-organization-id-bpfdp4pdeg8d********-username username@$PUB_IP

In our example:

  1. With the yc compute instance get and yc organization-manager organization list commands, we get the my-oslogin-vm public IP address and the current organization ID and save them in variables.
  2. With the yc compute ssh certificate export command, we export the user's short-lived SSH certificate to the ~/Downloads/cert directory.
  3. With the received SSH certificate, we connect to the VM using the previously saved public IP address.

The certificate is valid for one hour. After this time has elapsed, you will need to export a new certificate to connect to the VM.

Connecting via the Yandex Cloud CLI

You can connect to a VM with enabled OS Login access using the Yandex Cloud CLI with either an SSH key saved in the OS Login profile of a user or service account or an SSH certificate of that user or service account.

To learn more about connecting to VMs via OS Login, see Connecting via the Yandex Cloud CLI and Connecting to a Kubernetes node via OS Login.

Roles required to connect to a VM via OS Login

For connection to a virtual machine or Kubernetes node with OS Login access enabled, assign the compute.osLogin or compute.osAdminLogin role to the user or service account. When connecting using the Yandex Cloud CLI, you additionally need the compute.operator role.

Alert

A user with superuser permissions for a VM can retain access to it even if the roles are revoked. To prevent user access to a VM with old permissions, create a new VM from a clean image.

See also

Previous
Identity federations
Next
Quotas and limits