added authentication documentation #171

README.md

@@ -415,10 +415,10 @@ For a secure experience using LaMachine, take all of the following into account:
   as a convenience but carries some inherent risks and is generally not a secure practice. It implies a trust relation
   between you and us, as well as the hoster (github). Prudent users are encouraged to download the script,
   inspect it, and only then execute it. We may provide PGP-signed releases in the future.
-* The bootstrap script asks for and requires root privileges for certain installation steps, this will always be asked and the user may confirm. The Ansible provisioning scripts also generally required a sudo, this will only be asked once, but the privileges will only be used when needed.
+* The bootstrap script asks for and requires root privileges for certain installation steps, this will always be asked and the user may confirm. The Ansible provisioning scripts also generally requires sudo, this will only be asked once per run, and the privileges will only be used when needed.
 * Running either the bootstrap procedure or the subsequent ansible provisioning entirely as root is forbidden for
   security reasons.
-* The current webserver configuration does not yet enable authentication for any of the webservices, so do *NOT* expose it directly to the internet without setting up authentication yourself.
+* The current webserver configuration does not yet enable authentication for any of the webservices, so do *NOT* expose it directly to the internet without setting up authentication yourself. If you want authentication, consult the OpenID Connect section below.
 * If you are sure you don't need a webserver/webservices, disable it in the configuration upon first build.
 * The virtual machines tend to come with a preset username and password ``(vagrant:vagrant)``, the lamachine user in Docker containers has
   the password ``lamachine``, you will need to change this.
@@ -428,6 +428,14 @@ For a secure experience using LaMachine, take all of the following into account:
 * Only if your setup is otherwise secure (i.e. authentication on webservices), then make sure to always open only the necessary ports (80/443) to the internet, do not expose any of the UWSGI services to the world (this would allow arbitrary code execution).
 * As per the GNU General Public Licence, we do not offer any warranty despite doing our best.
 
+### OpenID Connect Authentication
+
+LaMachine supports OpenID Connect, which is an extension on top of OAuth2, as a means to authenticate against an
+*external* single-sign-on authentication provider. You can configure OpenID Connect in the LaMachine configuration and LaMachine will
+attempt to propagate these parameters to all underlying software that supports OpenID Connect.
+
+Please consult the [LaMachine as a service documentation](docs/service/README.md) for further instructions.
+
 ## Versioning
 
 LaMachine comes in three versions, *stable* installs the latest stable releases of all software, *development* installs

docs/kubernetes/Dockerfile

@@ -2,10 +2,21 @@ FROM proycon/lamachine:core
 MAINTAINER Maarten van Gompel <[email protected]>:
 LABEL description="A LaMachine Docker container template"
 RUN lamachine-config lm_base_url https://your.domain &&\
+RUN lamachine-config hostname your.domain &&\
     lamachine-config force_https yes &&\
     lamachine-config maintainer_name "Your name here" &&\
     lamachine-config maintainer_mail "[email protected]" &&\
-    lamachine-passwd -p some_secret_password lab flat &&\
+    #--- OpenID Connect Configuration ---:
+    lamachine-config oauth_client_id "<your client id here>" &&\
+    lamachine-config oauth_client_secret "<your client secret here>" &&\
+    lamachine-config oauth_auth_url "https://authentication.clariah.nl/Saml2/OIDC/authorization" &&\
+    lamachine-config oauth_token_url "https://authentication.clariah.nl/OIDC/token" &&\
+    lamachine-config oauth_userinfo_url "https://authentication.clariah.nl/OIDC/userinfo" &&\
+    lamachine-config oauth_scope '[ "openid", "email" ]' &&\
+    lamachine-config oauth_sign_algo "RS256" &&\
+    #lamachine-config oauth_jwks_url "https://authentication.clariah.nl/OIDC/jwks" &&\
+    lamachine-config oauth_sign_key '{ "kty": "RSA", "use": "sig", "alg": "RS256", "n": "64Aqjpp25auuL0Sh5vYc0RrqQ_kpLqfcjo6gpzIE_GI3xiJrxygvXvKgADXgRN03PEQFAIDDH-C_STgYXcOPFvrC6Hh48Cd0t21ScLemfx_PJzHPKj94nislYhlMN5v9X_Ol3lKL1uab6UrbPXPyudKiniviiq03H9eJMXeekoD_W-dT8MNxSb9Aj3sjJ0KWHIW6oFcChSaG-EnWrsvi_DO0cpasgtuB6BiR3HMm4CUdj2SM8jq2oLfpT8yWN4KsjYmMBAXQW8xh3fDwzq5DJ789cSwdPYX1Yp-LMxAq1TJM0oJhtrq81h9YFyue6ILvyGvrDALL50T1OxKXNTsEaQ", "e": "AQAB" }' &&\
+    #--- Packages to install ---:
     lamachine-add languagemachines-basic languagemachines-python labirinto jupyter
 RUN lamachine-update
 ENTRYPOINT [ "/usr/local/bin/lamachine-start-webserver", "-f" ]

