Setting up OS Login with two-factor authentication

If you use OS Login to manage access to your instances, you can add an extra layer of security by using two-factor authentication, also known as 2FA.

OS Login supports the following 2FA methods or challenge types:

• Google Authenticator
• Text message or phone call verification
• Phone prompts

To use 2FA authentication on your instances, complete the following steps:

1. Enable 2FA for your Google account or domain
2. Enable 2FA on your project or instance
3. Connect to your instances

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

Supported operating systems

OS Login two-factor authentication require operating system images created after the following dates:

Enabling 2FA for your Google account or domain

Before you can enable two-factor authentication for your project or instance, you must first enable 2FA on your Google account or domain. Ensure that you enable 2FA on the domain that contains the project or instances, or for the user that owns the project or instances.

A G Suite administrator can enable two-factor authentication for a domain or an individual Google user can enable two-factor authentication at the user account level.

Enabling 2FA on your project or instance

After you enable two-factor authentication at the domain or user account level, you can then enable individual instances or project to use OS Login 2FA.

An instance 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 instance creation or project set up. You can also configure OS Login 2FA on an existing instance or project that already has OS Login enabled.

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

gcloud compute instances create [INSTANCE_NAME] \
  --metadata enable-oslogin=True,enable-oslogin-2fa=True

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

gcloud compute instances add-metadata \
  --metadata enable-oslogin=True,enable-oslogin-2fa=True [INSTANCE_NAME]

Connecting to instances

After you configure the necessary roles, connect to an instance using Compute Engine tools. Compute Engine automatically generates SSH keys and associates them with your user account. Alternatively, if you create your own SSH keys and add the public keys to your user account, you can connect to instances using third-party tools. The instance obtains your public key from your user account and allows you to connect to the instance if you provide the correct user name and matching private SSH key.

When you connect to your instance, you will get a message based on your selected 2FA 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 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.

After you connect to your instance, review the expected login behaviors.

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 desired type.

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

1. Go to the Logs page in the GCP Console.

   Go to the Logs page

2. Expand the drop-down menu and select Audited Resource.
3. In the search bar, type oslogin.googleapis.com and hit Enter.

4. A list of audit logs describing the two-factor authentication requests displays. Expand any of the entries to get more information:

   

For any of the audit logs, you can:

1. Expand the protoPayload property.

   

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 requests.

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

StartSession audit logs

ContinueSession audit logs