Manage OS Login in an organization

If you use OS Login to manage access to your instances, you can set configurations at the organization level for your Cloud Identity account. For example, you can control who can directly use the OS Login API, enable OS Login for all virtual machine (VM) instances in an organization, and grant access to external users.

This topic covers the following tasks:

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.

When this constraint is set up, the following conditions are applied:

  • enable-oslogin=true is included in the project metadata for all new projects.
  • Requests that set enable-oslogin to false in VM or project metadata are rejected, for new and existing VMs and projects.


OS Login is not supported in the following products:

  • Cloud Data Fusion versions 6.1.4 and earlier
  • Cloud Composer
  • Google Kubernetes Engine (GKE) public clusters or in private clusters that run node pool versions earlier than 1.20.5.

Workarounds for Cloud Data Fusion, Cloud Composer, and GKE

To use OS Login in organizations that use these products, you can enable OS Login constraint at the organization level and then selectively disable the constraint on projects or folders for the affected projects.

For more information about editing organization policies, see creating and editing policies.

Enable the organization policy

To enable the OS Login policy, you can set the OS Login constraint on specific projects and folders by using the gcloud command-line tool. You can also set the OS Login constraint on the entire organization by using either the Google Cloud Console or the gcloud command-line tool.


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

  1. In the Google Cloud Console, go to the Organization policies page.

    Go to the Organization policies page

  2. In the policies list, click Require OS Login to view the OS Login constraints.
  3. Click Edit to edit your existing OS Login constraints.
  4. On the Edit page, select Customize.
  5. To enable enforcement of this constraint, select On.
  6. Click Save to apply the constraint settings.


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

  1. Find your organization ID.

    gcloud organizations list
  2. Set the constraint in your organization. Replace organization-id with your your organization ID.

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

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 \

For projects, run the following command:

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

Replace the following:

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 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:

  1. In the Google Cloud Console, go to the project and organization selection page.

    Go to the project and organization selection page

  2. In the Organization drop-down menu, select your organization.
    1. Click All, to view all of your organizations.
    2. Click the name of the organization.
  3. Click Add to add a new role to a user.
  4. Specify the user name for the user for whom you want to configure instance access.
  5. Click Select a role to specify which roles you want to grant to the users.
  6. In the Compute Engine roles list, select the Compute OS Login External User role.
  7. Click Add to confirm that you want to grant the selected role to the user.
  8. 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, the user 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 an organization 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.

For more information about the account properties that you can edit, see the Directory API reference.

For example, create a PUT request to the directory.users.update method and specify one or more properties to change on the user account:


 "posixAccounts": [
    "username": "user-name",
    "uid": "uid",
    "gid": "gid",
    "homeDirectory": "user-home-path",
    "shell": "shell-path"

Replace the following:

  • user-key: The user's primary email address, alias email address, or unique user ID.
  • user-name: The username that Compute Engine adds to the instance for the user. This value must be unique within your organization. This user-name must not end in a tilde ("~") or contain a period (".") as this might cause issues when running sudo commands on the VM.
  • uid: The user ID on the instance 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 value between 65536 and 214748646. The UID must be unique within your organization.
  • gid: The group ID on the instance that this user belongs to.
  • user-home-path: The home directory on the instance for this user. For example, /home/example_username.
  • shell-path: The path to the default shell for the user after they connect to the instance. For example, /bin/bash or /bin/sh.

Use Linux groups with OS Login

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.

What's next