From 42191b21b11697b60623b086c4fcce47a8f6000e Mon Sep 17 00:00:00 2001 From: jeb228 Date: Tue, 14 Dec 2010 21:58:02 +0000 Subject: [PATCH] NIHVIVO-1329 document how to setup Shibboleth. --- doc/install.txt | 92 ++++++++++++++++++++++++++++++++++++++- example.deploy.properties | 17 ++++++++ 2 files changed, 107 insertions(+), 2 deletions(-) diff --git a/doc/install.txt b/doc/install.txt index ae00db42..d3c9b1bb 100644 --- a/doc/install.txt +++ b/doc/install.txt @@ -33,7 +33,8 @@ are slightly different. Please consult developers.txt in this directory. * IX. Set the Contact Email Address (if using "Contact Us" form) * X. Setup Apache Tomcat Connector * XI. Configure Pellet Reasoner - * XII. Was the installation successful? + * XII. Using an External Authentication System with VIVO + * XIII. Was the installation successful? ------------------------------------------------------------------------------- @@ -156,6 +157,17 @@ example value: password property name: initialAdminUser example value: defaultAdmin + The name of a property that can be used to associate an Individual + with a user account. When a user logs in with a name that matches + the value of this property, the user will be authorized to edit + that Individual. +property name: selfEditing.idMatchingProperty +example value: http://vivo.mydomain.edu/ns#networkId + +NOTE: If you want to use an external authentication system like Shibboleth or +CUWebAuth, you will need to set two additional properties in this file. See +the section below entitled "Using an External Authentication System with VIVO". + ------------------------------------------------------------------------------- V. Compile and deploy @@ -334,7 +346,83 @@ property entailments are not needed. ------------------------------------------------------------------------------- -XII. Was the installation successful? +XII. Using an External Authentication System with VIVO + +VIVO can be configured to work with an external authentication system like +Shibboleth or CUWebAuth. + +VIVO must be accessible only through an Apache HTTP server. The Apache server +will be configured to invoke the external authentication system. When the user +completes the authentication, the Apache server will pass a network ID to VIVO, +to identify the user. + +If VIVO has an account for that user, the user will be logged in with the +privileges of that account. In the absence of an account, VIVO will try to find +a page associated with the user. If such a page is found, the user can log in +to edit his own profile information. + +---- Configuring the Apache server: + +Your institution will provide you with instructions for setting up the external +authentication system. The Apache server must be configured to secure a page in +VIVO. When a user reaches this secured page, the Apache server will invoke the +external authentication system. + +For VIVO, this secured page is named: + /loginExternalAuthReturn +When your instructions call for the location of the secured page, this is the +value you should use. + +---- Configuring VIVO: + +To enable external authentication, VIVO requires three values in the +deploy.properties file. + +* The name of the HTTP header that will hold the external user’s network ID + + When a user completes the authentication process, the Apache server will + put the user’s network ID into one of the headers of the HTTP request. + The instructions from your institution should tell you which header is + used for this purpose. + + You need to tell VIVO the name of that HTTP header. Insert a line like + this in the deploy.properties file: + externalAuth.netIdHeaderName = [the header name] + For example: + externalAuth.netIdHeaderName = remote_userID + +* The text for the Login button + + To start the authentication process, the user will click on a button in + the VIVO login form. You need to tell VIVO what text should appear in that + button. + + Put a line like this in the deploy.properties file: + externalAuth.buttonText = [the text for your login button] + For example: + externalAuth.buttonText = Log in using BearCat Shibboleth + + The VIVO login form will display a button labelled “Log in using BearCat + Shibboleth”. + +* Associating a User with a profile page + + If VIVO has an account for the user, the user will be given the privileges + assigned to that account. + + In addition, VIVO will try to associate the user with a profile page, so + the user may edit his own profile data. VIVO will search the data model + for a person with a property that matches the User’s network ID. + + You need to tell VIVO what property should be used for matching. Insert + a line like this in the deploy.properties file: + selfEditing.idMatchingProperty = [the URI of the property] + For example: + selfEditing.idMatchingProperty = http://vivo.mydomain.edu/ns#networkId + +------------------------------------------------------------------------------- + +XIII. Was the installation successful? If you have completed the previous steps, you have good indications that the installation was successful. diff --git a/example.deploy.properties b/example.deploy.properties index ec5fa830..891e2a0a 100644 --- a/example.deploy.properties +++ b/example.deploy.properties @@ -78,3 +78,20 @@ VitroConnection.DataSource.pool.maxActive = 320 # change the password the first time you login. # initialAdminUser = defaultAdmin + +# +# How is a logged-in user associated with a particular Individual? One way is +# for the Individual to have a property whose value is the username of the user. +# This is the name of that property. +# +selfEditing.idMatchingProperty = http://vivo.mydomain.edu/ns#networkId + +# +# If an external authentication system like Shibboleth or CUWebAuth is to be +# used, these properties say how the login button should be labeled, and which +# HTTP header will contain the user ID from the authentication system. If such +# as system is not to be used, leave these commented out. Consult the +# installation instructions for more details. +# +#externalAuth.buttonText = Log in using BearCat Shibboleth +#externalAuth.netIdHeaderName = remote_userID