Google Cloud OS Login

2.20.0 · active · verified Sun Mar 29

The `google-cloud-os-login` library is the Python client for the Google Cloud OS Login API, which enables managing SSH access to Google Compute Engine instances using IAM identities. It simplifies SSH key management, unifies Linux user accounts across multiple VMs, and integrates with Google Cloud IAM for granular authorization, two-factor authentication (2FA), and comprehensive audit logging. The library maintains a frequent release cadence, often receiving updates weekly or bi-weekly as part of the larger `google-cloud-python` client ecosystem.

Warnings

gotcha When OS Login is enabled for a VM, it will *not* accept SSH keys stored in instance or project metadata. Conversely, VMs without OS Login enabled will not accept SSH keys from OS Login profiles. Ensure consistency in your key management strategy.
Fix: Use OS Login for SSH key management if enabled, or revert to metadata-based keys if OS Login is disabled. Do not mix methods for a single VM.
gotcha Encountering 'The specified username or UID is not unique within given system ID' error when connecting via SSH to an OS Login-enabled VM. This can happen if a user account is deleted and a new one with the same email is created soon after, as POSIX information can take up to 48 hours to be fully removed.
Fix: Wait at least 48 hours for POSIX information to clear, or restore the deleted account and explicitly remove its POSIX information before re-deleting. For G Suite organizations, manage username formats via Cloud Identity administrators.
gotcha The 'Login profile size exceeds 32 KiB' error can occur if too many SSH keys or other profile values are associated with a user's OS Login profile.
Fix: Review the OS Login profile using `gcloud compute os-login describe-profile` and remove any unused or redundant SSH keys using `gcloud compute os-login ssh-keys remove`.
gotcha The OS Login Sign API may not be supported in all GCP regions/zones, leading to 'This region is not supported by the OS Login Sign API at this time' errors when attempting to connect via `gcloud compute ssh`.
Fix: Prefer deploying VMs in regions known to support the OS Login Sign API (e.g., `us-central1`, `europe-west1`, `asia-east1`). Alternatively, disable OS Login for the instance/project or add keys directly to your OS Login profile and use regular SSH if locked to an unsupported region.
gotcha Users might require the `roles/iam.serviceAccountUser` IAM role in addition to `roles/compute.osLogin` or `roles/compute.osAdminLogin` to successfully SSH into an OS Login-enabled instance, especially if service account impersonation is involved or the VM uses a specific service account.
Fix: Ensure the user or the service account acting on their behalf has the `roles/iam.serviceAccountUser` role granted on the relevant service account or project.
gotcha By default, OS Login generates a Linux username by combining the user's email username and domain (e.g., `user@example.com` becomes `user_example_com`). If you expect a simpler username (e.g., `user`), this behavior can be confusing.
Fix: For G Suite organizations, administrators can change the default setting to remove the domain suffix for newly generated usernames. This is not configurable for individual consumer accounts.

Install

pip install google-cloud-os-login Install latest version

Imports

OsLoginServiceClient

from google.cloud.oslogin_v1 import OsLoginServiceClient

OsLoginServiceAsyncClient

from google.cloud.oslogin_v1 import OsLoginServiceAsyncClient

Quickstart

This quickstart demonstrates how to initialize the `OsLoginServiceClient` and retrieve the OS Login profile for the currently authenticated user. This profile includes POSIX account information and associated SSH public keys. For this to work, OS Login must be enabled on your Google Cloud project/instance, and the executing user or service account must have appropriate IAM permissions (e.g., `roles/compute.osLogin` or `roles/compute.osAdminLogin`). Authentication is typically handled automatically via `gcloud auth application-default login` or `GOOGLE_APPLICATION_CREDENTIALS`.

import os
from google.cloud.oslogin_v1 import OsLoginServiceClient

def get_current_user_login_profile():
    """Retrieves the OS Login profile for the authenticated user."""
    # Instantiate a client
    client = OsLoginServiceClient()

    # The 'name' field identifies the user whose login profile is to be retrieved.
    # 'users/me' refers to the currently authenticated user.
    # For a specific user, use 'users/{email_address}' or 'users/{uid}'.
    user_name = 'users/me'
    
    try:
        login_profile = client.get_login_profile(name=user_name)
        print(f"Retrieved Login Profile for {user_name}:")
        print(f"  Name: {login_profile.name}")
        print(f"  Posix Accounts:")
        for account in login_profile.posix_accounts:
            print(f"    - Username: {account.username}, UID: {account.uid}, GID: {account.gid}")
        print(f"  SSH Public Keys:")
        if login_profile.ssh_public_keys:
            for key_id, ssh_key in login_profile.ssh_public_keys.items():
                print(f"    - Key ID: {key_id}, Key: {ssh_key.key}")
        else:
            print("    No SSH public keys found.")

    except Exception as e:
        print(f"Error retrieving login profile: {e}")
        print("Please ensure OS Login is enabled for the user/project and correct IAM roles are granted.")

if __name__ == '__main__':
    # Before running, ensure default authentication is set up, e.g., by running 'gcloud auth application-default login'
    # or by setting the GOOGLE_APPLICATION_CREDENTIALS environment variable.
    # This example assumes the 'users/me' identifier will work with the authenticated credential.
    get_current_user_login_profile()

view raw JSON →