Skip to content

Shibboleth Setup

Jump to bottom
Julie Allinson edited this page Jun 29, 2017 · 8 revisions

Setting up Shibbloleth and Hyku

Shibboleth Basics

There are two parts to shibboleth

  • Service Provider (SP) - this is the application making the request to authenticate
  • Identity Provider (IdP) - this is the application doing the authentication

This guide is about setting up a Service Provider.

Testing with testshib.org

testshib.org provides a sandbox for testing shibboleth configuration. It's highly recommended for getting the initial setup working and provides a step by step guide, and a ready-made shibboleth.xml file for your server.

Follow the guide on the testshib site to guide you through installation and configuration.

Step One: Install Shibboleth and Configure Apache

With puppet, eg. via /~https://github.com/Aethylred/puppet-shibboleth

Manual setup on centos

See the Documentation

  1. First download a copy of the appropriate shibboleth.repo file from https://shibboleth.net/downloads/service-provider/latest/RPMS/ into /etc/yum.repos.d/.
  2. Install with yum install shibboleth.x86_64
  3. Configure /etc/shibboleth/shibboleth2.xml (it's wise to backup the existing file before making changes). But see note about testshib - for initial testing, testshib.org will provide a shibboleth.xml.
  4. Start shibd with /sbin/service shibd start
  5. Enable at startup systemctl enable shibd

Apache installation and configuration

Install apache (httpd) and mod_ssl and enable apache at startup.

yum install httpd mod_ssl
systemctl enable httpd.service

Add VirtualHost configuration directories

mkdir /etc/httpd/sites-available
mkdir /etc/httpd/sites-enabled

Add the following line to to the end of /etc/httpd/conf/httpd.conf to load any additional configs

IncludeOptional sites-enabled/*.conf

Create a configuration file with a .conf extension in /etc/httpd/sites-available.

The following is a basic config. There will likely be additional configuration depending on how the appliation is running (eg. passenger setup for rails).

<VirtualHost *:443>
    ServerName YOUR_IP_ADDRESS_OR_HOSTNAME

    SSLEngine On
    # Using existing self-signed cert - change this to a proper certificate
    SSLCertificateFile /etc/pki/tls/certs/localhost.crt
    SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
    CustomLog       "/var/log/httpd/ssl_access_log" combined
    ErrorLog        "/var/log/httpd/ssl_error_log"

    # Shibboleth Setup
    # The location matches the path in your application that will redirect to shibboleth 
    # for authentication
    <Location "/users/auth/shibboleth">
        AuthType shibboleth
        ShibRequestSetting requireSession 1
        require valid-user
     </Location>

</VirtualHost>

Finally create a soft link in /etc/httpd/sites-enabled, eg.

ln -s /etc/httpd/sites-available/MYCONF_ssl.conf /etc/httpd/sites-enabled/MYCONF_ssl.conf

Restart httpd with sudo service httpd restart

You should now be able to download a metadata file from your_ip_or_host/Shibboleth.sso/Metadata. With this you can continue testing with testshib.org.

A Note about Attributes

The attributes that will be returned with the authentication response will depend on two things:

  1. what the IdP supports and you negotiate for it to supply to you
  2. asking for attributes in the defined way, via attributes-map.xml

There are some common attributes pre-defined in attributes-map.xml. Others will need to be added.

Note: In this basic setup, no configuration of attributes in attribute-map.xml has been done.

A Note about setting up with a real IdP

Further setup will be required to authenticate with a 'proper' shibboleth IdP. For the UK this will involve two things:

  1. Speaking to the IdP provider at the institution to authenticate against and agreeing what attributes will be exposed to the application
  2. Setting up the UK Federation metadata

Step Two: Make Shibboleth and Hyku work together

Using /~https://github.com/toyokazu/omniauth-shibboleth

Add gem 'omniauth-shibboleth' to the application Gemfile and run bundle install

configure omniauth in config/intializers/devise.rb

## ==> OmniAuth
  ## Add a new OmniAuth provider. Check the wiki for more information on setting
  ## up on your models and hooks.
  ## config.omniauth :github, 'APP_ID', 'APP_SECRET', scope: 'user,public_repo'
  config.omniauth :shibboleth, {:uid_field => 'eppn',
                                :info_fields => {
                                    ## affiliation info from testshib.org IDP
                                     :affiliation => lambda {|request_param| request_param.call('unscoped-affiliation').split(';')},
                                },
  }
  ## Note: the above 'lambda' turns a shib multi-valued attribute value into ruby array
  ## See /~https://github.com/toyokazu/omniauth-shibboleth

edit app/models/user.rb

## allow omniauth (including shibboleth) logins - this will create a local user based on an omniauth/shib login
  ## if they haven't logged in before
  def self.from_omniauth(auth)
    where(provider: auth.provider, uid: auth.uid).first_or_create do |user|
      user.provider = auth.provider
      user.uid = auth.uid
      user.email = auth.uid
      user.password = Devise.friendly_token[0,20]
    end
  end

add a controller, for example app/controllers/omniauthcallbacks_controller.rb

class OmniauthcallbacksController < Devise::OmniauthCallbacksController

  ## handle omniauth logins from shibboleth
  ## cf /~https://github.com/toyokazu/omniauth-shibboleth/issues/6
  def shibboleth
    @user = User.from_omniauth(request.env["omniauth.auth"])
    ## capture data about the user from shib
    session['shib_user_data'] = request.env["omniauth.auth"]
    sign_in_and_redirect @user
  end

  ## when shib login fails
  def failure
    ## redirect them to the devise local login page
    redirect_to new_local_user_session_path, :notice => "Shibboleth isn't available - local login only"
  end

end

edit config/routes.rb

devise_for :users, :controllers => { :omniauth_callbacks => "omniauthcallbacks" }, :skip => [:sessions]

add a migration and run it

rails g migration AddColumnsToUsers provider uid
rake db:migrate

Current Issues in Hyku:

  • Application logout destroy the session but does not log the user out of shibboleth (it can't); needs a more appropriate message on logout
  • Successful login returns the user to the dashboard, but via a POST rather than a GET request
  • All shibboleth users are getting the 'admin' role via the 'add_default_roles' method in app/models/user.rb when in fact it should only do that for the first logged in user
  • The new db migration has started to throw an error as it is attempting to add a duplicate column already added by a new migration. This work may conflict with other aspects of the new 'invitable' work. This needs testing.

Also useful:

TODO

  • Setting up multiple idp's for different Hyku tenants
  • Setting up with a 'proper' idp and getting different attributes

With huge thanks to Fergus McGlynn at UoY for his help with this.

Clone this wiki locally