authentication-shibboleth.cfg

#---------------------------------------------------------------#
#---------SHIBBOLETH AUTHENTICATION CONFIGURATIONS--------------#
#---------------------------------------------------------------#
# Configuration properties used by the Shibboleth               #
# Authentication plugin, when it is enabled.                    #
#---------------------------------------------------------------#

#### Shibboleth Authentication Configuration Settings ####
# Shibboleth is a distributed authentication system for securely authenticating
# users and passing attributes about the user from one or more identity
# providers. In the Shibboleth terminology DSpace is a Service Provider which
# receives authentication information and then based upon that provides a
# service to the user. With Shibboleth DSpace will require that you use
# Apache installed with the mod_shib module acting as a proxy for all HTTP
# requests for your servlet container (typically Tomcat). DSpace will receive
# authentication information from the mod_shib module through HTTP headers.
#
# See for more information on installing and configuring a Shibboleth
# Service Provider:
# https://wiki.shibboleth.net/confluence/display/SHIB2/Installation


##
## Shibboleth Sessions:
##
# When configuring your Shibboleth Service Provider there are two paradigms you
# may use: Active or Lazy Sessions. Active sessions is where the mob_shib
# module is configured to product a URL space. No one will be able to access
# that URL without first authenticating with Shibboleth. Using this method you
# will need to configure shibboleth to protect the URL: "/shibboleth-login".
# The alternative, Lazy Session does not protect any specific URL. Instead
# apache will allow access to any URL, and when the application wants to it
# may initiate an authenticated session. The Lazy Session method is preferable
# for most DSpace installations where you want public access to most of DSpace
# but restricted access to limitted areas - such as administration.

# Whether to use lazy sessions or active sessions.
authentication-shibboleth.lazysession = true

# The url to start a shibboleth session (only for lazy sessions)
# This must contain an absolute URL (e.g. http://dsapce-org/Shibboleth.sso/Login) or
# a relative path that start with slash (e.g. /Shibboleth.sso/Login)
authentication-shibboleth.lazysession.loginurl = /Shibboleth.sso/Login

# Force HTTPS when authenticating (only for lazy sessions)
authentication-shibboleth.lazysession.secure = true


##
## Shibboleth Authentication Methods:
##
# DSpace supports authentication using NetID, or email address. A user's NetID
# is a unique identifier from the IdP that identifies a particular user. The
# NetID can be of almost any form such as a unique integer, string, or with
# Shibboleth 2.0 you can use "targeted ids". You will need to coordinate with
# your shibboleth federation or identity provider. There are three ways to
# supply identity information to DSpace:
#
# 1) NetID from Shibboleth Header (best)
#
# The NetID-based method is superior because users may change their email
# address with the identity provider. When this happens DSpace will not be
# able to associate their new address with their old account.
#
# 2) Email address from Shibboleth Header (okay)
#
# In the case where a NetID header is not available or not found DSpace
# will fall back to identifying a user based-upon their email address.
#
# 3) Tomcat's Remote User (worst)
#
# In the event that neither Shibboleth headers are found then as a last
# resort DSpace will look at Tomcat's remote user field. This is the least
# attractive option because Tomcat has no way to supply additional
# attributes about a user. Because of this the autoregister option is not
# supported if this method is used.
#
# Identity Scheme Migration Strategies:
# If you are currently using Email based authentication (either 1 or 2) and
# want to upgrade to NetID based authentication then there is an easy path.
# Simply enable shibboleth to pass the NetID attribute and set the netid-header
# below to the correct value. When a user attempts to log in to DSpace first
# DSpace will look for an EPerson with the passed NetID, however when this
# fails DSpace will fall back to email based authentication. Then DSpace will
# update the user's EPerson account record to set their netted so all future
# authentications for this user will be based upon netted. One thing to note
# is that DSpace will prevent an account from switching NetIDs. If an account
# already has a NetID set and then they try and authenticate with a
# different NetID the authentication will fail.

# Authentication headers for Mail, NetID, and Tomcat's Remote User.
# Supply all parameters possible.
authentication-shibboleth.netid-header = SHIB-NETID
authentication-shibboleth.email-header = SHIB-MAIL
authentication-shibboleth.email-use-tomcat-remote-user = false

