## OS Login Guest Environment for Google Compute Engine This repository contains the system components responsible for providing Google Cloud OS Login features on Google Compute Engine instances. **Table of Contents** * [Overview](#overview) * [Components](#components) * [Authorized Keys Command](#authorized-keys-command) * [NSS Modules](#nss-modules) * [PAM Modules](#pam-modules) * [Utilities](#Utilities) * [Control Script](#control-script) * [SELinux Policy](#selinux-policy) * [Source Packages](#source-packages) * [DEB](#deb) * [RPM](#rpm) ## Overview The OS Login Guest Environment consists of the following main components: * **Authorized Keys Command** which provides SSH keys from the user's OS Login profile to sshd for authenticating users at login. * **NSS Modules** which provide support for making OS Login user and group information available to the system, using NSS (Name Service Switch) functionality. * **PAM Modules** which provide authorization (and authentication if two-factor support is enabled) support allowing the system to use Google Cloud IAM permissions to control the ability to log into an instance or to perform operations as root (via `sudo`). In addition to the main components, there are also the following utilities: * **google_oslogin_control** is a shell script for activating/deactivating the OS Login components. * **google_oslogin_nss_cache** is a utility for updating the local user and group cache. * **selinux** contains SELinux policy definition files and a compiled policy package for configuring SELinux to support OS Login. The **packaging** directory also contains files used to generate `.deb` and `.rpm` packages for the OS Login components. ## Components #### Authorized Keys Command The `google_authorized_keys` binary is designed to be used with the sshd `AuthorizedKeysCommand` option in [sshd_config(5)](https://linux.die.net/man/5/sshd_config). It does the following: * Reads the user's profile information from the metadata server: ``` http://metadata.google.internal/computeMetadata/v1/oslogin/users?username= ``` * Checks to make sure that the user is authorized to log in: ``` http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?email=&policy=login ``` * If the check is successful, returns the SSH keys associated with the user for use by sshd. Otherwise, exits with an error code. #### NSS Modules `libnss_oslogin.so` and `libnss_cache_oslogin.so` are NSS service modules which make OS Login users and groups available for use on the local system. The module is activated by adding `oslogin` and `cache_oslogin` entries for services in [nsswitch.conf(5)](https://linux.die.net/man/5/nsswitch.conf). * To return a list of all users, the NSS module queries: ``` http://metadata.google.internal/computeMetadata/v1/oslogin/users?pagesize= ``` * To look up a user by username, the NSS module queries: ``` http://metadata.google.internal/computeMetadata/v1/oslogin/users?username= ``` * To look up a user by UID, the NSS module queries: ``` http://metadata.google.internal/computeMetadata/v1/oslogin/users?uid= ``` #### PAM Modules `pam_oslogin_login.so` is a PAM module which determines whether a given user is allowed to SSH into an instance. It is activated by adding an entry for the account group to the PAM service config 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= ``` * If the user does not have OS Login profile information it is passed on to the system authentication modules to be processed as a local user. * Otherwise, the module confirms whether the user has permissions to SSH into the instance: ``` http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?email=&policy=login ``` * If the user is authorized, PAM returns a success message and SSH can proceed. Otherwise, PAM returns a denied message and the SSH check will fail. `pam_oslogin_admin.so` is a PAM module which determines whether a given user should have admin (sudo) permissions on the instance. It is activated by adding an entry for the `account` group to the PAM service config 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= ``` * If the user is not an OS Login user (a local user account), the module returns success. * Otherwise, the module determines if the user has admin permissions: ``` http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?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 removed from `/var/google-sudoers.d/` if it exists. ## Utilities #### Control Script The `google_oslogin_control` shell script activates or deactivates the OS Login features. It is invoked by the google accounts daemon. The control file performs the following tasks: * Adds (or removes) AuthorizedKeysCommand and AuthorizedKeysCommandUser lines to (from) `sshd_config` and restarts sshd. * Adds (or removes) `oslogin` and `cache_oslogin` to (from) `nsswitch.conf`. * Adds (or removes) the `account` entries to (from) the PAM sshd config. Also adds (or removes) the `pam_mkhomedir.so` module to automatically create the home directory for an OS Login user. * Creates (or deletes) the `/var/google-sudoers.d/` directory, and a file called `google-oslogin` in `/etc/sudoers.d/` that includes the directory. #### SELinux Policy The `selinux` directory contains `.te` (type enforcement) and `.fc` (file context) files used by SELinux to give the OS Login features the appropriate SELinux permissions. These are compiled using `checkmodule` and `semodule_package` to create an policy package `oslogin.pp`. ## Source Packages 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 the `packaging/` directory. #### DEB _Note: the `packaging/setup_deb.sh` script performs these steps, but is not production quality._ 1. Install build dependencies: ``` sudo apt-get -y install make g++ libcurl4-openssl-dev libjson-c-dev libpam-dev ``` 1. Install deb creation tools: ``` sudo apt-get -y install debhelper devscripts build-essential ``` 1. Create a compressed tar file named `google-compute-engine-oslogin_M.M.R.orig.tar.gz` using the files in this directory, excluding the `packaging` directory (where M.M.R is the version number). 1. In a separate directory, extract the `.orig.tar.gz` file and copy the `debian` directory into the top level. 1. To build the package, run the command ``` debuild -us -uc ``` #### RPM _Note: the `packaging/setup_rpm.sh` script performs these steps, but is not production quality._ 1. Install build dependencies: ``` sudo yum -y install make gcc-c++ libcurl-devel json-c json-c-devel pam-devel policycoreutils-python ``` 1. Install rpm creation tools: ``` sudo yum -y install rpmdevtools ``` 1. Create a compressed tar file named `google-compute-engine-oslogin_M.M.R.orig.tar.gz` using the files in this directory, excluding the `packaging` directory (where M.M.R is the version number). 1. In a separate location, create a directory called `rpmbuild` and a subdirectory called `SOURCES`. Copy the `.orig.tar.gz` file into the `SOURCES` directory. 1. Copy the `SPECS` directory from the `rpmbuild` directory here into the `rpmbuild` directory you created. 1. To build the package, run the command: ``` rpmbuild --define "_topdir /path/to/rpmbuild" -ba /path/to/rpmbuild/SPECS/google-compute-engine-oslogin.spec ```