Manage OS Login in an organization

Linux

This document describes how you can use OS Login to manage access to VM instances across your organization.

This topic covers the following tasks:

Enable OS Login for an organization using an organization policy: Use an organization policy to ensure that all new VM instances in your organization have OS Login enabled.

Grant instance access to users outside of your organization: Allow user accounts outside of your organization to use SSH to connect to your instances.

Manage the OS Login API: Allow or deny users access to use the OS Login API. Also enable or disable features of the OS Login API.

Audit OS Login events: Track OS Login-related events and activities such as adding, deleting, or updating an SSH key, or deleting POSIX information.

Modify user accounts using the Directory API: Update user properties, such as username and POSIX account information, by using the Directory API.

Use Linux groups with OS Login (Deprecated): Manage user permissions within VMs by using Linux groups with OS Login.

Use OS Login with workforce identity federation (Preview): Connect to VMs that have OS Login enabled when your organization uses an external identity provider (IdP).

Before you begin

OS Login organization policy

You can set up an OS Login constraint in your organization to ensure that all new projects, and the VM instances created in these new projects, have OS Login enabled.

Limitations

Workarounds for Cloud Data Fusion and Managed Airflow

To use OS Login in organizations that use Cloud Data Fusion and Managed Airflow, you can enable OS Login constraint at the organization level and then selectively disable the constraint on projects or folders for the affected projects.

Enable the organization policy

Permissions required for this task

To perform this task, you must have the following permissions:

resourcemanager.organizationAdmin role. For more information see, Access control for organizations using IAM.
To learn more about managing policies at the organization level, see Add an organization policy administrator.

To enable the OS Login policy, you can set the OS Login constraint on specific projects and folders by using the Google Cloud CLI. You can also set the OS Login constraint on the entire organization by using either the Google Cloud console or the Google Cloud CLI.

Console

To set the OS Login organization policy from the console, complete the following steps:

In the Google Cloud console, go to the Organization policies page.
Go to the Organization policies page
In the policies list, click Require OS Login to view the OS Login constraints.
Click Edit to edit your existing OS Login constraints.
On the Edit page, select Customize.
To enable enforcement of this constraint, select On.
Click Save to apply the constraint settings.

gcloud

To set the OS Login organization policy, use the gcloud beta resource-manager org-policies enable-enforce command.

Find your organization ID.
```
gcloud organizations list
```

Set the constraint in your organization. Replace organization-id with your organization ID.

gcloud beta resource-manager org-policies enable-enforce compute.requireOsLogin \
    --organization=organization-id

You can also apply the OS Login organization policy to a folder or a project with the --folder or the --project flags, and the folder ID and project ID, respectively.

For folders, run the following command:

gcloud beta resource-manager org-policies enable-enforce compute.requireOsLogin \
    --folder=folder-id

For projects, run the following command:

gcloud beta resource-manager org-policies enable-enforce compute.requireOsLogin \
    --project=project-id

Replace the following:

folder-id: your folder ID.
project-id: your project ID.

Grant instance access to users outside of your organization

By default, users outside of your organization can't set SSH keys for instances in your organization or be granted access to instances in your organization. In some situations, you might need to grant instance access to users who are part of a different organization or who have a consumer Google gmail.com account.

The roles/compute.osLoginExternalUser IAM role lets external Google Accounts interact with the other OS Login roles by allowing them to configure POSIX account information.

To grant roles/compute.osLoginExternalUser and other necessary OS Login instance access roles to users outside of your organization, complete the following steps:

In the Google Cloud console, go to the IAM & Admin page.
Go to IAM & Admin
Click the Select a project drop-down menu. In the Select a resource dialog that appears, select your organization by doing the following:
1. Click the organization drop-down menu to view all of your organizations.
2. Select your organization from the drop-down.
Click Grant access to add a new role to a user.
In the New principals field, add the email address for the user for whom you want to configure instance access.
From the Role drop-down menu, select the Compute OS Login External User role.
Click Save.
If you have not already done so, grant the other OS Login instance access roles to the user at the project or organization level.

The user can now connect to instances in your project that have OS Login enabled.

Manage the OS Login API

At an organization level, you can restrict access to the OS Login API by setting Google Workspace admin controls. To configure Google Workspace admin controls or view configuration options, see Control who uses Google Cloud in your organization. As a Google Workspace admin, you can also turn on or off certain features of the OS Login API. This includes the following options:

Choose whether to include the domain suffix in usernames generated by OS Login API. For example, in the domain example.com, the user user@example.com will have the username user if the setting to include domain suffix is not checked.
Decide if members of your organization can manage SSH keys using the OS Login API.
Restrict or permit VM access to users outside of your organization.

For more information about turning on or off OS Login API settings, see Choose settings for Google Cloud Platform.

Audit OS Login events

As a Google Workspace Admin, you can use the Google Workspace Admin SDK to audit actions performed with the OS Login API. By reviewing these events, you can track when a user adds, deletes, or updates an SSH key, or deletes POSIX account information.

