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