Webserver authentication - Revision history

Drn@ecs.soton.ac.uk: Updated instructions to tell people to use the Shibboleth page.

2018-02-08T12:04:25Z

Updated instructions to tell people to use the Shibboleth page.

← Older revision		Revision as of 12:04, 8 February 2018
Line 1:		Line 1:
			{{Deprecated \| This page is somewhat out of date. Please refer to these more up to date [[Shibboleth\|Shibboleth]] instructions.}}

	How to '''configure EPrints for authentication via the webserver'''. This enables/provides for		How to '''configure EPrints for authentication via the webserver'''. This enables/provides for
	* re-use of externally managed ("enterprise") user accounts,		* re-use of externally managed ("enterprise") user accounts,

Sp: /* Prerequisites */ $v++

2012-06-30T15:13:44Z

Prerequisites: $v++

← Older revision		Revision as of 15:13, 30 June 2012
Line 20:		Line 20:

	== Prerequisites ==		== Prerequisites ==
	The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5\|EPrints RPMs]] (which, at the time of writing, was at 3.3.7) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.		The EPrints instance this has been tested with was deployed from the latest [[Installing EPrints 3 on RedHat Enterprise 5\|EPrints RPMs]] (which, at the time of writing, was at 3.3.10) on a newly installed RHEL6 machine. All paths and file names are hence based on an RPM install on RHEL5/6 and will need to be adapted to your webserver and EPrints installation and configuration.

	Download the files from http://files.eprints.org/738/ and unpack them to a directory of choice, e.g.		Download the files from http://files.eprints.org/738/ and unpack them to a directory of choice, e.g.

Sp: /* Conceptual overview */

2012-06-30T15:12:09Z

Conceptual overview

← Older revision		Revision as of 15:12, 30 June 2012
Line 13:		Line 13:
	# Add code to the installation which handles those pre-authenticated requests, creates new users and sessions, and returns to the originally requested resource. (<tt>login</tt>)		# Add code to the installation which handles those pre-authenticated requests, creates new users and sessions, and returns to the originally requested resource. (<tt>login</tt>)

	Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the ~~right~~, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).		Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the correct, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

	A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.		A consequence of external authentication is that no self-registration of user accounts within EPrints is possible (or necessary, as many would see it) anymore, unless the system providing external authentication itself offers self-registration.

Sp: /* Conceptual overview */

2012-06-30T15:10:48Z

Conceptual overview

← Older revision		Revision as of 15:10, 30 June 2012
Line 11:		Line 11:
	# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)		# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)
	# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)		# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)
	# Add code to the installation which handles those pre-authenticated requests ~~(<tt>login</tt>)~~, creates new users and sessions, and returns to the originally requested resource.		# Add code to the installation which handles those pre-authenticated requests, creates new users and sessions, and returns to the originally requested resource. (<tt>login</tt>)

	Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).		Note that the recipe below does '''not''' provide a parallel authentication method for EPrints -- it completely replaces the default authentication method and login prompt. You can disable the new authentication method to change the user type of some (possibly newly created) user account to "repository administrator" afterwards (when logging in as eprints admin with local/database authentication). Alternatively make sure that a user account already exists within EPrints that is of user type "repository adminstrator" and has a username that can authenticate to the external authentication system (with Shibboleth you'd also need to make sure that this username is returned from the SAML Identity Provider and that the right, i.e., matching username is being mapped to httpd's <tt>REMOTE_USER</tt> variable).

Sp: /* Conceptual overview */

2012-06-30T15:09:53Z

Conceptual overview

← Older revision		Revision as of 15:09, 30 June 2012
Line 8:		Line 8:
	Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files from http://files.eprints.org/738/		Here's how this integration works conceptually (not in order of steps performed). Filenames in parentheses refer to the files from http://files.eprints.org/738/
	# Enable [[HTTPS]] for your webserver and the EPrints instance.		# Enable [[HTTPS]] for your webserver and the EPrints instance.
	# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice ~~and is ''not'' visible to people logging in!~~ (<tt>auth.pl</tt>)		# Configure EPrints to send requests requiring authentication to a specific resource/URL, we'll assume <tt>/shibboleth/login</tt> below but this could be any string of your choice. (<tt>auth.pl</tt>)
	# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)		# Make EPrints proper ignore these requests (<tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>)
	# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)		# Require authentication (and possibly also authorization) in the webserver for access to this resource (<tt>eprints-httpd-auth.conf</tt>)

Sp: /* Exclude a resource from EPrints proper */

2012-06-06T16:53:57Z

Exclude a resource from EPrints proper