# Should we allow new users to be registered automatically?
authentication-shibboleth.autoregister = true

# Sword compatibility will allow this authentication method to work when using
# sword. Sort relies on username and password based authentication and is
# entirely incapable of supporting shibboleth. This option allows you to
# authenticate username and passwords for sword sessions without adding
# another authentication method onto the stack. You will need to ensure that
# a user has a password. One way to do that is to create the user via the
# create-administrator command line command and then edit their permissions.
authentication-shibboleth.sword.compatibility = false


##
## EPerson Metadata:
##
# One of the primary benefits of using Shibboleth based authentication is
# receiving additional attributes about users such as their names, telephone
# numbers, and possibly their academic department or graduation semester if
# desired. DSpace treats the first and last name attributes differently because
# they (along with email address) are the three pieces of minimal information
# required to create a new user account. For both first and last name supply
# direct mappings to the Shibboleth headers. In additional to the first and
# last name DSpace supports other metadata fields such as phone, or really
# anything you want to store on an eperson object. Beyond the phone field,
# which is accessible in the user's profile screen, none of these additional
# metadata fields will be used by DSpace out-of-the box. However if you
# develop any local modification you may access these attributes from the
# EPerson object. The Vireo ETD workflow system utilizes this to aid
# students when submitting an ETD.

# Metadata Headers
# Shibboleth-based headers for the first and last name attirbutes
authentication-shibboleth.firstname-header = SHIB-GIVENNAME
authentication-shibboleth.lastname-header = SHIB-SURNAME

# Additional user attributes mapping, multiple attributes may be stored
# for each user. The left side is the Shibboleth-based metadata Header
# and the right side is the eperson metadata field to map the attribute to.
#authentication-shibboleth.eperson.metadata = \
# SHIB-telephone => eperson.phone, \
# SHIB-cn => cn

# If the eperson metadata field is not found, should it be automatically created?
authentication-shibboleth.eperson.metadata.autocreate = true

# Shibboleth attributes are by default UTF-8 encoded. Some servlet container
# automatically converts the attributes from ISO-8859-1 (latin-1) to UTF-8.
# As the attributes already were UTF-8 encoded it may be necessary to reconvert
# them. If you detect problems with special characters in shibboleth attributes
# set this to true (default to false).
authentication-shibboleth.reconvert.attributes = false

##
## Role-based Groups:
##
# DSpace is able to place users into pre-defined groups based upon values
# received from Shibboleth. Using this option you can place all faculty members
# into a DSpace group when the correct affiliation's attribute is provided.
# When DSpace does this they are considered 'special groups', these are really
# groups but the user's membership within these groups is not recorded in the
# database. Each time a user authenticates they are automatically placed within
# the pre-defined DSpace group, so if the user loses their affiliation then the
# next time they login they will no longer be in the group.
#
# Depending upon the shibboleth attributed use in the role-header it may be
# scoped. Scoped is shibboleth terminology for identifying where an attribute
# originated from. For example a students affiliation may be encoded as
# "student@tamu.edu". The part after the @ sign is the scope, and the preceding
# value is the value. You may use the whole value or only the value or scope.
# Using this you could generate a role for students and one institution
# different than students at another institution. Or if you turn on
# ignore-scope you could ignore the institution and place all students into
# one group.

# The values extracted (a user may have multiple roles) will be used to look
# up which groups to place the user into. The groups are defined as
# "role.<role-name>" which is a comma separated list of
# DSpace groups.

# The shibboleth header to do role-based mappings
authentication-shibboleth.role-header = SHIB-SCOPED-AFFILIATION

# Whether to ignore the attribute's scope or value.
authentication-shibboleth.role-header.ignore-scope = true
#authentication-shibboleth.role-header.ignore-value = false

# Default mappings of roles values to a comma separated list of DSpace group
# names (Case Sensitive).
#authentication-shibboleth.role.faculty = Faculty, Member
#authentication-shibboleth.role.staff = Staff, Member
#authentication-shibboleth.role.student = Students, Member