Setting up SAML Single Sign On

QPixel has support for SAML authentication using the devise_saml_authenticatable gem. See their repository for more information in case you have very special needs or need more support in how to configure.

Server configuration

The main configuration happens in the config/initializers/devise.rb and config/attribute-map.yml.

Caveat: there is a devise_example.rb in the initializers. Be sure to remove that one, otherwise, its settings will override the normal devise settings!

SAML Configuration

The main settings that you need to change are at the bottom of the devise configuration, in config.saml_configure:

config.saml_configure do |settings|
  settings.assertion_consumer_service_url     = '<http(s)-site-address-here>/users/saml/auth'
  settings.assertion_consumer_service_binding = 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST'
  settings.name_identifier_format             = 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent'
  settings.security[:want_assertions_signed]  = true
  settings.security[:metadata_signed]         = true
  settings.security[:authn_requests_signed]   = true
  settings.force_authn                        = !Rails.env.production?
  settings.protocol_binding                   = "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
  settings.passive                            = false
  settings.issuer                             = '<http(s)-site-address-here>/users/saml/metadata'
  settings.idp_slo_target_url                 = '<single logout service url of IDP>'
  settings.idp_sso_target_url                 = '<single sign on service url of IDP>'
  settings.idp_entity_id                      = '<metadata url of IDP>'
  settings.idp_cert                           = '<certificate of IDP>'
  settings.certificate                        = '<your (self-signed) certificate>'
  settings.private_key                        = '<your key (for your certificate)>'
end

The exact settings depend on your IDP, and more settings are available than shown here. See https://github.com/apokalipto/devise_saml_authenticatable and https://github.com/onelogin/ruby-saml for more information on what the different attributes do and which attributes are available.

There are also some tutorials for how to set up your application using some common IDPs at https://github.com/apokalipto/devise_saml_authenticatable/wiki .

Certificates

For signed or encrypted communication, you need to exchange a certificate with the SAML server. Normally, this will be a self-signed certificate, but that depends on your IDP. You can specify these settings by reading the certificates from a file with:

  settings.private_key = File.read('relative/or/absolute/path/private_key')

Alternatively, you can directly provide the certificates in a multi-line string in Ruby:

  settings.private_key =
'-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----'

Attributes

You configure the attributes in the config/attribute-map.yml. Your SAML response needs to contain at least an email address, unique identifier and some name for the user. The unique identifier can be the email address.

UID
A unique identifier to identify a particular user. Map this attribute to saml_init_identifier. If your UID is email, instead map it to saml_init_email_and_identifier. If you do so, you also have to update config.saml_default_user_key in config/initializers/devise.rb to the same value.

Email
The email address of the user. Map this attribute to saml_init_email. If your UID is email, instead map it to saml_init_email_and_identifier. If you do so, you also have to update config.saml_default_user_key in config/initializers/devise.rb to the same value.

Username
All users in QPixel must have some name they go by. This can be their real name, a displayname or can be any username (chosen by themselves). You have two options. The first option is to map a SAML attribute to saml_init_username_no_update. This will initialize the username of the user to the chosen attribute, but it will not get updated from SAML after the user is created.

The other option is to map a SAML attribute to username instead. This means that every time the user signs in, their username is updated to whatever the SAML response indicates. Effectively this means that users cannot choose their username on the platform, and are stuck with whatever attribute you map it to.

Enabling SSO

Next, you must configure QPixel to actually enable the Single Sign On sign in method. As an administrator, you need to go to Mod Tools, Admin Tools, Global Site Settings, and enable the setting SsoSignIn. By default, enabling this disables normal (email + password) authentication. If you want to allow both, enable the setting MixedSignIn.