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, then 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 by selecting one of the following options:
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
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- 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
In the Google Cloud console, go to the Logs Explorer page.
In the Query field, enter the following query:
protoPayload.serviceName="oslogin.googleapis.com"
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.
Click Run query. The results are displayed in the Query results section.
Click the
expander arrow next to each result to show detailed information.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
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.
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 themethodName
field for the connection attempt. To learn what eachmethodName
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 successfulContinueSession
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, theContinueSession
method accepts the response to the challenge or method and either authenticates or rejects the authentication attempt.Expand the
authenticationInfo
section to view theprincipalEmail
field. TheprincipalEmail
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?
- Learn more about Logging query language to customize your OS Login audit log queries.
- Learn how SSH connections to Linux VMs work on Compute Engine.