diff options
Diffstat (limited to 'packages/google-compute-engine-oslogin/README.md')
| -rw-r--r-- | packages/google-compute-engine-oslogin/README.md | 170 |
1 files changed, 84 insertions, 86 deletions
diff --git a/packages/google-compute-engine-oslogin/README.md b/packages/google-compute-engine-oslogin/README.md index 6f967c5..4acc31e 100644 --- a/packages/google-compute-engine-oslogin/README.md +++ b/packages/google-compute-engine-oslogin/README.md @@ -1,76 +1,73 @@ ## OS Login Guest Environment for Google Compute Engine -This package enables Google Cloud OS Login features on Google Compute Engine -instances. +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 Module](#nss-module) - * [PAM Module](#pam-module) - * [Utils](#utils) -* [Utility Directories](#utility-directories) - * [bin](#bin) - * [packaging](#packaging) - * [policy](#policy) + * [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) -* [Version Updates](#version-updates) ## Overview -The OS Login package has the following components: +The OS Login Guest Environment consists of the following main components: -* **Authorized Keys Command** to fetch SSH keys from the user's OS Login - profile and make them available to sshd. -* **NSS Module** provides support for making OS Login user and group +* **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 Module** provides authorization and authentication support allowing - the system to use data stored in Google Cloud IAM permissions to control - both, the ability to log into an instance, and to perform operations as root - (sudo). -* **Utils** provides common code to support the components listed above. - -In addition to the main components, there are also utilities for packaging and -installing these components: - -* **bin** contains a shell script for activating/deactivating the package - components. -* **packaging** contains files used to generate `.deb` and `.rpm` packages for - the OS Login components. -* **policy** contains SELinux "type enforcement" files for configuring SELinux - on CentOS/RHEL systems. +* **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](https://linux.die.net/man/5/sshd_config) option in -`sshd_config`. It does the following: +`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. +* 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. +* 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 user - for use by sshd. + for use by sshd. Otherwise, exits with an error code. -#### NSS Module +#### NSS Modules -The `nss_oslogin` module is built and installed in the appropriate `lib` -directory as a shared object with the name `libnss_oslogin.so.2`. The module is -then activated by an `oslogin` entry in `/etc/nsswitch.conf`. The NSS module -supports looking up `passwd` entries from the metadata server via -`getent passwd`. +`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: ``` @@ -78,47 +75,59 @@ supports looking up `passwd` entries from the metadata server via ``` * To look up a user by username, the NSS module queries: ``` - http://metadata.google.internal/computeMetadata/v1/oslogin/users?username=<username + 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 Module +#### PAM Modules -The `pam_module` directory contains two modules used by Linux PAM (Pluggable -Authentication Modules). +`pam_oslogin_login.so` is a PAM module which determines whether a given user is +allowed to SSH into an instance. -The first module, `pam_oslogin_login.so`, determines whether a given user is -allowed to SSH into an instance. It is activated by adding an -`account requisite` line to the PAM sshd config file and does the following: +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 + ``` -* Retrieves the user's profile information from the metadata server. +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 has OS Login profile information (as opposed to a local user - account), confirms whether the user has permissions to SSH into the - instance. +* 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=<user_email>&policy=login ``` -* If the user is a local user account or is authorized, PAM returns a success - message and SSH can proceed. Otherwise, PAM returns a denied message and the - SSH check will fail. +* 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. -The second module, `pam_oslogin_admin.so`, determines whether a given user -should have admin (sudo) permissions on the instance. It is activated by adding -an `account optional` line to the PAM sshd config file and does the following: +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=<username> ``` -* If the user is a local user account, the module exits with success. -* If the user is an OS Login user, the module perform an authorization check - to determine if the user has admin permissions. +* 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=<user_email>&policy=adminLogin ``` @@ -127,49 +136,40 @@ an `account optional` line to the PAM sshd config file and does the following: * If the authorization check fails for admin permissions, the file is removed from `/var/google-sudoers.d/` if it exists. -#### Utils - -`oslogin_utils` contains common functions for making HTTP calls, -interacting with the metadata server, and for parsing JSON objects. +## Utilities -## Utility Directories +#### Control Script -#### bin - -The `bin` directory contains a shell script called `google_oslogin_control` that -activates or deactivates the OS Login features. It is called in the pre and post -install scripts in the `.deb` and `.rpm` packages. The control file performs the -following tasks: +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` to (from) `nsswitch.conf`. +* 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. -#### packaging - -The `packaging` directory contains files for creating `.deb` and `.rpm` -packages. See [Source Packages](#source-packages) for details. +#### SELinux Policy -#### policy - -The `policy` directory contains `.te` (type enforcement) 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 `oslogin.pp` -that is intstalled in the appropriate SELinux directory. +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 8 + * 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 @@ -188,9 +188,7 @@ production quality._ 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 - appropriate `debian` directory into the top level. (e.g. When working on - Debian 8, copy the `debian8` directory to a directory named `debian` within - the code directory.) + `debian` directory into the top level. 1. To build the package, run the command ``` debuild -us -uc |