Troubleshooting OS Login

This document describes how to troubleshoot OS Login using the metadata server. For information about setting up OS Login or for step-by-step instructions, see Setting up OS Login or Setting up OS Login with 2-step verification.

You can query the metadata server from within a virtual machine (VM) instance. For more information, see Storing and retrieving instance metadata.

Before you begin

Default OS Login metadata entries

Compute Engine defines a set of default metadata entries that serves OS Login information. Default metadata is always defined and set by the server. The following table describes the entries you can query.

Relative to http://metadata.google.internal/computeMetadata/v1/
Metadata entry Description
project/attributes/enable-oslogin Checks if OS Login is enabled on the current Cloud project.
instance/attributes/enable-oslogin Checks if OS Login is enabled on the current VM.
oslogin/users/ Retrieves profile information for OS Login users. You can pass query parameters such as username, uid, pagesize and pagetoken.
oslogin/authorize/

Retrieves login or administrative level permission settings for an OS Login user.

To check a permission, you must specify the policy query parameter. The value of the policy parameter must be set to either login (to check for login permission) or adminLogin (to check for sudo access).

Checking if OS Login is configured

If both instance and project metadata are set, instance metadata takes precedence. You can run the following commands on your VMs.

  1. Check if OS Login is configured in your instance metadata:

    curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/enable-oslogin" -H "Metadata-Flavor: Google"

    If OS Login is configured on the instance, the output is TRUE. A 404 error indicates that OS Login isn't configured in instance metadata.

  2. If the metadata value is not configured for the instance, you can check if OS Login is configured for your project:

    curl "http://metadata.google.internal/computeMetadata/v1/project/attributes/enable-oslogin" -H "Metadata-Flavor: Google"

    If OS Login is configured for the project, the output is TRUE. A 404 error indicates that OS Login isn't configured in project metadata.

Viewing OS Login users

To view the profile information for multiple users, you need to specify the pagesize and pagetoken parameters. Replace the pagesize and pagetoken with the required numeric value.

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?pagesize=PAGE_SIZE&
pagetoken=PAGE_TOKEN" -H "Metadata-Flavor: Google"

For example, to set the pagesize to 1 and the pagetoken to 0, run the following command:

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?pagesize=1&pagetoken=0" -H "Metadata-Flavor: Google"

On most distributions, you can also run the Unix command getent passwd to retrieve the password entries for organization users.

Viewing a specific OS Login user

To view the profile information for a specific user on your VM, run the following command:

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=USERNAME" -H "Metadata-Flavor: Google"

Replace USERNAME with the username of the user that you want to query.

For example, you can perform a request to look up the user user_example_com. The following command and output show added formatting for improved readability.

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=user_example_com" -H "Metadata-Flavor: Google"

The output is similar to the following:

{
    "loginProfiles": [{
        "name": "12345678912345",
        "posixAccounts": [{
            "primary": true,
            "username": "user_example_com",
            "uid": "123451",
            "gid": "123451",
            "homeDirectory": "/home/user_example_com",
            "operatingSystemType": "LINUX"
        }],
        "sshPublicKeys": {
            "204c4b4fb...": {
                "key": "ssh-rsa AAAAB3Nz...",
                "fingerprint": "204c4b4fb..."
            }
        }
    }]
}

On most distributions, you can also run Unix commands such as getent passwd username or getent passwd uid to retrieve profile information.

To retrieve the SSH keys for a user, you can also run /usr/bin/google_authorized_keys USERNAME. If no keys are returned, the user might not have the required permissions to log into the VM.

Checking login permissions

To view login and administrative level permissions, you must provide the policy=login&email=LOGIN_NAME query parameters.

  1. Query the user profile to get the value of the name field:

    curl "http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=user_example_com" -H "Metadata-Flavor: Google"

  2. In the output, take note of the name.

  3. Run the following login command using the value of name:

    curl "http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?policy=login&email=LOGIN_NAME" -H "Metadata-Flavor: Google"

For example, you can query the login permissions for the user user_example_com that was viewed in the previous section:

curl "http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?policy=login&email=12345678912345" -H "Metadata-Flavor: Google"

The command output indicates the user is authorized to log in to the VM:

{"success":true}

Checking if your VM has a service account

You can query the metadata server to find the service account associated with your VM. On your VM, run the following command:

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/" -H "Metadata-Flavor: Google"

The output is similar to the following:

12345-sa@developer.gserviceaccount.com/
default/

If no service account is found, the output is blank.

What's next