Wiki Home	Grouper Release Announcements	Grouper Guides	Grouper Deployment Guide	Community Contributions	Internal Developer Resources

There are various approaches for implementing authentication to the Grouper UI. This page includes information on

Authentication using Shibboleth

Thanks to Newcastle University for providing this information on Authentication to Grouper using Shibboleth.

These are instructions on how to protect access to the Grouper User Interfaces with Shibboleth.

Any users trying to access the UI will need to create a valid session with Shibboleth, before being granted or denied access to the Grouper application.

The following page will explain how we have achieved this, there maybe some difference in configurations required depending on server set up.

The first step is to configure Shib so that it will protect any content that lives under the main Grouper install directory, to do this we use the following location block in our Shib conf file;
<Location /grouper>
Authtype shibboleth
ShibRequireSession On
require valid-user
</Location>
We configure our Tomcat server to take the headers from Apache, in the server.xml configuration file in our<TOMCAT-HOME>/conf directory, we define the AJP(8009) connector not to use tomcat Authentication;
<Connector port="8009" protocol="AJP/1.3" tomcatAuthentication="false" redirectPort="8443" />
We currently use mod_proxy to forward requests for /grouper to our Tomcat install

ProxyPass /grouper ajp://localhost:8009/grouper

On the install of Grouper 1.5 and the new Lite UI, we encountered problems when accessing the lite UI, when browsing to https://<server-name>/grouper/grouperUi/appHtml/grouper.html?operation=SimpleMembershipUpdate.index, we encountered an HTTP 403 error. This subsequently highlighted problems when trying to access the admin UI using the link from the grouper holding page, https://<server-name>/grouper/callLogin.do, which also gave us a HTTP 403 error.

With the help of the Grouper user mailing list, solutions to solve these problems were pointed out which we have implemented in our install successfully.

The main way to overcome the authentication problems was to make use of the CAS contribution, more details of which can be found on the Yale CAS auth page.

Gary pointed out the key areas from the CAS contribution that would solve the problems we were having with the 403 errors, these changes are documented below;

NOTE: By adding in the CAS contribution to the build of the UI solved the problems, below highlights the configurations that are specific to what we were wanting to achieve.

Grouper Admin UI

When accessing the admin UI through https://<server-name>/grouper/callLogin.do, this will call the default authentication method for Grouper, when protected by Shib it needs to bypass this page and go straight to the Grouper home page. This can be done by amending the action path for callLogin in the struts-config.xml, amend this so that it forwards the request to home.do rather than login.do;

<action path="/callLogin" scope="request"
type="edu.internet2.middleware.grouper.ui.actions.CallLoginAction"
unknown="false" validate="false">
<forward name="callLogin" path="/home.do" redirect="true"/>
</action>

Once this change has been put in place, when the callLogin action is called it will forward the user straight through to the home page as they have already identified themselves through Shib.

web.xml

To tell the grouper webapp not to authenticate (leave it to the web server), take out this section (all security stuff):

<security-constraint>
    <web-resource-collection>
      <web-resource-name>UI</web-resource-name>
      <url-pattern>/grouperUi/app/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>*</role-name>
    </auth-constraint>
  </security-constraint>

<security-constraint>
    <web-resource-collection>
      <web-resource-name>UI</web-resource-name>
      <url-pattern>/grouperUi/appHtml/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>*</role-name>
    </auth-constraint>
  </security-constraint>

<security-constraint>
    <web-resource-collection>
      <web-resource-name>UI</web-resource-name>
      <url-pattern>/grouperExternal/app/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>*</role-name>
    </auth-constraint>
  </security-constraint>

<security-constraint>
    <web-resource-collection>
      <web-resource-name>UI</web-resource-name>
      <url-pattern>/grouperExternal/appHtml/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>*</role-name>
    </auth-constraint>
  </security-constraint>

<security-constraint>
    <web-resource-collection>
      <web-resource-name>Tomcat login</web-resource-name>
      <url-pattern>/login.do</url-pattern>
    </web-resource-collection>
    <auth-constraint>
       
       <role-name>*</role-name>
    </auth-constraint>
  </security-constraint>