docs/service/README.md

@@ -0,0 +1,91 @@
+# LaMachine as a service
+
+A default LaMachine installation offers a single-user environment with little
+to no authentication for most services. The services it exposes should
+therefore not to be exposed to the public internet.
+
+LaMachine does have all the facilities for a proper multi-user environment, and
+this is what you will want in a proper production environment where you aim to
+offer it as a service. In that case you will need to set up authentication as
+described in this document.
+
+## Encryption Handling and Reverse proxy
+
+LaMachine serves traffic over HTTP by default, this is not secure for
+production environments. In production scenarios, you need your own
+reverse proxy server that handles HTTPS and forwards the traffic to the HTTP
+server in LaMachine.
+
+HTTPS is a prerequisite for authentication. We also assume you have a dedicated
+domain/subdomain for your LaMachine installation.
+
+You will need to configure the URL and hostname in your LaMachine instance as follows. You can edit your configuration
+interactively through ``lamachine-config --edit``:
+
+```yaml
+lm_base_url: https://your.domain
+hostname: your.domain
+force_https: yes
+```
+
+The ``force_https`` setting is crucial to ensure LaMachine knows the reverse proxy handles the encryption.
+
+## OpenID Connect
+
+LaMachine supports OpenID Connect, an extension on top of OAuth2, as a means to authenticate against an *external*
+single-sign-on authentication provider. LaMachine itself does not offer any integrated authentication provider (although
+some the software in it may).
+
+You can configure OpenID Connect in the LaMachine configuration and
+LaMachine will propagate these parameters to all underlying services
+that support OpenID Connect.
+
+Below is an example configuration for authentication against CLARIAH's authentication server.
+
+```yaml
+#shared oauth2 client ID
+oauth_client_id: "<your client id here>"
+
+#shared oauth2 client secret (always keep this private)
+oauth_client_secret: "<your client secret here>"
+
+oauth_auth_url: "https://authentication.clariah.nl/Saml2/OIDC/authorization"
+oauth_token_url: "https://authentication.clariah.nl/OIDC/token"
+oauth_userinfo_url: "https://authentication.clariah.nl/OIDC/userinfo"
+
+#Scope for OpenID Connect
+oauth_scope: [ "openid", "email" ]
+
+#Key signing algorithm for OpenID Connect, can be RS256 or HS256
+oauth_sign_algo: "RS256"
+
+#used by OpenID Connect to obtain a signing key automatically (usually in combination with RS256 algorithm)
+#oauth_jwks_url "https://authentication.clariah.nl/OIDC/jwks"
+
+#Or... specify the key manually:
+oauth_sign_key: { "kty": "RSA", "use": "sig", "alg": "RS256", "n": "64Aqjpp25auuL0Sh5vYc0RrqQ_kpLqfcjo6gpzIE_GI3xiJrxygvXvKgADXgRN03PEQFAIDDH-C_STgYXcOPFvrC6Hh48Cd0t21ScLemfx_PJzHPKj94nislYhlMN5v9X_Ol3lKL1uab6UrbPXPyudKiniviiq03H9eJMXeekoD_W-dT8MNxSb9Aj3sjJ0KWHIW6oFcChSaG-EnWrsvi_DO0cpasgtuB6BiR3HMm4CUdj2SM8jq2oLfpT8yWN4KsjYmMBAXQW8xh3fDwzq5DJ789cSwdPYX1Yp-LMxAq1TJM0oJhtrq81h9YFyue6ILvyGvrDALL50T1OxKXNTsEaQ", "e": "AQAB" }
+```
+
+You will need to register a client ID and client secret with your authentication provider. You will also need to
+register so-called redirect/callback URLs.  All services within a LaMachine installation will share the same ID/Secret,
+so it is important that your OpenID Connect provider supports multiple redirect URLs. For LaMachine, the URLs to
+register depend a bit on what services you have installed in LaMachine. The following lists the most prominent ones but
+is not necessarily exhaustive:
+
+```
+https://your.domain/frog/login
+https://your.domain/ucto/login
+https://your.domain/alpino/login
+https://your.domain/piccl/login
+https://your.domain/spacy/login
+https://your.domain/colibricore/login
+https://your.domain/piereling/login
+https://your.domain/flat/oidc/callback/
+```
+
+
+
+
+
+
+