Setting up OS Login with 2-step verification

This document covers the basic steps for setting up OS Login with 2-step verification.

If you use OS Login to manage access to your virtual machine (VM) instances, you can add an extra layer of security by using 2-step verification also known as two-factor authentication, or 2FA. To learn more about the other benefits of using OS Login, see OS Login.

To use OS Login 2FA on your VMs, complete the following steps:

  1. Install or update the guest environment.
  2. Optional: If you are an organization administrator, review Managing OS Login in an organization.

  3. Enable 2-step verification for your Google Account or domain.

  4. Enable 2FA on your project or VM.

  5. Grant the necessary IAM roles to yourself, your project members, or your organization members.

  6. Optional: Add custom SSH keys to user accounts for yourself, your project member, or organization members. Alternatively, Compute Engine can automatically generate these keys for you when you connect to VMs.

  7. Connect to VMs.

  8. Review the expected login behaviors.

To further restrict VM access, you can set up hardware-backed SSH key pairs. For more information, see SSH with security keys.

After setting up OS Login 2FA, you can use audit logs to monitor your authentication sessions.

Before you begin

Limitations

  • OS Login is not currently supported in Google Kubernetes Engine (GKE). GKE cluster nodes continue to use metadata SSH keys when OS Login is enabled.

  • Currently, Fedora CoreOS images do not support OS Login. To manage instance access to VMs created using these images, use the Fedora CoreOS ignition system.

  • Windows Server and SQL Server images do not support OS Login.

Supported methods or challenge types

OS Login supports the following 2-step verification methods or challenge types:

Step 1: Install or update the guest environment

Your VM instance must have the latest version of the guest environment installed. Most public images already have the latest version installed. If you don't have the latest guest environment, update your guest environment.

If you have VMs that run custom images that you imported, install the guest environment on those VMs.

If you don't have the latest guest environment, update your guest environment.

Step 2: (Optional) Review managing OS Login in an organization

If you are organization admin, you can set some configurations such as enabling OS Login at the organization level. See Managing OS Login in an organization.

Step 3: Enable 2-step verification for your Google Account or domain

Before you can enable OS Login 2FA for your project or VM, you must first enable 2-step verification on your Google Account or domain. Make sure that you either enable 2-step verification on the domain that contains the project or VMs or enable 2-step verification for the user that owns the project or VMs.

As a security best practice, require 2-step verification on user accounts in your organization. Enabling OS Login 2FA doesn't block login access to users who don't have two-factor authentication configured.

A Google Workspace administrator can enable 2-step verification for a domain, or an individual Google user can enable 2-step verification for a user-account.

Domain

2-step verification for a domain must be enabled by a Google Workspace administrator.

To enable 2-step verification for a domain, see Protect your business with 2-Step Verification in the Google Workspace Admin guide.

User account

If your user accounts are not managed by a Google Workspace administrator, you can configure 2-step verification for individual Google Accounts.

To configure 2-step verification for an individual Google Account, see Google 2-Step Verification.

Step 4: Enable OS Login 2FA on your project or VM

After you enable 2-step verification for a domain or user account, you can then enable individual VMs or projects to use OS Login 2FA. A VM or project must have OS Login enabled in order to use OS Login 2FA.

You can configure both OS Login and OS Login 2FA during VM creation or project setup. You can also configure OS Login 2FA on an existing VM or project that already has OS Login enabled.

To configure your project or VM to use OS Login two-factor authentication, set enable-oslogin-2fa=TRUE and enable-oslogin=TRUE in the project or instance metadata.

Console

You can apply the metadata values on your projects or VMs using one of the following options:

  • Option 1: Set enable-oslogin-2fa=TRUE and enable-oslogin=TRUE in instance metadata when you create a VM.

    1. In the Google Cloud Console, go to the VM instances page.

      Go to VM instances

    2. Click Create instance.

    3. On the Create a new instance page, fill in the properties for your instance.

    4. In the Metadata section, add the following metadata entries:

      • Set enable-oslogin to TRUE.
      • Set enable-oslogin-2fa to TRUE.

    5. Click Create to create the VM.

  • Option 2: Set enable-oslogin-2fa and enable-oslogin=TRUE in project-wide metadata so that the setting is applied to all of the VMs in your project.

    1. In the Google Cloud Console, go to the Metadata page.

      Go to Metadata

    2. Click Edit.

    3. In the Metadata section, add the following metadata entries:

      • Set enable-oslogin to TRUE.
      • Set enable-oslogin-2fa to TRUE.

    4. Click Save to apply the changes.

  • Option 3: Set enable-oslogin=TRUE and enable-oslogin-2fa=TRUE in the metadata of an existing VM.

    1. In the Google Cloud Console, go to the VM instances page.

      Go to VM instances

    2. Click the name of the VM on which you want to set the metadata value.

    3. On the Instance details page, click Edit.

    4. Under Custom metadata, add the following metadata entries:

      • Set enable-oslogin to TRUE.
      • Set enable-oslogin-2fa to TRUE.

    5. On the Instance details page, click Save to apply your changes to the instance.

