Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

OS Login

Written by
Updated at November 25, 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, Yandex Data Processing subcluster hosts, 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 Identity Hub 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 Yandex Identity Hub 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 accounts in that organization.

The username (login) assigned to a user account in the OS Login profile by default 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.

Note

For service accounts, OS Login profiles are not created automatically. To connect to a VM or Kubernetes node on behalf of a service account, you need to manually create an OS Login profile.

A single user or service account in a Identity Hub 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.

Each OS Login profile is assigned a numeric UID, which matches the user's UID in the VM operating systems. The OS Login profile UID must be unique within both the organization and the VM OS.

Warning

There must be no collisions between the UIDs of the OS Login profile and the OS system profiles. If you set the UID manually, use values in the range from 1002 to 2^63 - 1 to avoid such collisions.

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.

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 Identity Hub.

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.

Only Yandex account, federated or local users assigned the organization-manager.osLogins.admin role or higher can upload SSH keys to service account OS Login profiles.

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.

For more information about connecting to VMs via OS Login, see Connecting via the Yandex Cloud CLI, Connecting to a Kubernetes node via OS Login, and Connecting to a Yandex Data Processing cluster.

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.

Use cases

See also

Previous
Applications (SSO)
Next
MFA