1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
## 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=<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 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=<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 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=<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=<user_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=<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=<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 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
```
|