← Older revision		Revision as of 16:53, 6 June 2012
Line 47:		Line 47:
	Add the name of the resource where webserver authentication should happen to the end of <tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>, e.g.:		Add the name of the resource where webserver authentication should happen to the end of <tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>, e.g.:
	$c->{rewrite_exceptions} = ['/shibboleth'];		$c->{rewrite_exceptions} = ['/shibboleth'];
	After a <tt>service httpd reload</tt> EPrints should not present a nicely formatted error message when trying to access this resource (compare with any other non-existing request URI). Instead you should see an ordinary HTTP 404 "File not found" error.		After a <tt>service httpd reload</tt> EPrints should ''not'' present the usual, nicely formatted error message when trying to access this resource (compare with any other non-existing request URI). Instead you should see an ordinary HTTP 404 "File not found" error.

	=== Add the login script ===		=== Add the login script ===

Sp: /* TLS/SSL */ formatting

2012-06-06T16:29:42Z

TLS/SSL: formatting

← Older revision		Revision as of 16:29, 6 June 2012
Line 31:		Line 31:
	[[:Category:Authentication\|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.		[[:Category:Authentication\|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

	When running <tt>[[Getting Started with EPrints 3\|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - '''No doubt, for secure usage you need another name'''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.		When running <tt>[[Getting Started with EPrints 3\|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - ''No doubt, for secure usage you need another name''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

	(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>root</tt> or <tt>cgiroot</tt> statements which are mentioned [[HTTPS\|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)		(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>root</tt> or <tt>cgiroot</tt> statements which are mentioned [[HTTPS\|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)

Sp: slight rephrasing of headings

2012-03-16T10:14:45Z

slight rephrasing of headings

← Older revision		Revision as of 10:14, 16 March 2012
Line 44:		Line 44:

	== Configuration ==		== Configuration ==
	=== Exclude resource from EPrints proper ===		=== Exclude a resource from EPrints proper ===
	Add the name of the resource where webserver authentication should happen to the end of <tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>, e.g.:		Add the name of the resource where webserver authentication should happen to the end of <tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>, e.g.:
	$c->{rewrite_exceptions} = ['/shibboleth'];		$c->{rewrite_exceptions} = ['/shibboleth'];
	After a <tt>service httpd reload</tt> EPrints should not present a nicely formatted error message when trying to access this resource (compare with any other non-existing request URI). Instead you should see an ordinary HTTP 404 "File not found" error.		After a <tt>service httpd reload</tt> EPrints should not present a nicely formatted error message when trying to access this resource (compare with any other non-existing request URI). Instead you should see an ordinary HTTP 404 "File not found" error.

	=== Add login script ===		=== Add the login script ===
	There are two example scripts provided in the package:		There are two example scripts provided in the package:
	* <tt>login-noprovisioning</tt>, which failes logins for users not found in your EPrints instance and simply redirects them to a page of your choice. Provisioning user accounts needs to happen via some other process (e.g. manually, batch processes, etc.)		* <tt>login-noprovisioning</tt>, which failes logins for users not found in your EPrints instance and simply redirects them to a page of your choice. Provisioning user accounts needs to happen via some other process (e.g. manually, batch processes, etc.)
Line 63:		Line 63:
	chmod +x shibboleth/login		chmod +x shibboleth/login

	=== Tell httpd about login scipt ===		=== Tell httpd about the login scipt ===
	Next include the content of the file <tt>eprints-httpd-auth.conf</tt> inside your SSL vhost webserver configuration in <tt>/etc/httpd/conf.d/ssl.conf</tt>, adapting file system paths as necessary:		Next include the content of the file <tt>eprints-httpd-auth.conf</tt> inside your SSL vhost webserver configuration in <tt>/etc/httpd/conf.d/ssl.conf</tt>, adapting file system paths as necessary:

Line 108:		Line 108:
	'''Alternatively''', to avoid any unintentional changes to the auto-generated config file, which could be overwritten by careless use of <tt>epadmin</tt>, you could assemble a config file for the non-SSL vhost yourself, based on the series of Includes starting with <tt>/etc/httpd/conf.d/eprints.conf</tt> and include that within your httpd config instead.		'''Alternatively''', to avoid any unintentional changes to the auto-generated config file, which could be overwritten by careless use of <tt>epadmin</tt>, you could assemble a config file for the non-SSL vhost yourself, based on the series of Includes starting with <tt>/etc/httpd/conf.d/eprints.conf</tt> and include that within your httpd config instead.

	=== ~~Tell EPrints about it~~ ===		=== Activate the new authentication method ===
	To finally activate the switch to webserver-based authentication copy <tt>auth.pl</tt> to <tt>archives/[repo_id]/cfg/cfg.d/</tt> and reload httpd.		To finally activate the switch to webserver-based authentication copy <tt>auth.pl</tt> to <tt>archives/[repo_id]/cfg/cfg.d/</tt> and reload httpd.
	Conversely, to deactivate webserver-based authentication and restore EPrints' default authentication method either remove the file or wrap the whole file's content in a <tt>while(0){</tt> and <tt>}</tt> block (Perl's approximation of a block comment) and reload httpd.		Conversely, to deactivate webserver-based authentication and restore EPrints' default authentication method either remove the file or wrap the whole file's content in a <tt>while(0){</tt> and <tt>}</tt> block (Perl's approximation of a block comment) and reload httpd.

	[[Category:Authentication]]		[[Category:Authentication]]

Sp at 10:08, 16 March 2012

2012-03-16T10:08:05Z

← Older revision		Revision as of 10:08, 16 March 2012
Line 3:		Line 3:
	* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)		* automated Just-In-Time provisioning ("on-access provisioning"), instead of Just-In-Case (seperately managed batch processes)
	* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).		* Web Single Sign-On to EPrints (with Shibboleth, CAS/<tt>mod_cas</tt>, Kerberos or just about any <tt>mod_auth_*</tt> Module for Apache httpd).
	With small changes (not ~~yet~~ included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).		With small changes (not included below) EPrints user types (<tt>User</tt>, <tt>Editor</tt>, <tt>Repository Administrator</tt>) could also be assigned dynamically, based on data from an external authoritative source (e.g. an LDAP directory via <tt>Net::LDAP</tt> or an RDBMS via <tt>DBI</tt>) or recieved as SAML attributes (in case of Shibboleth).

	== Conceptual overview ==		== Conceptual overview ==

Sp: /* Exclude resource from EPrints proper */ link 20_baseurls.pl

2012-03-15T20:54:36Z

Exclude resource from EPrints proper: link 20_baseurls.pl

← Older revision		Revision as of 20:54, 15 March 2012
Line 45:		Line 45:
	== Configuration ==		== Configuration ==
	=== Exclude resource from EPrints proper ===		=== Exclude resource from EPrints proper ===
	Add the name of the resource where webserver authentication should happen to the end of <tt>archives/[repo_id]/cfg/cfg.d/20_baseurls.pl</tt>, e.g.:		Add the name of the resource where webserver authentication should happen to the end of <tt>archives/[repo_id]/cfg/cfg.d/[[20_baseurls.pl]]</tt>, e.g.:
	$c->{rewrite_exceptions} = ['/shibboleth'];		$c->{rewrite_exceptions} = ['/shibboleth'];
	After a <tt>service httpd reload</tt> EPrints should not present a nicely formatted error message when trying to access this resource (compare with any other non-existing request URI). Instead you should see an ordinary HTTP 404 "File not found" error.		After a <tt>service httpd reload</tt> EPrints should not present a nicely formatted error message when trying to access this resource (compare with any other non-existing request URI). Instead you should see an ordinary HTTP 404 "File not found" error.

← Older revision		Revision as of 16:29, 6 June 2012
Line 31:		Line 31:
	[[:Category:Authentication\|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.		[[:Category:Authentication\|SSL and HTTPS and Secure logins]] have been covered numerous times in this wiki, but most of the material is outdated and some seems horribly cumbersome (or both). Still, there's no point in creating ''yet another'' how-to for this so we'll keep this brief. TLS/SSL was enabled in the webserver by first installing the <tt>mod_ssl</tt> package and configuring a key pair in <tt>/etc/httpd/conf.d/ssl.conf</tt>.

	When running <tt>[[Getting Started with EPrints 3\|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - '''No doubt, for secure usage you need another name'''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.		When running <tt>[[Getting Started with EPrints 3\|epadmin create]]</tt> supply a hostname for https connections. ''Contrary'' to a statement from [[Getting Started with EPrints 3]] ("If you will use https for your user pages (including login) enter the https hostname - ''No doubt, for secure usage you need another name''", my emphasis) this can and probably should be your main EPrints hostname also used for plain HTTP.

	(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>root</tt> or <tt>cgiroot</tt> statements which are mentioned [[HTTPS\|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)		(To change this after installation either edit <tt>archives/[repo_id]/cfg/cfg.d/10_core.pl</tt> or do as suggested in this file and run <tt>epadmin config_core [repo_id]</tt>. Note that leaving this to <tt>epadmin</tt> does ''not'' set or change any of the <tt>root</tt> or <tt>cgiroot</tt> statements which are mentioned [[HTTPS\|in the wiki]]. Only <tt>$c->{securehost}</tt> seems to be needed.)