Repository files navigation

This repository contains the system components responsible for providing GoogleCloud OS Login features on Google Compute Engine instances.

Table of Contents

• Overview
• Components
  • Authorized Keys Command
  • NSS Modules
  • PAM Modules
• Utilities
  • SELinux Policy
• Source Packages

The OS Login Guest Environment consists of the following main components:

• Authorized Keys Command which provides SSH keys from the user's OS Loginprofile to sshd for authenticating users at login.
• NSS Modules which provide support for making OS Login user and groupinformation available to the system, using NSS (Name Service Switch)functionality.
• PAM Modules which provide authorization (and authentication iftwo-factor support is enabled) support allowing the system to use GoogleCloud IAM permissions to control the ability to log into an instance or toperform operations as root (viasudo).

In addition to the main components, there are also the following utilities:

• google_oslogin_nss_cache is a utility for updating the local user andgroup cache.
• selinux contains SELinux policy definition files and a compiled policypackage for configuring SELinux to support OS Login.

Thepackaging directory also contains files used to generate.deb and.rpm packages for the OS Login components.

Thegoogle_authorized_keys binary is designed to be used with the sshdAuthorizedKeysCommand option insshd_config(5).It does the following:

• Reads the user's profile information from the metadata server:

  http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=<username>

• Checks to make sure that the user is authorized to log in:

  http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?email=<user_email>&policy=login

• If the check is successful, returns the SSH keys associated with the userfor use by sshd. Otherwise, exits with an error code.

libnss_oslogin.so andlibnss_cache_oslogin.so are NSS service modules whichmake OS Login users and groups available for use on the local system. The moduleis activated by addingoslogin andcache_oslogin entries for services innsswitch.conf(5).

• To return a list of all users, the NSS module queries:

  http://metadata.google.internal/computeMetadata/v1/oslogin/users?pagesize=<pagesize>

• To look up a user by username, the NSS module queries:

  http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=<username>

• To look up a user by UID, the NSS module queries:

  http://metadata.google.internal/computeMetadata/v1/oslogin/users?uid=<uid>

pam_oslogin_login.so is a PAM module which determines whether a given user isallowed to SSH into an instance.

It is activated by adding an entry for the account group to the PAM serviceconfig for sshd as:

account requisite pam_oslogin_login.so

This module:

• Retrieves the user's profile information from the metadata server:

  http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=<username>

• If the user does not have OS Login profile information it is passed on tothe system authentication modules to be processed as a local user.
• Otherwise, the module confirms whether the user has permissions to SSH intothe instance:

  http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?email=<user_email>&policy=login

• If the user is authorized, PAM returns a success message and SSH canproceed. Otherwise, PAM returns a denied message and the SSH check willfail.

pam_oslogin_admin.so is a PAM module which determines whether a given usershould have admin (sudo) permissions on the instance.

It is activated by adding an entry for theaccount group to the PAM serviceconfig for sshd config as:

account optional pam_oslogin_admin.so

This module:

• Retrieves the user's profile information from the metadata server.

  http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=<username>

• If the user is not an OS Login user (a local user account), the modulereturns success.
• Otherwise, the module determines if the user has admin permissions:

  http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?email=<user_email>&policy=adminLogin

• If the user is authorized as an admin, a file with the username is added to/var/google-sudoers.d/. The file gives the user sudo privileges.
• If the authorization check fails for admin permissions, the file is removedfrom/var/google-sudoers.d/ if it exists.

Theselinux directory contains.te (type enforcement) and.fc (filecontext) files used by SELinux to give the OS Login features the appropriateSELinux permissions. These are compiled usingcheckmodule andsemodule_package to create an policy packageoslogin.pp.

There is currently support for creating packages for the following distros:

• Debian 9
• CentOS/RHEL 6
• CentOS/RHEL 7

Files for these packages are in thepackaging/ directory.