You can retrieve OS Login API audit activity events, from the Google Workspace Admin SDK, by calling Activities.list() with applicationName=gcp. For more information, see Google Cloud activity events in the Google Workspace Admin SDK Reports API documentation.

Modify user accounts using the Directory API

OS Login uses either your Cloud Identity or Google Workspace user settings when connecting to an instance. If you are a Google Workspace super admin, you can use the Directory API to complete the following tasks for your Google Workspace or Cloud Identity user accounts:

Modify instance login settings
Make a user an administrator
Modify user properties such as account name and email
Add and remove SSH keys for a user
Modify POSIX account information
Change the username that the users connect to on the instance

The following examples show how to modify or remove user accounts using the Directory API. For more information about the account properties that you can edit, see the Directory API reference.

Modify account properties

To modify a user's POSIX account information or manage the user's SSH keys, issue a PUT request to the directory.users.update method and specify one or more properties to change on the user account.

If you modify a user's posixAccounts properties, you must specify the current or new username, uid, and gid values in the request.

If you modify the user's sshPublicKeys properties, you must specify the key value in the request.

The following is an example of a PUT request:

PUT https://admin.googleapis.com/admin/directory/v1/users/USER_KEY

{
 "posixAccounts": [
  {
    "username": "USERNAME",
    "uid": "UID",
    "gid": "GID",
    "homeDirectory": "USER_HOME_PATH",
    "shell": "SHELL_PATH"
   }
  ],
 "sshPublicKeys": [
  {
    "key": "KEY_VALUE",
    "expirationTimeUsec": EXPIRATION_TIME
   }
  ],
}

Replace the following:

USER_KEY: the user's primary email address, alias email address, or unique user ID.
USERNAME: the username that Compute Engine adds to the VM for the user. This value must be unique within your organization and must not end in a tilde ("~") or contain a period (".").
UID: the user ID on the VM for this user. This property must be a value between 1001 and 60000, or a value between 65535 and 2147483647. To access a container-optimized OS, the UID must have a value between 65536 and 214748646. The UID must be unique within your organization.
GID: the group ID on the VM that the user belongs to.
USER_HOME_PATH: (Optional) the home directory on the VM for the user. For example, /home/example_username.
SHELL_PATH: (Optional) the path to the default shell for the user after they connect to the instance. For example, /bin/bash or /bin/sh.
KEY_VALUE: the public SSH key value.
EXPIRATION_TIME: (Optional) the key's expiration time in microseconds since epoch (1 second = 10⁶ microseconds).

Remove account properties

To clear the posixAccounts and sshPublicKeys data for a user, issue a PUT request to the directory.users.update method, setting the posixAccounts and sshPublicKeys fields to null:

PUT https://admin.googleapis.com/admin/directory/v1/users/USER_KEY

{
 "posixAccounts": null,
 "sshPublicKeys": null
}

Replace USER_KEY with the user's primary email address, alias email address, or unique user ID.

Use Linux groups with OS Login (Deprecated)

Organization admins can use the Cloud Identity Groups API to configure supplementary Linux groups for OS Login users by creating and managing POSIX groups. OS Login links POSIX groups with supplementary Linux groups in your organization's VMs so that you can manage the permissions users have in your VMs.

Manage user membership in Linux groups

To create a POSIX group, see Creating and updating POSIX groups.

To add users to a group, see Add or invite users to a group.

Membership updates take effect within 10 minutes. Group changes are reflected in all newly created VMs. POSIX group updates may take up to six hours to propagate to all running VMs. Users may have to log out or use the newgrp command to observe group changes.

Delete POSIX groups configurations

OS Login POSIX group support is deprecated. We recommend that you delete OS Login POSIX groups configurations.

You must be an organization administrator to delete OS Login POSIX group configurations.

If you don't know your organization resource ID, get your organization resource ID.
List all POSIX groups in your organization. Note the email address of each group.
For each POSIX group in your organization, do the following:
1. Retrieve the group information. Note the posixGroups.gid.
2. Delete the POSIX group.
Optionally verify that all groups have been deleted by listing all POSIX groups in your organization. If all groups have been successfully deleted, the response is empty.

Rate limits for Linux groups with OS Login

Linux groups with OS Login use oslogin.googleapis.com/metadata_server_groups_requests quota. By default, the quota limit is 60 requests/minute, per project for a particular region.

If you need a higher rate limit, you can request a quota adjustment from the Quotas page in the Google Cloud console.

Go to Quotas

Use workforce identity federation with OS Login

Organizations that use workforce identity federation can use OS Login to manage access to their VMs. When workforce identity federation is enabled for an organization, OS Login uses certificate-based authentication instead of key-based authentication to verify user identities.

Before you begin

Create a workforce identity pool.
Set up google.posix_username attribute mappings.
Configure your VM to use OS Login with workforce identity federation by doing the following:
1. Confirm that the VM has OpenSSH 7.4 or later installed by running the following command on the VM:
```
ssh -V
```
2. Update the guest environment.