gcloud

You can apply the metadata values on your projects or VMs by using one of the following options:

  • Option 1: Set enable-oslogin=TRUE and enable-oslogin-2fa=TRUE in instance metadata when you create a VM.

    gcloud compute instances create VM_NAME \
 --metadata enable-oslogin=True,enable-oslogin-2fa=True

    Replace VM_NAME with the name of your VM.

  • Option 2: Set enable-oslogin=TRUE and enable-oslogin-2fa=TRUE in project-wide metadata, so that it applies to all of the VMs in your project.

    gcloud compute project-info add-metadata \
  --metadata enable-oslogin=True,enable-oslogin-2fa=True

  • Option 3: Set enable-oslogin=TRUE and enable-oslogin-2fa=TRUE in metadata of an existing VM.

    gcloud compute instances add-metadata \
  --metadata enable-oslogin=True,enable-oslogin-2fa=True VM_NAME

    Replace VM_NAME with the name of your VM.

Step 5: Configure OS Login roles on user accounts

Granting OS Login IAM roles

After you enable OS Login on one or more instances in your project, those VMs accept connections only from user accounts that have the necessary IAM roles in your project or organization.

To allow OS Login access to these VMs, you need to grant the necessary roles to the user. To allow OS Login access, complete the following steps:

  1. Grant one of the following instance access roles.

    You can grant these instance access roles at the instance level by using the gcloud compute instances add-iam-policy-binding command.

  2. If your VM instance uses a service account, then each user must be configured to have the roles/iam.serviceAccountUser role on the service account. To learn how to add access for a user to a service account, see Managing service account impersonation.

  3. For users that are outside of your organization to access your VMs, in addition to granting an instance access role, grant the roles/compute.osLoginExternalUser role. This role must be granted at the organization level by an organization administrator. For more information, see Granting instance access to users outside of your organization.

Granting SSH access to a service account

You can use OS Login roles to allow service accounts to establish SSH connections to your instances. This is useful for the following tasks:

You can grant SSH access to your service accounts by using the following process:

  1. Create a service account.
  2. Grant the necessary OS Login roles to your service account. Service accounts require the same roles as user accounts. To learn how to configure roles and permissions for service accounts, see Granting roles to service accounts.
  3. Provide Application Default Credentials to your service account, so that it can authorize requests to the necessary APIs. Provide Application Default Credentials using one of the following options:

After you grant SSH access to your service accounts, you can configure your apps to create SSH keys and establish SSH connections to other instances on your VPC networks. To see an example app for service account SSH, read the Connecting apps to instances using SSH tutorial.

Revoking OS Login IAM roles

To revoke user access to instances that are enabled to use OS Login, remove the user roles from that user account. For information about removing an IAM role for a user, see Granting, changing, and revoking access to resources.

When a user's access is revoked, the user will still have public SSH keys that are associated with their account, but those keys no longer function on the VM instances.

Step 6: (Optional) Add SSH keys to a user account

If you want connect to your VMs by using third-party tools, you need to add your SSH keys to your user account. If you connect to your instances using other options, such as the gcloud command-line tool or SSH from the browser, you can skip this step because Compute Engine automatically generates SSH keys for you.

You can associate public SSH keys with the following user account types:

You can use the gcloud command-line tool, or the OS Login API to add SSH keys to your own account. Alternatively, if you are a domain admin for an organization, you can use the Directory API to add SSH keys to the Users resource in your organization.

gcloud

The gcloud compute os-login commands are available only on Cloud SDK version 184 and later.

Use the gcloud command-line tool to associate public SSH keys with an account.

gcloud compute os-login ssh-keys add \
    --key-file=KEY_FILE_PATH \
    --ttl=EXPIRE_TIME

