Manage OS Login in an organization

Linux

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

Note: To complete any of the tasks detailed in this document, you must be aGoogle Workspace administrator.

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 allnew projects, and the VM instances created in these new projects, have OS Loginenabled.

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

  • enable-oslogin=true is included in the project metadata for all newprojects.
  • Requests that setenable-oslogin tofalse in instance or projectmetadata are rejected, for new and existing VMs and projects.

Limitations

OS Login is not supported in the following products, features, and VMs:
  • Cloud Data Fusion versions 6.1.4 and earlier
  • Cloud Composer 1
  • Windows Server and SQL Server VMs
  • Fedora CoreOS VMs. To manage instance access to VMs created using theseimages, use theFedora CoreOS ignition system

Workarounds for Cloud Data Fusion and Cloud Composer

To use OS Login in organizations that use Cloud Data Fusion andCloud Composer, youcan enable OS Login constraint at the organization level and then selectivelydisable the constraint on projects or folders for the affectedprojects.

For more information about editing organization policies, seecreating and editing policies.

Enable the organization policy

Permissions required for this task

To perform this task, you must have the followingpermissions:

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

Console

To set the OS Loginorganization policyfrom the console, complete the following steps:

  1. In the Google Cloud console, go to theOrganization policies page.

    Go to the Organization policies page

  2. In the policies list, clickRequire OS Login to view theOS Login constraints.
  3. ClickEdit to edit your existing OS Login constraints.
  4. On theEdit page, selectCustomize.
  5. To enable enforcement of this constraint, selectOn.
  6. ClickSave to apply the constraint settings.

gcloud

To set the OS Login organization policy, use thegcloud beta resource-manager org-policies enable-enforcecommand.

  1. Find your organization ID.

    gcloud organizations list

  2. Set the constraint in your organization. Replaceorganization-id with your yourorganization 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 projectwith the--folder or the--project flags, and the folder ID and projectID, 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:

Grant instance access to users outside of your organization

Note: If your project is part of anorganization,you can grant instance access to users who are outside of yourorganization by usingroles/compute.osLoginExternalUser or by using acustom role with thecompute.oslogin.updateExternalUser permission.

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

Theroles/compute.osLoginExternalUserIAM role lets external Google Accounts interact with the other OS Login rolesby allowing them to configure POSIX account information.

To grantroles/compute.osLoginExternalUser and other necessary OS Logininstance access roles to users outside of your organization, complete thefollowing steps:

  1. In the Google Cloud console, go to theIAM & Admin page.

    Go to IAM & Admin

  2. Click theSelect a project drop-down menu. In theSelect a resourcedialog 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.
  3. ClickGrant access to add a new role to a user.
  4. In theNew principals field, add the email address for the user for whomyou want to configure instance access.
  5. From theRole drop-down menu, select theCompute OS Login External User role.
  6. ClickSave.
  7. If you have not already done so,grant the other OS Login instance access rolesto the user at the project or organization level.

The user can nowconnect to instancesin 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 settingGoogle Workspace admin controls. To configure Google Workspace admincontrols or view configuration options, seeControl who uses Google Cloud in your organization.As a Google Workspace admin, you can also turn on or off certain featuresof the OS Login API. This includes the following options:

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

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

Audit OS Login events

As a Google Workspace Admin, you can use the Google Workspace AdminSDK 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 POSIXaccount information.

You can retrieve OS Login API audit activity events, from theGoogle Workspace Admin SDK, by callingActivities.list() withapplicationName=gcp. For more information, seeGoogle Cloud activity eventsin the Google Workspace Admin SDK Reports API documentation.

Modify user accounts using the Directory API

Note: You can't use the Directory API to modify Google consumer accounts,service accounts, or accounts for users outside your Google Workspaceorganization.

OS Login uses either yourCloud Identity orGoogle Workspaceuser settings when connecting to an instance. If you are a Google Workspacesuper admin, you can use the Directory API to complete the following tasks foryour 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 theDirectory API. For more information about the account properties that you canedit, see theDirectory API reference.

Modify account properties

To modify a user's POSIX account information or manage the user's SSH keys,issue aPUT request to thedirectory.users.update methodand specify one or more properties to change on the user account.

If you modify a user'sposixAccounts properties, you must specify thecurrent or newusername,uid, andgid values in the request.

If you modify the user'ssshPublicKeys properties, you must specify thekey value in the request.

Caution: Do not update thesystemId property. OS Login ignores POSIXaccount information where thesystemId is not blank.

The following is an example of aPUT 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 thatCompute Engine adds to the VM for the user. This value must beunique within your organization and must not end in a tilde ("~") orcontain a period (".").
  • UID: the user ID on the VM for this user.This property must be a value between1001 and60000, or a valuebetween65535 and2147483647. To access a container-optimized OS, theUID must have a value between65536 and214748646. TheUID must be unique within yourorganization.
  • GID: the group ID on the VM that the user belongsto.
  • USER_HOME_PATH: (Optional) the home directory onthe VM for the user. For example,/home/example_username.
  • SHELL_PATH: (Optional) the path to the defaultshell 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 expirationtime in microseconds since epoch (1 second = 106microseconds).