Limitations

You can't use workforce identity federation with OS Login two-factor authentication (2FA).
The VM you're connecting to must have OpenSSH version 7.4 or later to use workforce identity federation with OS Login.

If your organization uses workforce identity federation, you can't access VM's serial ports.

Connect to VMs that use OS Login and workforce identity federation

Connect to VMs that use OS Login with workforce identity federation using the Google Cloud console, the gcloud CLI, or other SSH clients.

Console

When you connect to VMs that use OS Login with workforce identity federation using SSH-in-browser, Compute Engine configures the SSH certificate on your behalf when you attempt to connect.

To connect to VMs, do the following:

In the Google Cloud console, go to the VM instances page.
Go to VM instances
In the list of virtual machine instances, click SSH in the row of the instance that you want to connect to.

gcloud

When you connect to VMs that use OS Login with workforce identity federation using the gcloud CLI, Compute Engine configures the SSH certificate on your behalf when you attempt to connect.

Connect to a VM using SSH by running the gcloud beta compute ssh command:

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Run the following command:
```
gcloud beta compute ssh --project=PROJECT_ID --zone=ZONE VM_NAME
```
Replace the following:
- PROJECT_ID: the ID of the project that contains the VM
- ZONE: the name of the zone that the VM is located in
- VM_NAME: the name of the VM
If you have set default properties for the Google Cloud CLI, you can omit the --project and --zone flags from this command. For example:
```
gcloud compute ssh VM_NAME
```

IAP Desktop

When you connect to VMs that use OS Login with workforce identity federation using IAP Desktop, Compute Engine configures the SSH certificate on your behalf when you attempt to connect.

To connect to a VM using IAP Desktop, do the following:

Install IAP Desktop on your workstation if you haven't already.
Open IAP Desktop. The Add projects window opens.
When prompted, sign in with workforce identity federation.
In the Add projects window, enter the project ID or name of the project that contains the VMs you want to connect to.
In the Project Explorer window, right-click the name of the VM again and select Connect to connect to the VM.

SSH client

To connect to a VM that uses OS Login with workforce identity federation using an SSH client, do the following:

Create an SSH key if you don't already have one.
Sign your public SSH key using the users.projects.locations.signSshPublicKey method:
```
POST https://oslogin.googleapis.com/v1beta/users/USER/projects/PROJECT_ID/locations/LOCATION:signSshPublicKey

{
 "ssh_public_key": "PUBLIC_KEY"
}
```
Replace the following:
- USER: a single identity in a workforce pool, in the following format:
```
principal:%2F%2Fiam.googleapis.com%2Flocations%2Fglobal%2FworkforcePools%2POOL_ID%2Fsubject%2FSUBJECT_ATTRIBUTE_VALUE
```
  Replace the following:
  - POOL_ID: the workforce pool the user belongs to.
  - SUBJECT_ATTRIBUTE_VALUE: the value of the user's google.posix_username attribute mapping.
- PROJECT_ID: the project ID of the project that contains the VM you want to connect to.
- LOCATION: the zone where the VM you want to connect to is located.
- PUBLIC_KEY: the contents of your SSH public key file.
Copy the SSH certificate from the output of the user.signSshPublicKey method and save the contents in a new file.
Set permissions on the SSH certificate file, by running the following command:
```
sudo chmod 600 FILE_NAME
```
Replace FILE_NAME with the name of the file.
Connect to the VM using the following command:
```
ssh -i PATH_TO_PRIVATE_KEY -o CertificateFile=PATH_TO_SSH_CERTIFICATE USERNAME@EXTERNAL_IP
```
Replace the following:
- PATH_TO_PRIVATE_KEY: the path to your private SSH key file.
- PATH_TO_SSH_CERTIFICATE: the path to your SSH certificate file.
- USERNAME: the value of the user's google.posix_username attribute mapping.
- EXTERNAL_IP: the external IP address of the VM.

What's next

Learn how to set up OS Login.
Learn how to set up OS Login with 2-step verification.
Read an overview of the OS Login feature.
Troubleshoot OS Login.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-07-17 UTC.

Manage OS Login in an organization Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Console

gcloud

REST

OS Login organization policy

Limitations

Workarounds for Cloud Data Fusion and Managed Airflow

Enable the organization policy

Permissions required for this task

Console

gcloud

Grant instance access to users outside of your organization

Manage the OS Login API

Audit OS Login events

Modify user accounts using the Directory API

Modify account properties

Remove account properties

Use Linux groups with OS Login (Deprecated)

Manage user membership in Linux groups

Delete POSIX groups configurations

Rate limits for Linux groups with OS Login

Use workforce identity federation with OS Login

Before you begin

Limitations

Connect to VMs that use OS Login and workforce identity federation

Console

gcloud

IAP Desktop

SSH client

What's next

Manage OS Login in an organization