diff --git a/docs/apache-oauth2.md b/docs/apache-oauth2.md index 58ef8ac0c78f2848b3e8f4306636376272f2e33c..411e42b16c6b1ae30aba9b6428e6361dbd17b9ff 100644 --- a/docs/apache-oauth2.md +++ b/docs/apache-oauth2.md @@ -19,8 +19,10 @@ that the [mod_auth_openidc](https://github.com/zmartzone/mod_auth_openidc/) is Apache module is installed on your server. If you are running a Debian or Ubuntu server this is provided by the [libapache2-mod-auth-openidc](https://packages.debian.org/sid/web/libapache2-mod-auth-openidc) -package which can be installed via `apt-get`. In this guide we will make use of -a pre-built Docker container based on Ubuntu. +package which can be installed via `apt-get`. Other Linux distributions will require +an alternative install command, such as `yum install mod_auth_openidc`. + +In this guide we will make use of a pre-built Docker container based on Ubuntu. ## Fetching and building the container image @@ -114,7 +116,7 @@ a2enmod auth_openidc ### Configuring mod_auth_openidc The Apache web server supports serving multiple websites from the same server. -Each website is usually configured with a `#!apache <VirtualServer>` section +Each website is usually configured with a `#!apache <VirtualHost>` section in the Apache configuration file. The configuration for our protected site can be found within the @@ -196,9 +198,12 @@ OIDCCryptoPassphrase "e3b0c44298fc1c149996fb92427ae41e4649b934ca495991b7852b855" the passphrase. Try it yourself in the Play with Docker terminal: ```bash - dd if=/dev/urandom of=- count=100 2>/dev/null | sha256sum - | cut -f1 -d ' ' + dd if=/dev/urandom of=/dev/stdout count=100 2>/dev/null | sha256sum - | cut -f1 -d ' ' ``` + In production, you should make use of whatever secure token generation + system you currently use. + #### Token request parameters The OAuth2 standard allows for websites to make special requests about sign @@ -260,12 +265,12 @@ Configuring mod_auth_openidc does not actually cause the website to be Raven enabled. You must explicitly specify locations within a site which require sign in. To protect the entire site you can use the following `#!apache <Location>` section which should be within the appropriate `#!apache -<VirtualServer>` section: +<VirtualHost>` section: ```apache # Protect entire site with Raven authentication. <Location /> - # Use OIDC authentication. + # Use OIDC authentication - ESSENTIAL FOR RAVEN WORKFLOW AuthType openid-connect <RequireAll> @@ -281,6 +286,7 @@ sign in. To protect the entire site you can use the following `#!apache </Location> ``` + !!! important "Always check the `hd` claim" Great sites follow the [Raven "golden rules"](golden-rules.md). Although you can set the `hd` request parameter via `#!apache OIDCAuthRequestParams`, a @@ -292,7 +298,7 @@ sign in. To protect the entire site you can use the following `#!apache ## Next steps On this page you learned how to build and customise the example Apache -container. You saw all the mod_auth_openidc configration directives required to +container. You saw all the mod_auth_openidc configuration directives required to configure Raven sign in and you saw how to require sign in for an entire web site.