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.
pip install google-cloud-os-loginVerified import paths — ran on the pinned version, not inferred.
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`.
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.
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.
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`.
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.
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.
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.
Ensure that Application Default Credentials are properly configured in the execution environment. This can involve running `gcloud auth application-default login` for local development, setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file, or deploying the application in a Google Cloud environment (like Compute Engine, Cloud Run, GKE) that automatically provides credentials.
Ensure Application Default Credentials (ADC) are configured in the execution environment. This typically involves authenticating `gcloud` (e.g., `gcloud auth application-default login`), setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file, or ensuring the environment (e.g., GCE VM, Cloud Run) has appropriate scopes and metadata for implicit ADC.
Ensure the user has the appropriate OS Login IAM roles (e.g., `roles/compute.osLogin` for standard access or `roles/compute.osAdminLogin` for sudo access) on the project or instance, and `roles/iam.serviceAccountUser` if the instance uses a service account. For external users (outside the organization), the `roles/compute.osLoginExternalUser` role must also be granted at the organization level.
```bash
gcloud projects add-iam-policy-binding PROJECT_ID \
--member='user:YOUR_USER_EMAIL' \
--role='roles/compute.osLogin'
# Or for admin access:
gcloud projects add-iam-policy-binding PROJECT_ID \
--member='user:YOUR_USER_EMAIL' \
--role='roles/compute.osAdminLogin'
# If using a service account, also add:
gcloud projects add-iam-policy-binding PROJECT_ID \
--member='user:YOUR_USER_EMAIL' \
--role='roles/iam.serviceAccountUser'
```Install the `google-cloud-os-login` library using pip in your active Python environment. ```bash pip install google-cloud-os-login ```
Remove unused or expired SSH keys from the OS Login profile using the `gcloud compute os-login ssh-keys remove` command. ```bash gcloud compute os-login describe-profile # Identify the key's fingerprint or string to remove gcloud compute os-login ssh-keys remove --key=KEY_FINGERPRINT_OR_STRING ```
Deploy your VM instance in a region that supports the OS Login Sign API (e.g., `us-central1`, `europe-west1`, `asia-east1`). Alternatively, if using that region is unavoidable, temporarily disable OS Login for the instance and revert to traditional metadata-based SSH keys, or add your SSH key to your OS Login profile and use regular SSH.
```bash
# Option 1: Disable OS Login for the instance (if regional support is critical and you can't change region)
gcloud compute instances add-metadata INSTANCE_NAME \
--metadata enable-oslogin=FALSE \
--zone=REGION-ZONE
# Option 2: Add an SSH key to your OS Login profile and use standard SSH client (if OS Login is still desired but not via gcloud in unsupported region)
gcloud compute os-login ssh-keys add --key-file=~/.ssh/id_rsa.pub
# Then connect via standard SSH
ssh -i ~/.ssh/id_rsa YOUR_OS_LOGIN_USERNAME@YOUR_VM_EXTERNAL_IP
```Wait up to 48 hours for the old POSIX user information to be fully removed after a user deletion, then retry. Alternatively, if the user account was deleted, consider restoring it or ensuring that the account's POSIX information was explicitly removed before deletion.