Merge 48322fc into 2285708

docs/docker/README.md

@@ -69,6 +69,18 @@ $ sudo sed -i 's% shared_data_directory:.*% shared_data_directory: "/usr/share/k
  ${KEYMASTER_DATA}/conf/config.yml
 ```
 
+## Configure Auth backend
+
+Edit ${KEYMASTER_DATA}/conf/config.yml and set up your Auth Backend. Visit
+[here](https://github.com/Cloud-Foundations/keymaster#supported-backend-authentication-methods)
+for more info.
+
+**NOTE**: "U2F", "TOTP" and "SymantecVIP" still need passwords in either LDAP or
+the passfile. For the webui you can also add "federated" and configure oauth2
+against another provider. Be sure to use an internal oauth token if using a big
+provider like Google for Auth because username@mydomain.com will register the same
+as username@gmail.com.
+
 ## Start
 
 After bootstrapping configs and keys you just start the container. This will
@@ -102,17 +114,6 @@ $ docker exec -it keymaster /usr/bin/htpasswd -B -c \
  /etc/keymaster/passfile.htpass $USERNAME
 ```
 
-## Add users
-
-By default a user is created. Let's start by deleting this and creating our own
-user.
-
-```
-$ rm -f ${KEYMASTER_DATA}/conf/passfile.htpass
-$ docker exec -it keymaster /usr/bin/htpasswd -B -c \
- /etc/keymaster/passfile.htpass $USERNAME
-```
-
 ## SSH
 
 Distribute the SSH CA to hosts

docs/examples/gitdb.md