Replace the following:

  • KEY_FILE_PATH: the path to the public SSH key on your local workstation. Ensure that the public SSH key is properly formatted. If you use PuTTYgen on Linux systems to generate your public keys, you must use the public-openssh format.
  • EXPIRE_TIME: an optional flag to set an expiration time for the public SSH key. For example, you can specify 30m and the SSH key will expire after 30 minutes. This flag uses the following units:
    • s for seconds
    • m for minutes
    • h for hours
    • d for days
    • Set the value to 0 to indicate no expiration time.

OS Login API

Use the OS Login API to associate public SSH keys with an account:

POST https://oslogin.googleapis.com/v1/users/ACCOUNT_EMAIL:importSshPublicKey

{
 "key": "SSH_KEY",
 "expirationTimeUsec": "EXPIRATION_TIMESTAMP"
}

Replace the following:

  • ACCOUNT_EMAIL: the email address that represents your managed user account.
  • SSH_KEY: The public key that you want to apply to the account. Make sure that the public SSH key is properly formatted. If you use PuTTYgen on Linux systems to generate your public keys, you must use the public-openssh format.
  • EXPIRATION_TIMESTAMP: the expiration time for the key, in microseconds since epoch.

Directory API

If you are a domain admin for an organization, you can use the Directory API reference to add SSH keys to the account of another user in your organization. For example, create a PUT request to the directory.users.update method with one or more SSH sshPublicKeys entries:

PUT https://www.googleapis.com/admin/directory/v1/users/USER_ID_KEY

{
 "sshPublicKeys": [
  {
   "key": "SSH_KEY",
   "expirationTimeUsec": "EXPIRATION_TIMESTAMP"
  },
  {
   "key": "SSH_KEY",
   "expirationTimeUsec": "EXPIRATION_TIMESTAMP"
  }
 ]
}

Replace the following:

  • USER_ID_KEY: an immutable ID for the user.
  • SSH_KEY: a public key that you want to apply to the account. Make sure that the public SSH key is properly formatted. If you use PuTTYgen on Linux systems to generate your public keys, you must use the public-openssh format.
  • EXPIRATION_TIMESTAMP: the expiration time for a key, in microseconds since epoch.

To remove all keys from an account, specify "sshPublicKeys": null as the body, replacing USER_ID_KEY with an immutable ID for the user:

PUT https://www.googleapis.com/admin/directory/v1/users/USER_ID_KEY

{
  "sshPublicKeys": null
}

After you add your keys to your account, you can connect to instances using third-party tools and the username associated with your account. Your organization admin can change this username. Accounts that don't belong to organizations cannot change the default username.

You can find the current username for your account by running the gcloud compute os-login describe-profile command.

For example, your output might resemble the following:

name: '314159265358979323846'
posixAccounts:
- gid: '27182818'
  homeDirectory: /home/user_example_com
  ⋮
  uid: '27182818'
  username: user_example_com
⋮

Step 7: Connect to VMs

When you connect to a VM, you have 3 main options:

If you connect to a VM by using either gcloud command-line tool or SSH from the browser, Compute Engine automatically generates SSH keys and associates them with your user account.

If you connect to a VM by using a third-party tool, you need to add the public keys to your user account. The VM gets your public key from your user account and lets you connect to the VM if you provide the correct user name and matching private SSH key.

When you connect to your VM, you will get a message based on your selected 2-step verification method or challenge type.

  • For Google Authenticator, you will see the following message:

    "Enter your one-time password:"

  • For text message or phone call verification, you will see the following message:

    "A security code has been sent to your phone. Enter code to continue:"

  • For phone prompt, you will see the following message:

    "A login prompt has been sent to your enrolled device:"

  • For security key OTP, you will see the following message:

    "Enter your security code by visiting g.co/sc:"

For the phone prompt method, accept the prompts on your phone or tablet to continue.

For other methods, enter your security code or one-time password.

