[Yandex Cloud documentation](../../index.md) > [Yandex Identity Hub](../index.md) > Concepts > OS Login

# OS Login

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](../../compute/concepts/vm.md#project), [Yandex Data Processing subcluster](../../data-proc/concepts/index.md#resources) hosts, and [individual nodes in node groups](../../managed-kubernetes/concepts/index.md#node-group) within [Yandex Managed Service for Kubernetes clusters](../../managed-kubernetes/concepts/index.md#kubernetes-cluster) 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](../../iam/concepts/index.md). 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](membership.md) account or [service account](../../iam/concepts/users/service-accounts.md).

OS Login benefits:

* Instant update of user [access permissions](../../iam/concepts/access-control/roles.md) 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 {#structure}

OS Login includes the following elements: [OS Login agent](#agent), organization-level OS Login [operation mode settings](#modes), as well as [OS Login profiles](#os-login-profiles) and [SSH keys](#ssh-keys) of users and service accounts in the organization.

### OS Login agent {#agent}

The _OS Login agent_ is based on the [guest agent for Google Compute Engine](https://github.com/GoogleCloudPlatform/guest-agent). To monitor the changes introduced by the Yandex Cloud team, see the [project's repository on GitHub](https://github.com/yandex-cloud/yandex-cloud-guest-agent).

The OS Login agent is integrated into [a number of Linux images](https://yandex.cloud/en/marketplace?search=oslogin) available when creating a VM.

### OS Login operating mode settings at the Yandex Identity Hub level {#modes}

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](../../compute/operations/vm-connect/os-login.md#connect-with-yc-cli) or a [standard SSH client](../../compute/operations/vm-connect/os-login.md#connect-with-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](os-login.md#os-login-profiles) of a user or [service account](../../iam/concepts/users/service-accounts.md).

### OS Login profiles for users and service accounts {#os-login-profiles}

_OS Login profile_ defines the parameters to apply when creating a user account within a VM.

[Enabling](../operations/os-login-access.md) 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 info %}

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](../operations/os-login-profile-create.md) an OS Login profile.

{% endnote %}

A single user or service account in a Yandex 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](../operations/os-login-profile-create.md).

Each OS Login profile is assigned a numeric UID, which matches the user's [UID](https://en.wikipedia.org/wiki/User_identifier) in the VM operating systems. The OS Login profile UID must be unique within both the [organization](organization.md) and the VM OS.

{% note 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.

{% endnote %}

You can manage user OS Login profiles via the [Cloud Center interface](https://center.yandex.cloud/organization) as well as the [Yandex Cloud CLI](../../cli/cli-ref/organization-manager/cli-ref/oslogin/index.md) and [API](../api-ref/OsLogin/index.md). 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](../security/index.md#organization-manager-osLogins-viewer) 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](../security/index.md#service-roles).

### SSH keys of users and service accounts {#ssh-keys}

The [organization administrator](../security/index.md#organization-manager-admin) can enable [Mode 2](#modes) 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](#os-login-profiles).

An organization administrator can also allow users to manage their public SSH keys themselves by additionally [enabling](../operations/os-login-access.md) the **Allow members to use their own SSH keys** option in the organization's security settings.

Only [Yandex account](../../iam/concepts/users/accounts.md#passport), [federated](../../iam/concepts/users/accounts.md#saml-federation) or [local](../../iam/concepts/users/accounts.md#local) users assigned the `organization-manager.osLogins.admin` [role](../security/index.md#organization-manager-osLogins-admin) or higher can upload SSH keys to service account [OS Login profiles](os-login.md#os-login-profiles).

### OS Login prerequisites {#pre-conditions}

{% note info %}

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

{% endnote %}

To start [connecting](#os-login-connection) to a VM via OS Login, make sure to do the following:

* [Enable OS Login access](../operations/os-login-access.md) to the VM at the organization level.
* [Deploy the VM](../../compute/operations/vm-connect/os-login-create-vm.md) from an [image](https://yandex.cloud/en/marketplace?search=oslogin) with an integrated [OS Login agent](#agent).
    If the VM is created from an image without an integrated OS Login agent, you can [install the agent](../../compute/operations/vm-connect/enable-os-login.md#enable-os-login) 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 info %}

If OS Login access is [enabled](../operations/os-login-access.md) 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 OS Login access is disabled in the organization, the default value of this field will be `INSTANCE_METADATA`.

{% endnote %}

## Connecting via OS Login {#os-login-connection}

To connect to a VM with OS Login access enabled, you can use either a standard SSH client or the [Yandex Cloud CLI](../../cli/quickstart.md).

### Connecting with a standard SSH client {#connect-with-ssh-client}

Users or, if acting under service accounts, third-party tools, such as [Terraform](https://www.terraform.io/) or [Ansible](https://www.ansible.com/), can use a standard SSH client to [connect](../../compute/operations/vm-connect/os-login.md#connect-with-ssh-client) to a VM with enabled OS Login access using a short-lived SSH certificate or SSH key [saved](../operations/add-ssh.md) 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](../../compute/operations/vm-connect/os-login-export-certificate.md) the certificate and use it when connecting.

{% cut "Example of connecting using a short-lived SSH certificate" %}

```bash
# 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.
1. With the `yc compute ssh certificate export` command, we export the user's short-lived SSH certificate to the `~/Downloads/cert` directory.
1. With the received SSH certificate, we connect to the VM using the previously saved public IP address.

{% endcut %}

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 {#connect-with-yc-cli}

You can connect to a VM with enabled OS Login access using the Yandex Cloud CLI with either an SSH key [saved](../operations/add-ssh.md) 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](../../compute/operations/vm-connect/os-login.md#connect-with-yc-cli), [Connecting to a Kubernetes node via OS Login](../../managed-kubernetes/operations/node-connect-oslogin.md#connect-via-cli), and [Connecting to a Yandex Data Processing cluster](../../data-proc/operations/connect-oslogin.md#os-login-cli).

### Roles required to connect to a VM via OS Login {#necessary-roles}

To connect to a virtual machine or Kubernetes node with OS Login access enabled, assign the following roles to the user or [service account](../../iam/concepts/users/service-accounts.md):

* `compute.osLogin` or `compute.osAdminLogin` [role](../../compute/security/index.md#compute-oslogin).
* `resource-manager.auditor` [role](../../resource-manager/security/index.md#resource-manager-auditor) or higher for the folder containing the VM instance or Kubernetes node.
* `compute.operator` [role](../../compute/security/index.md#compute-operator) for connecting via the Yandex Cloud CLI.

{% note alert %}

A user with [superuser](https://en.wikipedia.org/wiki/Superuser) permissions for a VM can retain access to it even if the [roles are revoked](../security/index.md#revoke). To prevent user access to a VM with old permissions, [create](../../compute/operations/images-with-pre-installed-software/create.md) a new VM from a clean image.

{% endnote %}

## Use cases {#examples}

* [Using a service account with an OS Login profile for VM management via Ansible](../tutorials/sa-oslogin-ansible.md)
* [Access control for user groups with different roles in Yandex Identity Hub](../../tutorials/security/user-group-access-control.md)

#### See also {#see-also}

* [Enabling access via OS Login](../operations/os-login-access.md)
* [Creating an OS Login profile](../operations/os-login-profile-create.md)
* [Using a service account with an OS Login profile for VM management via Ansible](../tutorials/sa-oslogin-ansible.md)
* [Authentication and authorization security checklist](../../security/domains/iam-checklist.md)