Remove account properties

To clear theposixAccounts andsshPublicKeys data for a user,issue aPUT request to thedirectory.users.update method,setting theposixAccounts andsshPublicKeys fields tonull:

PUT https://admin.googleapis.com/admin/directory/v1/users/USER_KEY{ "posixAccounts": null, "sshPublicKeys": null}

ReplaceUSER_KEY with the user's primary emailaddress, alias email address, or unique user ID.

Use Linux groups with OS Login (Deprecated)

Caution: OS Login POSIX groups support isdeprecated. As of September 26, 2024,you can no longer use OS Login to link POSIX groups with supplementary Linuxgroups in your organization's VMs. We recommend that youdelete OS Login POSIX group configurations.

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

Manage user membership in Linux groups

To create a POSIX group, seeCreating and updating POSIX groups.

To add users to a group, seeAdd or invite users to a group.

Membership updates take effect within 10 minutes. Group changes arereflected in all newly created VMs. POSIX group updates may take up to six hoursto propagate to all running VMs. Users may have to log out or use thenewgrpcommand to observe group changes.

Delete POSIX groups configurations

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

You must be anorganization administratorto delete OS Login POSIX group configurations.

Caution: Removing OS Login POSIX groups configurations might disrupt users'ability to access resources on Linux VMs. If you use POSIX groups to manageaccess on your Linux VMs, ensure that you transition to an alternative method ofaccess management before you delete OS Login POSIX group configurations.
  1. If you don't know your organization resource ID,get your organization resource ID.
  2. List all POSIX groupsin your organization. Note the email address of each group.
  3. For each POSIX group in your organization, do the following:
    1. Retrieve the group information. Note theposixGroups.gid.
    2. Delete the POSIX group.
  4. Optionally verify that all groups have been deleted bylisting all POSIX groupsin your organization. If all groups have been successfully deleted, theresponse is empty.

Rate limits for Linux groups with OS Login

Linux groups with OS Login useoslogin.googleapis.com/metadata_server_groups_requests quota. By default, thequota limit is60 requests/minute, per project for a particular region.

If you need a higher rate limit, you canrequest a quota adjustment from the Quotaspage in the Google Cloud console.

Go to Quotas

Use workforce identity federation with OS Login

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Organizations that useworkforce identity federation can useOS Login to manage access to their VMs. When workforce identity federation isenabled for an organization, OS Login uses certificate-based authenticationinstead of key-based authentication to verify user identities.

Before you begin

Limitations

Connect to VMs that use OS Login and workforce identity federation

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

Console

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

To connect to VMs, do the following:

  1. In the Google Cloud console, go to theVM instances page.

    Go to VM instances

  2. In the list of virtual machine instances, clickSSH in the row of the instance that you want to connect to.

    SSH button next to instance name.

gcloud

When you connect to VMs that use OS Login with workforce identity federationusing thegcloud CLI,Compute Engine configures the SSH certificate on your behalf when youattempt to connect.

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

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, aCloud 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.

  1. Run the following command:

    gcloud beta compute ssh --project=PROJECT_ID --zone=ZONEVM_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 haveset default properties for the Google Cloud CLI, you can omit the--project and--zone flags from this command. For example:

    gcloud compute sshVM_NAME
Note: When you connect to VMs using the gcloud CLI, Compute Engine creates a persistent SSH key for you. For more information about SSH keys, seeSSH connections to Linux VMs.

IAP Desktop

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

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

  1. Install IAP Desktop on your workstation if you haven't already.

  2. Open IAP Desktop. TheAdd projects window opens.

  3. When prompted, sign in with workforce identity federation.

  4. In theAdd projects window, enter the project ID or name of the project that contains the VMs you want to connect to.

  5. In theProject Explorer window, right-click the name of the VM again and selectConnect to connect to the VM.

SSH client

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

  1. Create an SSH key if you don'talready have one.

  2. Sign your public SSH key using theusers.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:

    • PROJECT_ID: the project ID of the project thatcontains the VM you want to connect to.

    • LOCATION: the zone where the VM you want toconnect to is located.

    • PUBLIC_KEY: the contents of your SSH public keyfile.

  3. Copy the SSH certificate from the output of theuser.signSshPublicKeymethod and save the contents in a new file.

  4. Set permissions on the SSH certificate file, by running the followingcommand:

    sudo chmod 600FILE_NAME

    ReplaceFILE_NAME with the name of the file.

  5. Connect to the VM using the following command:

    ssh -iPATH_TO_PRIVATE_KEY -o CertificateFile=PATH_TO_SSH_CERTIFICATEUSERNAME@EXTERNAL_IP

    Replace the following:

    • PATH_TO_PRIVATE_KEY: the path to your privateSSH key file.
    • PATH_TO_SSH_CERTIFICATE: the path to your SSHcertificate file.
    • USERNAME: the value of the user'sgoogle.posix_username attribute mapping.
    • EXTERNAL_IP: the external IP address of the VM.

What's next

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

Last updated 2025-12-15 UTC.