FAQ | This is a LIVE service | Changelog

Commit 770a7169 authored by Dr Rich Wareham's avatar Dr Rich Wareham
Browse files

add first draft of public Raven documentation

This is a first draft of the public Raven documentation encompassing
Raven OAuth2 and Raven SAML 2.0.
parent c5919b61
root=true
[*.{html,js,md}]
[*.{html,js,css,md}]
indent_size=2
indent_style=space
......
......@@ -7,14 +7,14 @@ This repository contains the source for the Raven public documentation.
The guidebook uses mkdocs to convert Markdown source into a static website.
Install mkdocs using pip:
```console
$ pip3 install --user -r requirements.txt
```bash
pip3 install --user -r requirements.txt
```
You can then serve a site locally for development via ``mkdocs``:
```console
$ mkdocs serve
```bash
mkdocs serve
```
The documentation is now available at http://localhost:8000/.
......
title: Apache and Raven OAuth2
# Configuring the Apache web server for Raven OAuth2
This page follows on from the [first steps page](./first-steps.md) and peeks
behind the scenes a bit about how our example web server is configured. By
doing so you will learn how to configure the [Apache web
server](https://httpd.apache.org/) to require Raven authentication when
visiting a site.
## Prerequisites
This guide is written assuming you have completed the [first steps
guide](./first-steps.md), that you have had some experience with the Linux
command line and have configured an Apache web server before.
In order to add Raven authentication to a website you will need to make sure
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.
## Fetching and building the container image
We will be making use of Play with Docker as we did on the [first steps
page](./first-steps.md). If you haven't done so already make sure now that:
1. You have created a Play with Docker instance.
2. You have set the `CLIENT_ID` and `CLIENT_SECRET` environment variables to out
OAuth2 [client credentials](creating-oauth2-client-credentials.md).
Previously we made use of a pre-built container to demonstrate Raven
integration. Now we will build our own.
Use the `git` command line tool to fetch the Raven documentation samples and
move into the `apache-oauth2` directory:
```bash
git clone https://gitlab.developers.cam.ac.uk/uis/devops/raven/doc-samples.git
cd doc-samples/apache-oauth2
```
Build a new container image called `my-server`:
```bash
docker build -t my-server .
```
Run the web-server just as you did on the [first steps page](./first-steps.md)
except using your new image name:
```bash
docker run --rm -it -e CLIENT_ID -e CLIENT_SECRET -p 8000:80 my-server
```
!!! important
Make sure you have set the `CLIENT_ID` and `CLIENT_SECRET` environment
variables.
## Experiment with the container
Since you are now building the container yourself, you can experiment with
changing how it is configured.
1. Press Ctrl-C in the Play with Docker window to stop the web server.
2. Click the **editor** button and navigate to
`/root/doc-samples/apache-oauth2/htdocs`.
3. Click on **index.shtml** to edit the code of the example web page.
4. Change the word "Congratulations" to "Well done".
5. The Play with Docker editor changes the permissions on files it edits so,
back in the Play with Docker terminal window, use the following command to
restore
them:
```bash
chmod -R oug+r htdocs/
```
Try re-building and re-running the web server:
```bash
docker build -t my-server .
docker run --rm -it -e CLIENT_ID -e CLIENT_SECRET -p 8000:80 my-server
```
If you visit your page again, you should see the welcome message has changed.
## A tour of the container
Now you are familiar with how to modify the container configuration, you can
experiment with the container setup to gain some familiarity with it. Don't
worry if you've never used docker before. We'll now go on a tour of how the
container works its magic.
### Installing mod_auth_openidc
The
[Dockerfile](https://gitlab.developers.cam.ac.uk/uis/devops/raven/doc-samples/blob/master/apache-oauth2/Dockerfile)
describes the steps to set up the container. We start from a base Ubuntu
install. We run a number of basic system configuration commands but the main
commands which install and configure mod_auth_openidc are as follows:
```bash
apt-get install apache2 libapache2-mod-auth-openidc
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
in the Apache configuration file.
The configuration for our protected site can be found within the
[sites/protected.conf](https://gitlab.developers.cam.ac.uk/uis/devops/raven/doc-samples/blob/master/apache-oauth2/sites/protected.conf)
file. The mod_auth_openidc module is configured using directives which start
`OIDC...`.
#### OpenID connect metadata URL
The OpenID Connect specification describes a way to auto-configure a number of
the OAuth2 parameters for a particular authentication server. We can use the
`#!apache OIDCProviderMetadataURL` directive to specify the appropriate metadata
configuration URL for Raven:
```apache
# Raven OAuth2 is provided by Google. This URL provides metadata which
# auto-configures some OAuth2 parameters.
OIDCProviderMetadataURL \
https://accounts.google.com/.well-known/openid-configuration
```
#### OAuth2 client credentials
The `#!apache OIDCClientID` and `#!apache OIDCClientSecret` directives let you
specify the OAuth2 client credentials for your site. In our container we load
them from the `CLIENT_ID` and `CLIENT_SECRET` environment variables but you can
specify them directly in your configuration if you wish:
```apache
# OAuth2 client application.
OIDCClientID "some-client-id"
OIDCClientSecret "some-client-secret"
```
#### Redirect URI
When a website wants to cause a user to sign in, it redirects them to Raven.
Raven, in turn, needs to know where to redirect the user back to after they have
authenticated. This is a special URL on your site known as the "redirect URI".
It doesn't matter what you choose as a redirect URI as long as it doesn't
conflict with any other URL on your website. A good choice is
`/.oidc/redirect`.
Our example container allows the redirect URI to be customised with an
environment variable but you can specify it directly in the configuration if you
wish:
```apache
# Redirect URI claimed by mod_auth_openidc. This should not be any URL used by
# the site you're protecting. A good choice is usually something like
# "/.oidc/redirect".
OIDCRedirectURI "/.oidc/redirect"
```
#### Session cookie passphrase
It would be tiresome in the extreme if each time a visitor to your site
navigated around it they were prompted for their Raven credentials. To prevent
this `mod_auth_openidc` keeps a special value in a "session cookie" which a
user's web browser presents to the web server on each visit to identify them. To
make sure that this cookie can't be faked, it is encrypted with a secret value
you configure in the web server.
This value should ideally be a long random string. The container generates a
different passphrase each time it is run but in production you should use a
fixed value and add it to the Apache configuration using the `#!apache
OIDCCryptoPassphrase` directive:
```apache
# Crypto passphrase for session cookie. This is used to encrypt a session
# cookie which allows users to re-visit your site once signed in without
# having to present their Raven credentials again.
OIDCCryptoPassphrase "e3b0c44298fc1c149996fb92427ae41e4649b934ca495991b7852b855"
```
!!! info
The container uses a little bit of Unix command line trickery to generate
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 ' '
```
#### Token request parameters
The OAuth2 standard allows for websites to make special requests about sign
ins. For example they could request that a user always be asked for their
password even if they have signed in before. Raven OAuth2 uses the `hd`
parameter to signal that a website only wants users with `@cam.ac.uk` email
addresses. The parameters are set via the `#!apache OIDCAuthRequestParams`
directive:
```apache
# OAuth2 token request parameters. Use "hd=cam.ac.uk" to request the Raven
# login box.
OIDCAuthRequestParams "hd=cam.ac.uk"
```
If you don't set the `hd` parameter you will get a generic Google login box.
This may be what you want if you want offer sign in to both the public and Raven
account holders.
#### OAuth2 scopes
In the OAuth2 protocol, "scope" refers to the set of things a server wants to be
able to do on behalf of a user. To get the `@cam.ac.uk` email address for the
user in you only need the "email" scope. To get other basic information on a
user such as name and profile picture you need the "openid" and "profile"
scopes. Generally it is best to specify all three. Do this via the `#!apache
OIDCScope` directive:
```apache
# Scopes indicating the information we want back from Raven.
OIDCScope "openid email profile"
```
#### Remote user
Apache supports the concept of a "remote user" which some applications use to
automatically create user accounts when a user signs in. If your application
makes use of this feature, you can configure mod_auth_openidc to use the user's
email address as their username via the `#!apache OIDCRemoteUserClaim`
directive:
```apache
# Some sites look at the "remote user" setting in Apache to determine the
# username which should be used. Set this to the user's "@cam.ac.uk" email
# address.
OIDCRemoteUserClaim email
```
!!! tip
It is possible to perform some regular expression trickery with `#!apache
OIDCRemoteUserClaim` to strip the domain-name part of the email address off.
This is not recommended since, as described in the [Raven "golden
rules"](golden-rules.md), it reduces your ability to allows users without
CRSids to use your site.
### Requiring sign in
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:
```apache
# Protect entire site with Raven authentication.
<Location />
# Use OIDC authentication.
AuthType openid-connect
<RequireAll>
# Require that authentication succeeded.
Require valid-user
# Require that the user be a Raven user.
#
# THIS CHECK IS REQUIRED TO STOP ANYONE WITH A PUBLIC GOOGLE ACCOUNT
# FROM SIGNING IN TO YOUR SITE.
Require claim "hd:cam.ac.uk"
</RequireAll>
</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
clever user could modify the request in their browser and request sign in
for any public Google account. Unless you **check** the `hd` claim in the
response from Raven you are essentially letting anyone on the Web
access your site.
## 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
configure Raven sign in and you saw how to require sign in for an entire web
site.
Remember to read the [Raven golden rules](golden-rules.md) when configuring your
website.
The [complete list of configuration
directives](https://github.com/zmartzone/mod_auth_openidc/blob/master/auth_openidc.conf)
for mod_auth_openidc is available if you want to find out more.
title: Apache and Raven SAML 2.0
# Configuring the Apache web server for Raven SAML 2.0
This page follows on from the [first steps page](./first-steps.md) and covers
configuring the [Apache web server](https://httpd.apache.org/) to make use of
Raven SAML 2.0 and require Raven authentication when visiting a site.
## Prerequisites
This guide is written assuming you have completed the [first steps
guide](./first-steps.md), that you have had some experience with the Linux
command line and have configured an Apache web server before.
In order to add Raven authentication to a website you will need to make sure
that the [Shibboleth 3 Service Provider for
Apache](https://wiki.shibboleth.net/confluence/display/SP3/LinuxInstall) is
installed on your server. If you are running a Debian or Ubuntu server, the
[libapache2-mod-shib](https://packages.debian.org/sid/web/libapache2-mod-shib)
package provides this and can be installed via `apt-get`. In this guide we will
make use of a pre-built Docker container based on Ubuntu.
## Quick start
We will be making use of Play with Docker as we did on the [first steps
page](./first-steps.md). If you haven't already, sign in to Play with Docker and
create a new instance.
Much like Raven OAuth2 uses client ids to identify websites, Raven SAML 2.0
uses *entity ids*. These are publicly-visible textual descriptions of sites and
should be unique. Use your creativity to come up with one and set the
`ENTITY_ID` environment variable:
```bash
export ENTITY_ID="A very creative name"
```
We have created a Docker image with Apache pre-installed which uses the
[Shibboleth Service
Provider](https://wiki.shibboleth.net/confluence/display/SP3/LinuxInstall) to
interact with Raven SAML 2.0. We'll discuss the configuration later but for now
just start the server:
```bash
docker run --rm -it \
-e ENTITY_ID -v shib-keys:/etc/shibboleth/keys -p 8000:80 \
registry.gitlab.developers.cam.ac.uk/uis/devops/raven/doc-samples/apache-saml2
```
!!! info
To use Raven SAML 2.0, a website needs to create a "private key" which it
uses to sign all the requests and to decrypt responses from Raven SAML 2.0.
Our pre-made image will auto-generate this on first run. We use a *Docker
volume* called `shibboleth-keys` to store them. This makes sure that the
key is the same if the server is stopped and re-started.
A link to your new site should have appeared next to the **open port** button.
1. Right-click it the link next to **open port** and copy the URL.
2. Add `/Shibboleth.sso/Metadata` to the URL you copied. So, if the
URL you coped was http://abc.direct.labs.play-with-docker.com/, visit
http://abc.direct.labs.play-with-docker.com/Shibboleth.sso/Metadata in your
browser and save the metadata to a file.
3. Open the metadata in a text editor and copy the contents to your clipboard.
4. Visit https://metadata.raven.cam.ac.uk/, sign in and click **Register new
site**.
5. Provide a descriptive short name for the site, paste the metadata in to the
large box and add a contact email address.
6. Click **Submit**.
After around a minute, Raven SAML 2.0 will automatically register your metadata.
You should now be able to click the link next to **open port** and visit your
new site.
## What Raven SAML 2.0 tells you about users
Raven SAML 2.0 is intended both for University-managed websites and websites
managed by others. The level of detail Raven SAML 2.0 releases about users
differs between *internal* sites (those whose domain names end in `.cam.ac.uk`)
and *external* sites (everything else).
External sites are given basic information on users including an email address
formatted identifier of the form `[crsid]@cam.ac.uk`, an opaque persistent
identifier and some basic information about whether they are considered a
member of the University.
Internal sites are given a lot more information including a human-friendly name
for the user and a list of the [Lookup](https://www.lookup.cam.ac.uk/) groups
they are a member of.
!!! info
There is a separate page giving [the full list of all the attributes
released by Raven SAML 2.0](saml2-attributes.md).
## A tour of the container
[The source code for our SAML 2.0
container](https://gitlab.developers.cam.ac.uk/uis/devops/raven/doc-samples/tree/master/apache-saml2)
is publicly available and can be used as a guide to configuring your own Apache
web server to make use of Raven SAML 2.0. We'll go on a quick tour of the
container's contents visiting the most important files.
### Installing mod_shib
The
[Dockerfile](https://gitlab.developers.cam.ac.uk/uis/devops/raven/doc-samples/blob/master/apache-saml2/Dockerfile)
describes the steps to set up the container. We start from a base Ubuntu
install. We run a number of basic system configuration commands but the main
command which installs and configure mod_shib is:
```bash
apt-get install apache2 libapache2-mod-shib
```
### Shibboleth configuration
The Shibboleth software is configured through two files:
`/etc/shibboleth/attribute-map.xml` and `/etc/shibboleth2/shibboleth2.xml`.
Raven SAML 2.0 can pass information about the current user back to your web
site. These are called *attributes*. The
[attribute-map.xml](https://gitlab.developers.cam.ac.uk/uis/devops/raven/doc-samples/blob/master/apache-saml2/shib/attribute-map.xml)
file provided in the container tells the Shibboleth software how to map the
somewhat opaque numeric "OID-style" names into something a human can understand.
You will rarely need to modify this file.
The
[shibboleth2.xml](https://gitlab.developers.cam.ac.uk/uis/devops/raven/doc-samples/blob/master/apache-saml2/shib/shibboleth2.xml.template)
file configures the Shibboleth software. Our container arranges for strings of
the form `${...}` to be replaced with the configuration passed in via
environment variables. In your own deployments you should set these values
directly in the file.
### Configuring mod_shib
The Apache web server supports serving multiple websites from the same server.
Each website is usually configured with a `#!apache <VirtualServer>` section
in the Apache configuration file.
The configuration for our protected site can be found within the
[sites/protected.conf](https://gitlab.developers.cam.ac.uk/uis/devops/raven/doc-samples/blob/master/apache-saml2/sites/protected.conf)
file. The mod_shib module is configured using directives which start
`Shib...`.
Shibboleth requires that a region of the web-site be set aside for its use. In
our configuration we have set this to be any URL of the form
`/Shibboleth.sso/...` by means of a custom `#!apache <Location>` section:
```apache
# The "/Shibboleth.sso" location is "special" and is handled by the
# Shibboleth module.
<Location /Shibboleth.sso>
SetHandler shib
</Location>
```
Generally you will not need to change this unless your specific application
requires URLs of the form `/Shibboleth.sso/...`.
### Requiring sign in
Configuring mod_shib does not actually cause the website to be Raven
protected. 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:
```apache
# Protect entire site with Raven authentication.
<Location />
# Use Shibboleth to provide SAML 2.0 integration with Apache.
AuthType shibboleth
# Initiate a new session with Raven SAML 2.0 if one did not previously
# exist.
ShibRequireSession On
<RequireAll>
# Require that authentication succeeded.
Require valid-user
# Require that the user is a Cambridge University member. THIS IS
# REQUIRED TO AVOID LETTING NON-CAMBRIDGE USERS SIGN IN TO YOUR SITE.
Require shib-attr affiliation member@cam.ac.uk
# If you wish to restrict access to a particular lookup group, set
# the numeric group number here. Only sites hosted from domains
# ending in .cam.ac.uk will have lookup groups given to them.
# Alternatively you could use mod_authz_ldap and use Lookup directly as
# described in the Raven documentation.
#
# Require shib-attr groupID 123456
</RequireAll>
</Location>
```
## Next steps
This page has covered the basic moving parts of an Apache web server configured
to use Raven SAML 2.0 for sign in.
Remember to read the [Raven golden rules](golden-rules.md) when configuring your
website.
The [full list of SAML 2.0 attributes](saml2-attributes.md) is available on this
site for your reference along with some [generic Raven SAML 2.0
instructions](raven-saml2.md).
title: OAuth2 Client Credentials
# Registering OAuth2 Client Credentials
The Raven OAuth2 service allows websites to authenticate using the
[OAuth2](https://oauth.net/2/) protocol. In order to make use of the OAuth2
protocol you will need to register some *client credentials*.
OAuth2 requires that an application authenticating a user identify itself to the
authentication service. Client credentials are the way in which your website
identifies itself to Raven when requesting user sign in.
Client credentials consist of two parts. The **client id**, sometimes called the
**client key**, is the equivalent of a username identifying your application.
The **client secret** is the equivalent of a password. As the name suggests, it
should be kept secret.
## Register a Google account
Raven makes use of OAuth2 client credentials managed by Google. There are,
somewhat confusingly, several forms of identity in the Google ecosystem:
An **ordinary Google account** is the sort of Google account you can register
for free at https://google.com/. All that you need to register an ordinary
Google account is the ability to receive email. An ordinary Google account is
associated with an email address.
A **G Suite account** is like an ordinary Google account but the associated email
address ends in `@cam.ac.uk`. G Suite accounts use Raven to authenticate
rather than giving a password to Google. A G Suite account is associated with a
single individual.
A **service account** is an account associated with a particular “project” in
Google’s [developer console](https://console.developers.google.com/). They are
_not_ associated with individuals. They do have email addresses associated with
them which end with `.gserviceaccount.com`. There is no mailbox behind the
email address associated with service accounts.
In order to register new OAuth2 client credentials you will need to create an
*ordinary Google account*. If you're just experimenting you can use any personal
GMail account. If you're deploying a site in production we **strongly**
recommend that you create a shared Google account for a role address. For
example, the COs of St Botolph's college would create a Google account for
`computer-officers@botolphs.cam.ac.uk` and store the credentials like they do
with any other shared secrets. By using a role address, you can have some
confidence that access to the Google account can be recovered in future as
people join or leave your team.
## Create a Google project
Once registered, sign in as the shared user, open the [Google developer
console](https://console.developers.google.com/) and create a new project for
your service; click **Select a project**, then **NEW PROJECT**, enter a name
for the project and, optionally, edit the provided project ID. Click **Create**.
!!! note "G Suite accounts cannot create projects in the Google developer console"
This is intentional. It is easy to miss which Google user you are currently
signed in as and the G Suite administrators want to make it very hard for
projects to be created by an individual who forgets to grant owner access to
the rest of their team. Such projects are in danger of becoming "orphaned"
when the individual who created it leaves the University.
You will first need to add an initial set of administrators:
1. Navigate to the [IAM
page](https://console.developers.google.com/iam-admin/iam) of the Google
developer console for your project.
2. Use the **Add** button at the top of the page to add some G Suite users to
the project and give them the **Project Owner** role.
(Recall that users with email addresses of the form `...@cam.ac.uk` are part
of the University's G Suite account and are authenticated via Raven sign in.)
3. Sign out from the shared role account and proceed using one of the G Suite
accounts you just added to the project as an administrator.
!!! important "All project administration should now be done as a G Suite user"
It is best practice to use the shared Google account sparingly. As people
join or leave your team, their corresponding G Suite user can be added or
removed to the set of project owners.
Sign in details for the shared account should be kept securely for disaster
recovery purposes or for adding project owners if all existing project
owners are unavailable.
## Create the client credentials
Once you have a new Google project, you can create some OAuth2 client
credentials for your first application.
1. Open the [Google API Console Credentials
page](https://console.developers.google.com/apis/credentials).
2. On the Credentials page, select **Create credentials**, then **OAuth client
ID**.
3. You may be prompted to set a product name on the Consent screen; if so, click
**Configure consent screen**, supply the requested information, and click
Save to return to the Credentials screen.
4. Select **Web Application** for the **Application Type**. If the web
application or web server you are configuring specifies JavaScript origins or