1## OS Login Guest Environment for Google Compute Engine 2 3This package enables Google Cloud OS Login features on Google Compute Engine 4instances. 5 6**Table of Contents** 7 8* [Overview](#overview) 9* [Components](#components) 10 * [Authorized Keys Command](#authorized-keys-command) 11 * [NSS Module](#nss-module) 12 * [PAM Module](#pam-module) 13 * [Utils](#utils) 14* [Utility Directories](#utility-directories) 15 * [bin](#bin) 16 * [packaging](#packaging) 17 * [policy](#policy) 18* [Source Packages](#source-packages) 19 * [DEB](#deb) 20 * [RPM](#rpm) 21* [Version Updates](#version-updates) 22 23## Overview 24 25The OS Login package has the following components: 26 27* **Authorized Keys Command** to fetch SSH keys from the user's OS Login 28 profile and make them available to sshd. 29* **NSS Module** provides support for making OS Login user and group 30 information available to the system, using NSS (Name Service Switch) 31 functionality. 32* **PAM Module** provides authorization and authentication support allowing 33 the system to use data stored in Google Cloud IAM permissions to control 34 both, the ability to log into an instance, and to perform operations as root 35 (sudo). 36* **Utils** provides common code to support the components listed above. 37 38In addition to the main components, there are also utilities for packaging and 39installing these components: 40 41* **bin** contains a shell script for activating/deactivating the package 42 components. 43* **packaging** contains files used to generate `.deb` and `.rpm` packages for 44 the OS Login components. 45* **policy** contains SELinux "type enforcement" files for configuring SELinux 46 on CentOS/RHEL systems. 47 48## Components 49 50#### Authorized Keys Command 51 52The `google_authorized_keys` binary is designed to be used with the sshd 53[AuthorizedKeysCommand](https://linux.die.net/man/5/sshd_config) option in 54`sshd_config`. It does the following: 55 56* Reads the user's profile information from the metadata server. 57 ``` 58 http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=<username> 59 ``` 60* Checks to make sure that the user is authorized to log in. 61 ``` 62 http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?email=<user_email>&policy=login 63 ``` 64* If the check is successful, returns the SSH keys associated with the user 65 for use by sshd. 66 67#### NSS Module 68 69The `nss_oslogin` module is built and installed in the appropriate `lib` 70directory as a shared object with the name `libnss_oslogin.so.2`. The module is 71then activated by an `oslogin` entry in `/etc/nsswitch.conf`. The NSS module 72supports looking up `passwd` entries from the metadata server via 73`getent passwd`. 74 75* To return a list of all users, the NSS module queries: 76 ``` 77 http://metadata.google.internal/computeMetadata/v1/oslogin/users?pagesize=<pagesize> 78 ``` 79* To look up a user by username, the NSS module queries: 80 ``` 81 http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=<username 82 ``` 83* To look up a user by UID, the NSS module queries: 84 ``` 85 http://metadata.google.internal/computeMetadata/v1/oslogin/users?uid=<uid> 86 ``` 87 88#### PAM Module 89 90The `pam_module` directory contains two modules used by Linux PAM (Pluggable 91Authentication Modules). 92 93The first module, `pam_oslogin_login.so`, determines whether a given user is 94allowed to SSH into an instance. It is activated by adding an 95`account requisite` line to the PAM sshd config file and does the following: 96 97* Retrieves the user's profile information from the metadata server. 98 ``` 99 http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=<username> 100 ``` 101* If the user has OS Login profile information (as opposed to a local user 102 account), confirms whether the user has permissions to SSH into the 103 instance. 104 ``` 105 http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?email=<user_email>&policy=login 106 ``` 107* If the user is a local user account or is authorized, PAM returns a success 108 message and SSH can proceed. Otherwise, PAM returns a denied message and the 109 SSH check will fail. 110 111The second module, `pam_oslogin_admin.so`, determines whether a given user 112should have admin (sudo) permissions on the instance. It is activated by adding 113an `account optional` line to the PAM sshd config file and does the following: 114 115* Retrieves the user's profile information from the metadata server. 116 ``` 117 http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=<username> 118 ``` 119* If the user is a local user account, the module exits with success. 120* If the user is an OS Login user, the module perform an authorization check 121 to determine if the user has admin permissions. 122 ``` 123 http://metadata.google.internal/computeMetadata/v1/oslogin/authorize?email=<user_email>&policy=adminLogin 124 ``` 125* If the user is authorized as an admin, a file with the username is added to 126 `/var/google-sudoers.d/`. The file gives the user sudo privileges. 127* If the authorization check fails for admin permissions, the file is removed 128 from `/var/google-sudoers.d/` if it exists. 129 130#### Utils 131 132`oslogin_utils` contains common functions for making HTTP calls, 133interacting with the metadata server, and for parsing JSON objects. 134 135## Utility Directories 136 137#### bin 138 139The `bin` directory contains a shell script called `google_oslogin_control` that 140activates or deactivates the OS Login features. It is called in the pre and post 141install scripts in the `.deb` and `.rpm` packages. The control file performs the 142following tasks: 143 144* Adds (or removes) AuthorizedKeysCommand and AuthorizedKeysCommandUser lines 145 to (from) `sshd_config` and restarts sshd. 146* Adds (or removes) `oslogin` to (from) `nsswitch.conf`. 147* Adds (or removes) the `account` entries to (from) the PAM sshd config. Also 148 adds (or removes) the `pam_mkhomedir.so` module to automatically create the 149 home directory for an OS Login user. 150* Creates (or deletes) the `/var/google-sudoers.d/` directory, and a file 151 called `google-oslogin` in `/etc/sudoers.d/` that includes the directory. 152 153#### packaging 154 155The `packaging` directory contains files for creating `.deb` and `.rpm` 156packages. See [Source Packages](#source-packages) for details. 157 158#### policy 159 160The `policy` directory contains `.te` (type enforcement) files used by SELinux 161to give the OS Login features the appropriate SELinux permissions. These are 162compiled using `checkmodule` and `semodule_package` to create an `oslogin.pp` 163that is intstalled in the appropriate SELinux directory. 164 165## Source Packages 166 167There is currently support for creating packages for the following distros: 168* Debian 8 169* Debian 9 170* CentOS/RHEL 6 171* CentOS/RHEL 7 172 173#### DEB 174 175_Note: the `packaging/setup_deb.sh` script performs these steps, but is not 176production quality._ 177 1781. Install build dependencies: 179 ``` 180 sudo apt-get -y install make g++ libcurl4-openssl-dev libjson-c-dev libpam-dev 181 ``` 1821. Install deb creation tools: 183 ``` 184 sudo apt-get -y install debhelper devscripts build-essential 185 ``` 1861. Create a compressed tar file named 187 `google-compute-engine-oslogin_M.M.R.orig.tar.gz` using the files in this 188 directory, excluding the `packaging` directory (where M.M.R is the version 189 number). 1901. In a separate directory, extract the `.orig.tar.gz` file and copy the 191 appropriate `debian` directory into the top level. (e.g. When working on 192 Debian 8, copy the `debian8` directory to a directory named `debian` within 193 the code directory.) 1941. To build the package, run the command 195 ``` 196 debuild -us -uc 197 ``` 198 199#### RPM 200 201_Note: the `packaging/setup_rpm.sh` script performs these steps, but is not 202production quality._ 203 2041. Install build dependencies: 205 ``` 206 sudo yum -y install make gcc-c++ libcurl-devel json-c json-c-devel pam-devel policycoreutils-python 207 ``` 2081. Install rpm creation tools: 209 ``` 210 sudo yum -y install rpmdevtools 211 ``` 2121. Create a compressed tar file named 213 `google-compute-engine-oslogin_M.M.R.orig.tar.gz` using the files in this 214 directory, excluding the `packaging` directory (where M.M.R is the version 215 number). 2161. In a separate location, create a directory called `rpmbuild` and a 217 subdirectory called `SOURCES`. Copy the `.orig.tar.gz` file into the 218 `SOURCES` directory. 2191. Copy the `SPECS` directory from the `rpmbuild` directory here into the 220 `rpmbuild` directory you created. 2211. To build the package, run the command: 222 ``` 223 rpmbuild --define "_topdir /path/to/rpmbuild" -ba /path/to/rpmbuild/SPECS/google-compute-engine-oslogin.spec 224 ``` 225