<login-config>
    <auth-method>BASIC</auth-method>
    <realm-name>Grouper Application</realm-name>
  </login-config>


<security-role>
    <description>
      The role that is required to log in to the Grouper UI
    </description>
    <role-name>*</role-name>
  </security-role>

This change will now allow users to access through to the lite Ui through the login link or the admin ui when the user has a valid Shib Session, if they do not have a session they are directed to the Shib login page.

The configurations shown above maybe slightly different for other environments, though hopefully it will be of some help.

CAS Authentication to the Grouper UI

Method 1: Tomcat Container Authentication
Method 2: Client Configuration Using web.xml
Previous way to integrate CAS with Grouper (< 2.4.0)
- The yale-cas-auth java jar file is included with the installation of the Grouper UI. There are a few steps we needed to implement it:
  - - Configuration Steps to enable CAS Authentication
    - Deployment Steps
  - Troubleshoot

There are two different ways of enabling CAS authentication to protect Grouper resources. These have been tested with Grouper 2.4.0 primarily as a proof of concept, although there is some reports of success from similar configurations based on these.

CAS Authentication Method 1: Tomcat Container Authentication

The context definition in server.xml for Tomcat looks like this:

<Context docBase="/ucd/opt/grouper-ui/dist/grouper" path="/grouper"
    reloadable="false" mapperContextRootRedirectEnabled="true" mapperDirectoryRedirectEnabled="true">

  <Realm className="org.jasig.cas.client.tomcat.v85.PropertiesCasRealm"
     propertiesFilePath="/etc/tomcat/grouper-users.properties"
   />

    

  <Valve className="org.jasig.cas.client.tomcat.v85.Cas20CasAuthenticator"
     encoding="UTF-8"
     casServerLoginUrl="https://CAS_SERVER/cas/login"
     casServerUrlPrefix="https://CAS_SERVER/cas/"
     serverName="GROUPER_SERVER"
   />

  
  <Valve className="org.jasig.cas.client.tomcat.v85.SingleSignOutValve"
    artifactParameterName="SAMLart"
  />
</Context>

The following jar files will need to go into the Tomcat lib directory (with current versions as of May 2019):

org.jasig.cas.client : cas-client-core (v3.5.1) [Download]
org.jasig.cas.client : cas-client-integration-tomcat-common (v3.5.1) [Download]
org.jasig.cas.client : cas-client-integration-tomcat-v85 (v3.5.1) [Download]
org.slf4j : slf4j-api (v1.7.26) [Download]

In Grouper's WEB-INF/web.xml, comment out the login-config and security-role sections. The security-constraint sections should remain so that authentication is triggered. The role-name can be changed to "*" (or "**" if that doesn't work) to allow all validated users to log in.

For other versions of Tomcat, change v85 to v8, v7, or v6 as appropriate.

CAS Authentication Method 2: Client Configuration Using web.xml

This method makes changes solely within the Grouper web application, without affecting the Tomcat configuration.

1. Download the cas-client-core jar file (current version is cas-client-core-3.5.1.jar as of May 2019)

2. Copy the web applications top-level index.jsp to a new subdirectory cas/

3. Edit cas/index.jsp to reference parent directory instead of the current one

<%@ include file="../WEB-INF/grouperUi2/assetsJsp/commonTaglib.jsp"%>
String location="../grouperUi/app/UiV2Main.index?operation=UiV2Main.indexMain";

4. Add to WEB-INF/classes/Owasp.CsrfGuard.overlay.properties

