OAuth2 server for wrapping Shibboleth IdPs

This is a server that creates an OAuth2 Server (identity provider). It assumes it runs behind as protected resource (e.g. by securing it with AuthType shibboleth in an Apache 2 server). Shibboleth/SAML meta data fields that are passed through as HTTP headers (like X-Remote-User) variables can be mapped to JWT token attributes.

Background

This project will be used as identity provider for the ANNIS frontend when an institutional Shibboleth identity provider (like the DFN AAI) should be used.

Installation and configuration

Configure Apache2 with Shibboleth

Follow one of the Shibboleth guides like in the Shibboleth Wiki to configure your Apache with a location secured by Shibboleth. This secured location must be forwared to the actual web service we are going to install.

``` # Proxy all requests to /login to our service at port 8020 ProxyPass http://localhost:8020 ProxyPassReverse http://localhost:8020 AuthType shibboleth ShibRequestSetting requireSession true Require shib-session # Add more conditions on the user here # This is important since we want to use the forwarded headers ShibUseHeaders On

```

Installation of the service binary

  1. To install this binary as a service you will need a working Rust compiler environment, which can be installed with https://rustup.rs/
  2. Compile the binary with cargo install shibboleth-oauth2-forwarding,
  3. Copy the resulting binary file to you system-wide binary folder bash cp ~/.cargo/bin/shibboleth-oauth2-forwarding /usr/local/bin/
  4. For systemd based Linux servers like Ubuntu 18.04, create a service unit definition file with a .service suffix in the /etc/systemd/system directory. This file could look like following example. Also make sure to choose a user (here youruser) this service should run as.

``` [Unit] Description=Authorization token wrapper for ANNIS

[Service] Type=simple ExecStart=/usr/local/bin/shibboleth-oauth2-forwarding -c /usr/local/etc/shibboleth-oauth2-forwarding.toml User=youruser Group=youruser WorkingDirectory=/usr/local/

[Install] WantedBy=multi-user.target ```

Execute bash systemctl daemon-reload to make the new file known to the system.

For non-systemd-based servers use the operating system manual to define a corresponding service.

Configuration file

In the previous service definition, the /usr/local/etc/shibboleth-oauth2-forwarding.toml file was used as configuration file. You can copy one of the example files in the examples/ folder and adjust them to your needs. We use TOML files, which syntax is documented at https://toml.io/

```toml [bind]

Define the port to use for the service

port = 8020

[mapping]

List all headers that should be forwared from Apache2 to the

include_headers = ["x-admin"]

Path to the template file that is used to generate the JWT tokens

token_template = ""

The default value for the "sub" field

default_sub = "academic"

[client]

Define the OAuth2 client ID

id = "Shibboleth"

A valid redirect URI

redirect_uri = "https://youapplicationserver/appcontext/"

[client.token_verification]

Define a secret to be shared between identity provider and service consuming the JWT token

type = "HS256" secret = "random-words-are-not-secure-please-change-me"

Alternativly, you can use a private/public key approach

type = "RS256"

private_key = "yourprivatekey"

public_key = "yourpublikey"

```

Token template

JWT tokens are created using a template file, which is given as token_template field in the mapping section of the configuration file. We use the template language Handlebars for including dynamic content like the user name (given as sub variable). Also, all forwarded headers which are defined in the include_header field of the configuration variable can be used inside the JWT token definition.

{ "sub": "{{sub}}", "exp": {{exp}}, {{#if x-admin}} "https://corpus-tools.org/annis/roles": ["admin"], {{/if}} "https://corpus-tools.org/annis/groups": ["academic"] }

Start and test the service

When you installed the service, created the configuration files and secured the /login path, you should be able to start the newly defined service. If the service unit file was named shib-wrapper.service you can start and enable the service at each boot with

bash systemctl enable shib-wrapper.service systemctl start shib-wrapper.service

Configure the application to use this OAuth2 identity provider

If your application uses Spring Security (like e.g. ANNIS), you can configure the endpoints of this OAuth2 service like this in your application properties:

```properties spring.security.oauth2.client.registration.shib.client-id=Shibboleth spring.security.oauth2.client.registration.shib.authorization-grant-type=authorization_code spring.security.oauth2.client.registration.shib.redirect-uri=https://youapplicationserver/appcontext/login/oauth2/code/shib

spring.security.oauth2.client.provider.shib.authorization-uri=https://yourserver/login/authorize spring.security.oauth2.client.provider.shib.token-uri=https://yourserver/login/authorize/token spring.security.oauth2.client.provider.shib.user-info-urihttps://yourserver/login/userinfo spring.security.oauth2.client.provider.shib.user-name-attribute=sub

```

3rd party dependencies

This software depends on several 3rd party libraries. These are documented in the "third-party-licenses.html" file in this folder.