Step 8: Review expected login behaviors

  • On some instances using OS Login, you might receive the following error message after the connection is established:

    /usr/bin/id: cannot find name for group ID 123456789

    Ignore this error message. This error does not affect your instances.

  • Cloud Identity administrators can configure POSIX information and set a username for organization members. If a username is not set by a Cloud Identity administrator, OS Login generates a default Linux username by combining the username and domain from the email address associated with the user's Google profile. This naming convention ensures uniqueness. For example, if the user email associated with the Google profile is user@example.com, then their generated username is user_example_com.

    Optionally, Google Workspace organizations can change their default to remove the domain suffix for newly generated usernames. For example, if the user email address associated with the Google profile is user@example.com, then their generated username is user. For more information, see Managing the OS Login API.

    If a user is from a separate Google Workspace organization, the generated username is prefixed with 'ext_'. For example, if user@example.com is accessing a VM in a different organization, then their generated username is ext_user_example_com.

  • When you log in to an instance by using the gcloud compute ssh command, the login message has the following format for a user user that belongs to the example.com domain:

    Using OS Login user user_example_com instead of default user user

    This message confirms that the user is logging in with an OS Login profile.

Viewing OS Login 2FA audit logs

Compute Engine provides audit logs to track two-factor authentication requests. Two-factor authentication has two request types:

  • StartSession. Starts a new authentication session. In a StartSession call, a client declares its capabilities to the server and obtains information about the first challenge. A StartSession call returns the following:

    • A session ID. This session ID is passed to all subsequent ContinueSession calls.
    • Information about the challenge or 2FA method used in this new authentication session.

  • ContinueSession. Continues an existing authentication session. By using the provided session ID, the ContinueSession API can perform one of the following two actions:

    • Accept the response to a challenge or method and then either authenticate, reject, or require additional challenges from the user.
    • Switch to a different type of challenge than the one initially proposed by the server on the previous round of API calls. If a client chooses to complete a different challenge type—for example, Google Authenticator instead of phone prompt—the client can request a different challenge type in a call to the server by using a request.challengeId of the type you want to use.

To view logs, you must have permissions for the Logs Viewer or be a project viewer or editor.

  1. In the Cloud Console, go to the Logs page.

    Go to Logs

  2. Expand the drop-down menu and select Audited Resource.

  3. In the search bar, type oslogin.googleapis.com and press Enter. You see a list of audit logs describing the two-factor authentication requests. Expand any of the entries to get more information:

    Audit logs for two-factor authentication.

For any of the audit logs, you can do the following:

  1. Expand the protoPayload property.

    Audit log metrics for two-factor authentication.

  2. Look for methodName to see activity this log applies to (either a StartSession or ContinueSession request).

    For example, if this log tracks a StartSession request, the method name would say "google.cloud.oslogin.OsLoginService.v1.StartSession". Similarly, a ContinueSession log would say "google.cloud.oslogin.OsLoginService.v1.ContinueSession". An audit log entry is recorded for every start and continue session request.

There are different audit log properties for different log types. For example, audit logs relating to StartSession have properties that are specific to starting sessions, while audit logs for ContinueSession have their own set of properties. There are certain audit log properties that are also shared between both log types.

All two-factor authentication audit logs

Property Value
serviceName oslogin.googleapis.com
resourceName A string containing the project number. This project number indicates which login request the audit log belongs to. For example, projects/myproject12345.
severity The severity level of the log message. For example, INFO or WARNING.
request.email The email address of the user that the API call is authenticating.
request.numericProjectId The project number of the Google Cloud project.
response.@type type.googleapis.com/google.cloud.oslogin.OsLoginService.v1.StartOrContinueSessionResponse
response.sessionId An ID string uniquely identifying the session. This session ID is passed to the next API call in the sequence.
response.authenticationStatus Status of the session. For example, Authenticated, Challenge required, or Challenge pending.
response.challenges The set of challenges that you can attempt to pass this round of authentication. At most, one of these challenges is started and has a status of READY. The others are provided as options that the user can specify as an alternative to the proposed primary challenge.

StartSession audit logs

Property Value
methodName google.cloud.oslogin.OsLoginService.v1.StartSession
request.@type type.googleapis.com/google.cloud.oslogin.OsLoginService.v1.StartSessionRequest
request.supportedChallengeTypes The list of challenge types or 2FA methods that you can choose from.

ContinueSession audit logs

Property Value
methodName google.cloud.oslogin.OsLoginService.v1.ContinueSession
request.sessionId An ID string uniquely identifying the previous session. This session ID is passed from the previous API call in the sequence.
request.@type type.googleapis.com/google.cloud.oslogin.OsLoginService.v1.ContinueSessionRequest
request.challengeId An ID string identifying which challenge to start or execute. This ID must belong to a challenge type returned from the response.challenges call in a previous API response.
request.action The action to take.

What's next