org.owasp.csrfguard.unprotected.CASLogin=%servletContext%/cas/*

5. Add to WEB-INF/web.xml, changing parameters as needed. Based on https://apereo.atlassian.net/wiki/spaces/CASC/pages/103252594/Configuring+the+Jasig+CAS+Client+for+Java+in+the+web.xml

<filter>
  <filter-name>CAS Authentication Filter</filter-name>
  <filter-class>org.jasig.cas.client.authentication.AuthenticationFilter</filter-class>
  <init-param>
    <param-name>casServerUrlPrefix</param-name>
    <param-value>http://localhost:8080/cas</param-value>
  </init-param>
  <init-param>
    <param-name>serverName</param-name>
    <param-value>http://localhost:8080</param-value>
  </init-param>
</filter>
<filter-mapping>
    <filter-name>CAS Authentication Filter</filter-name>
    <url-pattern>/cas/*</url-pattern>
</filter-mapping>
<filter>
  <filter-name>CAS Validation Filter</filter-name>
  <filter-class>org.jasig.cas.client.validation.Cas20ProxyReceivingTicketValidationFilter</filter-class>
  <init-param>
    <param-name>casServerUrlPrefix</param-name>
    <param-value>http://localhost:8080/cas</param-value>
  </init-param>
  <init-param>
    <param-name>serverName</param-name>
    <param-value>http://localhost:8080</param-value>
  </init-param>
</filter>
<filter-mapping>
    <filter-name>CAS Validation Filter</filter-name>
    <url-pattern>/cas/*</url-pattern>
</filter-mapping>
<filter>
  <filter-name>CAS HttpServletRequest Wrapper Filter</filter-name>
  <filter-class>org.jasig.cas.client.util.HttpServletRequestWrapperFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>CAS HttpServletRequest Wrapper Filter</filter-name>
    <url-pattern>/cas/*</url-pattern>
</filter-mapping>

6. Start Tomcat, check catalina and localhost logs if any startup errors

7. Go to URI /grouper/cas/index.jsp to trigger the start of a CAS session.

Previous way to integrate CAS with Grouper (prior to Grouper 2.4.0)

The yale-cas-auth java jar file is included with the installation of the Grouper UI. There are a few steps we needed to implement it:

Configuration Steps to enable CAS Authentication

Add the cas authentication piece to the build.xml file in the Grouper UI home/build folder: /deploy/AppServers/grouper-ui folder:
/deploy/AppServers/grouper-ui/build.xml

<ant antfile="build.xml" target="webapp" dir="${contrib.dir}/yale-cas-auth" inheritrefs="true" />

It should go just below the following section in the build.xml file:


                <antcall target="-additional-build">
                        <param name="target" value="webapp"/>
                                                <reference refid="ui.class.path.for.run"/>
                </antcall>

Implementer note: There are several -additional-build sections. Ensure you find the one that has a target with a value of "webapp".

Modify the following 3 lines in the build.properties file that is in the yale-cas-auth folder -- enter proper URLs for your organization:
/deploy/AppServers/grouper-ui/contrib/yale-cas-auth/build.properties

#Grouper CAS Integration for CalPoly
sso.login.url=https://mydev.YourCampus.edu/cas/login
sso.validate.url=https://mydev.YourCampus.edu:443/cas/serviceValidate
grouper.server.name=s-grouper.its.YourCampus.edu

Modify the struts-config.xml file to skip the login prompt by changing the callLogin path to home.do instead of login.do:
/deploy/AppServers/grouper-ui/webapp/WEB-INF/struts-config.xml
<forward name="callLogin" path="/home.do" redirect="true"/>
Ensure the REMOTE_USER value that is returned from CAS is configured as one of the subject identifiers in the sources.xml:
/deploy/AppServers/grouper/conf/sources.xml
<init-param>
  
  <param-name>subjectIdentifierCol0</param-name>
  <param-value>SUBJECT_NAME</param-value>
</init-param>
This is based on using the GrouperJdbcSourceAdapter2 source adapter type
Ensure the grouper URL has been added to the CAS Services Registry.

Deployment Steps

From the /deploy/AppServers/grouper-ui directory, create a new war file:
ant war
Remove the grouper directory in the $TOMCAT_HOME/webapps folder:
cd /deploy/AppServers/tomcat/webapps
rm -rf grouper
Copy the new war file to the webapps directory (overwrite existing grouper.war file):
cp /deploy/AppServers/grouper-ui/dist/grouper.war .
Stop and restart Tomcat.

Troubleshoot

See debug information in logs in log4j.properties

log4j.logger.edu.internet2.middleware.grouper.ui.GrouperUiFilter = DEBUG

Page tree