Monitor OS Login audit logs

You can monitor connection attempts to virtual machine (VM) instances that have OS Login and OS Login two-factor authentication (2FA) enabled by viewing OS Login audit logs. These audit logs are always enabled and cannot be disabled by data access configs.

You can also track OS Login-related events and activities such as adding, deleting, or updating an SSH key, or deleting POSIX information with the Google Workspace Admin SDK.

Before you begin

  • If you haven't already, set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine as follows.

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init
    2. Set a default region and zone.

View OS Login audit logs

To display a list of OS Login connection attempts, query Cloud Audit Logs.

Console

  1. In the Google Cloud console, go to the Logs Explorer page.

    Go to Logs Explorer

  2. In the Query field, enter the following query:

    protoPayload.serviceName="oslogin.googleapis.com"

  3. If the event you're looking for happened more than an hour ago, set a custom time frame by clicking the clock symbol and entering a custom range.

    Set query time frame.

  4. Click Run query. The results are displayed in the Query results section.

  5. Click the expander arrow next to each result to show detailed information.

  6. To learn about the types of OS Login audit logs and what they mean, continue to the Review OS Login audit logs section of this document.

gcloud

  1. View Cloud Audit Logs using the gcloud logging read command:

    gcloud logging read --freshness=TIME 'protoPayload.serviceName="oslogin.googleapis.com"'

    Replace TIME with the amount of time you want to query. For example, 1h queries log entries in the past hour. For information about date and time formats, see gcloud topic datetimes.

    The results display.

  2. To learn about the types of OS Login audit logs and what they mean, continue to the Review OS Login audit logs section of this document.

Review OS Login audit logs

Review the methodName and principalEmail fields of the audit logs to learn about the types of connection attempts to VMs that have OS Login enabled and the users who initiated those connection attempts.

  • Expand the protoPayload section to view the methodName field for the connection attempt. To learn what each methodName field means, see the following table:

    Method Connection type Description
    google.cloud.oslogin.v1.OsLoginService.CheckPolicy All OS Login connections Indicates a connection attempt to a VM. For non-2FA connections, a successful response indicates that the user connected to the VM. For 2FA connections, a successful connection is indicated by both a successful CheckPolicy call and a successful ContinueSession call.
    google.cloud.oslogin.OsLoginService.v1.StartSession OS Login 2FA connections Indicates a new 2FA authentication session. In a StartSession call, a client declares its capabilities to the server and obtains information about the available challenges.
    google.cloud.oslogin.OsLoginService.v1.ContinueSession OS Login 2FA connections

    Indicates a continuation of an authentication session. The client completes the challenge proposed by the server on the previous StartSession call or requests and completes a different challenge type. Then, the ContinueSession method accepts the response to the challenge or method and either authenticates or rejects the authentication attempt.

  • Expand the authenticationInfo section to view the principalEmail field. The principalEmail field shows the email address of the user who tried to connect to the VM.

OS Login audit log properties

The following sections describe the properties for audit logs. Some properties are common across all audit logs, and other properties are specific to the CheckPolicy, StartSession, and ContinueSession methods.

Common OS Login audit log properties

The properties listed in the following table are common across all OS Login audit logs.

Property Value
serviceName oslogin.googleapis.com
resourceName A string containing the project number that 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. To learn more about severity levels, see LogSeverity.
authenticationInfo.principalEmail The email address of the user that the method is authenticating.
request.numericProjectId The project number of the Google Cloud project.

CheckPolicy audit log properties

The properties listed in the following table apply to CheckPolicy audit logs.

Property Value
methodName google.cloud.oslogin.v1.OsLoginService.CheckPolicy
request.@type type.googleapis.com/google.cloud.oslogin.v1.CheckPolicyRequest
request.policy The permission being checked. Either LOGIN, which checks if the user is authorized to log into the VM, or ADMIN_LOGIN, which checks if the user is authorized to have administrative access on the VM.
response.success The result of the LOGIN or ADMIN_LOGIN request.policy check. Either true or false, depending on whether the user is authorized for the specified policy.

StartSession audit log properties

The properties listed in the following table apply to StartSession audit logs, for VMs that have OS Login 2FA enabled.

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.
response.authenticationStatus Status of the session. One of Authenticated, Challenge required, or Challenge pending.
response.sessionId An ID string uniquely identifying the session. This session ID is passed to the ContinueSession call in the sequence.
response.challenges The set of challenges that you can attempt to pass during 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.

ContinueSession audit log properties

The properties listed in the following table apply to ContinueSession audit logs, for VMs that have OS Login 2FA enabled.

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 StartSession call.
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 the StartSession response.
request.action The action to take to complete the challenge.
response.authenticationStatus Status of the session. For example, Authenticated, Challenge required, or Challenge pending.
response.challenges.status SUCCESS indicates that a user has successfully connected to the VM.
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.

What's next?