@@ -0,0 +1,14 @@
+# gitdb
+
+A database for user and group information using Git as the back-end.
+
+The database is read from `groups.json` files in directories in the repository.
+All the groups files are merged together; the directory structure is not
+relevant to how the repository is processed. This allows for arbitrary directory
+structures to reflect the organisation. Each directory must have the following
+files:
+- `groups.json`: containing group definitions and their memberships
+- `permitted-groups.json`: containing a list of regular expressions for the
+                           permitted groups in the `groups.json` file
+
+See examples and testdata [here](https://github.com/Cloud-Foundations/golib/tree/master/pkg/auth/userinfo/gitdb)

docs/examples/ldap.md

@@ -0,0 +1,34 @@
+# LDAP
+
+If you use LDAP as your authoritative source of users, you can have keymaster
+use this for both password and userinfo.
+
+## Keymaster config.yml
+
+1. Enable LDAP for user authentication
+
+```
+ldap:
+  bind_pattern: "cn=%s,ou=People,dc=example,dc=com"
+  ldap_target_urls: "ldaps://ldaps.example.com:636"
+  disable_password_cache: false
+```
+
+2. Configure LDAP userinfo_sources
+
+```
+  ldap:
+    bind_username: "cn=keymaster,ou=serviceacct,dc=example,dc=com"
+    bind_password: "MyBindPw"
+    group_prepend: ""
+    ldap_target_urls: "ldaps://ldaps.example.com:636"
+    user_search_base_dns: ["dc=example,dc=com"]
+    user_search_filter: "(&(objectClass=posixAccount)(uid=%s))"
+    group_search_base_dns: ["dc=example,dc=com"]
+    group_search_filter: "(&(objectClass=posixGroup)(memberUid=%s))"
+```
+
+Set a group_prepend item, such as ```ldap-``` if you utilize both gitdb and LDAP
+
+**WARNING** Keymaster only supports ldaps and will not allow unencrypted LDAP
+requests.

docs/examples/oauth2.md

@@ -0,0 +1,58 @@
+# Oauth2
+
+**Warning: For this flow, the part before the @ in the e-mail address is
+considered the login. Be sure to limit who can oauth2 in by using internal
+or private tokens. For example myuser@example.com is the same as
+myuser@gmail.com if I choose Google as my oauth2 provider.**
+
+If you have an external source of truth for users that also provides an oauth2
+endpoint, you can allow your users to login and register their second factor.
+
+## Keymaster config.yml
+
+1. Enable oauth2 in the web flow via keymaster
+
+```
+-  allowed_auth_backends_for_webui: [ "TOTP", "U2F" ]
++  allowed_auth_backends_for_webui: [ "federated", "TOTP", "U2F" ]
+```
+
+1. a - **OPTIONAL** Enable TOTP registration
+
+```
+-  enable_local_totp: false
++  enable_local_totp: true
+```
+
+1. b - **OPTIONAL** Disable non oauth2 login for web flow
+
+```
+-  hide_standard_login: false
++  hide_standard_login: true
+```
+
+```
+-  allowed_auth_backends_for_webui: [ "TOTP", "U2F" ]
++  allowed_auth_backends_for_webui: [ "federated" ]
+```
+
+2. Enable oauth2. This example uses Google, but you may need to visit
+https://endpoint/.well-known/openid-configuration for the correct entries.
+
+**NOTE**: During registration for your oauth2 token, you will be asked for an
+allowed redirect URL. That should be:
+**https://keymaster.example.com/auth/oauth2/callback**
+
+[Example](https://accounts.google.com/.well-known/openid-configuration)
+
+```
+oauth2:
+  config: null
+  enabled: true
+  client_id: "random-text.apps.googleusercontent.com"
+  client_secret: "My-Secret-Id"
+  token_url: "https://oauth2.googleapis.com/token"
+  auth_url: "https://accounts.google.com/o/oauth2/v2/auth"
+  userinfo_url: "https://openidconnect.googleapis.com/v1/userinfo"
+  scopes: "openid profile email"
+```

docs/examples/zerotrust/huproxy.md

@@ -0,0 +1,151 @@
+# HUProxy
+
+## What is HUProxy
+
+[HTTP(S)-Upgrade Proxy](https://github.com/google/huproxy) — Tunnel anything
+(but primarily SSH) over HTTP websockets.
+
+This example uses Ubuntu 20.04 as a base.
+
+## HUProxy Config
+
+1. On a build machine with go installed run 
+```CGO_ENABLED=0 go get github.com/google/huproxy```. Copy that binary to your
+target in ```/usr/local/bin```
+
+2. Create a system user named huproxy place
+```/etc/systemd/system/huproxy.service``` with the following contents.
+
+```
+[Unit]
+Description=Simple ssh proxy
+After=network.target
+
+[Service]
+Type=simple
+User=huproxy
+Group=huproxy
+WorkingDirectory=/tmp
+ExecStart=/usr/local/bin/huproxy -listen [::1]:8086
+Restart=on-failure
+PrivateTmp=true
+
+[Install]
+WantedBy=default.target
+```
+
+3. Run ```systemctl daemon-reload && systemctl enable --now huproxy```.
+
+## Apache Config
+
+1. Install Apache and stop it
+
+```
+$ sudo apt update && sudo apt -y install apache2 && systemctl stop apache2
+```
+
+2. Remove existing configuration
+
+```
+$ sudo rm -rf /etc/apache2/mods-enabled/* /etc/apache2/sites-enabled/*
+```
+
+3. Enable required modules
+
+```
+$ sudo a2enmod mpm_event proxy_wstunnel ssl rewrite access_compat authz_core
+
+```
+
+4. Obtain the Keymaster CA file
+
+```
+$ sudo curl -Lo /etc/apache2/keymaster-ca.pem https://keymaster.example.com/public
+/x509ca
+```
+
+5. Place this in ```/etc/apache2/sites-available/zerotrust.conf```. Be sure to
+swap in your personal SSL certificates.
+
+```
+<VirtualHost *:80>
+        ServerName sshproxy.example.com
+        ServerAdmin webmaster@localhost
+        DocumentRoot /var/www/html
+        RewriteEngine On
+        RewriteCond %{REQUEST_URI} !^/.well-known/acme-challenge [NC]
+        RewriteCond %{HTTPS} !=on
+        RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R=301,L]
+        ErrorLog ${APACHE_LOG_DIR}/error.log
+        CustomLog ${APACHE_LOG_DIR}/access.log combined
+</VirtualHost>
+<IfModule mod_ssl.c>
+        <VirtualHost _default_:443>
+                Protocols http/1.1
+                ServerName sshproxy.example.com
+                ServerAdmin webmaster@localhost
+                DocumentRoot /var/www/html
+                ErrorLog ${APACHE_LOG_DIR}/error.log
+                CustomLog ${APACHE_LOG_DIR}/access.log combined
+                SSLEngine on
+                SSLProtocol -all +TLSv1.3 +TLSv1.2
+                SSLHonorCipherOrder off
+                SSLSessionTickets off
+                SSLCipherSuite "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384"
+                SSLCertificateFile     /etc/ssl/certs/ssl-cert-snakeoil.pem
+                SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
+
+                SSLCACertificateFile /etc/apache2/keymaster-ca.pem
+                SSLUserName SSL_CLIENT_S_DN_CN
+                SSLVerifyClient require
+
+                ProxyRequests Off
+                ProxyPass "/proxy/" "ws://[::1]:8086/proxy/"
+
+                # Default Deny
+                <LocationMatch "^/proxy/">
+                        Order Allow,Deny
+                        Deny from all
+                </LocationMatch>
+
+                # Example with group limit. You can even use ldap groups.
+                #<LocationMatch "^/proxy/adminbastion.internal.example.com/22">
+                #       Allow from all
+                #       AuthGroupFile /etc/apache2/groups
+                #       Require group admin
+                #</LocationMatch>
+
+                # Allow TCP port 22
+                <LocationMatch "^/proxy/[^/]+/22$">
+                        Allow from all
+                </LocationMatch>
+
+        </VirtualHost>
+</IfModule>
+
+# vim: syntax=apache ts=4 sw=4 sts=4 sr noet
+```
+
+**Do not enable http2 until this [issue](https://github.com/gorilla/websocket/issues/417) is resolved.**
+
+6. Enable zerotrust.conf and start Apache
+
+```
+$ sudo a2ensite zerotrust && sudo systemctl start apache2
+```
+
+## SSH Config
+
+1. On a build machine with go installed run 
+```CGO_ENABLED=0 go get github.com/google/huproxy/huproxyclient```. Copy that binary to your
+target in ```/usr/local/bin```
+
+2. Place your config in ```/etc/ssh/ssh_config``` or in individual users ```~/.ssh/config```.
+
+```
+Host *.internal.example.com
+    ProxyCommand /usr/local/bin/huproxyclient -key ~/.ssl/keymaster.key -cert ~/.ssl/keymaster.cert wss://sshproxy.example.com/%h/%p  
+```
+
+## Congrats
+You can now ssh to internal servers without a VPN.

docs/examples/zerotrust/pomerium.md

@@ -0,0 +1,75 @@
+# Pomerium
+
+## What is Pomerium
+
+[Pomerium](https://pomerium.com/) is an identity-aware proxy that enables secure
+access to internal applications. Pomerium provides a standardized interface to
+add access control to applications regardless of whether the application itself
+has authorization or authentication baked-in. Pomerium gateways both internal
+and external requests, and can be used in situations where you'd typically reach
+for a VPN.
+
+## Keymaster Config
+
+```
+openid_connect_idp:
+  default_email_domain: "example.com"
+  clients:
+    - client_id: "pomerium"
+      client_secret: "Pre-Shared-Key"
+      allowed_redirect_domains:
+        - "pomerium.example.com"
+```
+
+## Pomerium Config
+
+Configure certificates and DNS as you would normally. You can get your own
+certificates, use certbot to obtain wildcards or enable autocert. Once you have
+that figured out, the configurations below are a reasonable template to follow.
+
+```
+authenticate_service_url: https://pomerium.example.com
+signout_redirect_url: https://keymaster.example.com/api/v0/logout
+
+idp_provider: oidc
+idp_provider_url: https://keymaster.example.com
+idp_client_id: pomerium
+idp_client_secret: Pre-Shared-Key
+
+cookie_expire: 16h
+cookie_domain: pomerium.example.com
+cookie_secret: (EXECUTE head -c32 /dev/urandom | base64)
+
+policy:
+  - from: https://site1.pomerium.example.com
+    to: https://site1.internal.example.com:4422
+    allow_websockets: false
+    preserve_host_header: true
+    tls_skip_verify: false
+    allowed_idp_claims:
+      groups:
+        - marketing
+        - product
+
+  - from: https://site2.pomerium.example.com
+    to: https://site2.internal.example.com:443
+    allow_websockets: true
+    preserve_host_header: false
+    tls_skip_verify: true
+    allowed_users:
+      - user1@example.com
+      - user2@example.com
+
+  - from: https://site3.pomerium.example.com
+    to: https://site3.internal.example.com:4422
+    allow_websockets: true
+    preserve_host_header: true
+    tls_skip_verify: false
+    allowed_domains:
+      - example.com
+```
+
+## Congrats
+You can now access internal websites without a VPN. Further reading is available
+at the Pomerium [guides](https://www.pomerium.com/guides/) and
+[references](https://www.pomerium.com/reference/) pages.