diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 85 |
1 files changed, 85 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..3379199 --- /dev/null +++ b/README.md @@ -0,0 +1,85 @@ +# ansible-googleauth + + + +This role is to install google authenticator and integrate it into ssh so that TOTP tokens may be required for ssh connections. + +It will create a `~/.google_authenticator` if required, and will NOT alter or remove any existing version. + +It will update `/etc/ssh/sshd_config.d` to ensure that a token is required for any ssh connection without an ssh key. Connections _with_ an ssh key will not require a token, though this may be enabled so that tokens are *always* required. Set the global **google_auth_force** variable to _true_ or an individual host entry (see below) to enable this. + +## Configuration + +To pre-populate the TOTP secret there are two locations to place the information. + +* Place them into `defaults/main.yml` under the **google_auth_config** variable +* *Much* more preferably place them into an ansible-vault encrypted file under the **vault_google_auth_config** variable. Typically this might be in `group_vars/all/vault` + +The format is as follows +| Variable | Description | +| :--- | :--- | +| name: | The inventory_hostname for this block | +| force_auth: | force token for ALL ssh connections for this host | +| secret: | Standard `.google_authenticator` secret info + +```yaml +# 1st line of secret can be 16 or 26 chars +vault_google_auth_config: + - name: host1.example.com + force_auth: false + secret: | + 6DRWZ2AWOAFAQMSI + "RATE_LIMIT 3 30 + " WINDOW_SIZE 3 + " DISALLOW_REUSE + " TOTP_AUTH + 36011504 + 52878834 + 36710801 + 23387673 + 16670568 + - name: hosty.somewhere.com + force_auth: false + secret: | + MVXECANUVTIQ2647HK3S35FM3A + " RATE_LIMIT 3 30 1734051365 + " DISALLOW_REUSE 57801712 + " TOTP_AUTH + 17029728 + 27355189 + 27432004 + 50794981 + 18624382 +``` + +NOTE: There must be at least 5x scratch codes for each secret + +## Manually generating a google authenticator secret + +For pre-populating the host secrets in the config, one can generate them via the command-line. For an Ubuntu system, ensure the following packages are installed : + +* libpam-google-authenticator +* python3-qrcode +* qrencode + +Generate an authenticator secret, placed in `/tmp/google.txt` + +```bash +google-authenticator --time-based --disallow-reuse --label=Test1 --qr-mode=UTF8 --rate-limit=3 --rate-time=30 --secret=/tmp/google.txt --window-size=3 --force +``` + +The contents of the resulting `/tmp/google.txt` may be placed directly into the `vault_google_auth_config` variable for a specific host. + +## Methods of installation + +There are several methods of creating the `~/.google_authenticator` file + +* Existing `~/.google_authenticator`, no pre-config + Any existing configuration will not be touched +* Existing `~/.google_authenticator`, pre-config in **vault_google_auth_config** + Any existing configuration will not be touched. You must manually remove any existing `~/.google_authenticator` +* No existing `~/.google_authenticator`, no pre-config + In this case a new secret key and scratch codes will be created +* No existing`~/.google_authenticator`, pre-config in **vault_google_auth_config** + If an entry in **vault_google_auth_config** exists it will be used, otherwise a new secret key will be created + |