Wiki Home	Download Grouper	Grouper Guides	Community Contributions	Developer Resources	Deployment Guide

Overview

There are a few different ways of authenticating to the Grouper UI. For any method, the mapping of the login username to a Grouper subject works the same.

After authentication, Grouper will attempt to retrieve the username by these methods in order:

httpServletRequest.getRemoteUser()
a specific http header, as configured in property grouper.ui.authentication.http.header in grouper-ui.properties
servlet attribute REMOTE_USER
httpServletRequest.getUserPrincipal().getName()
httpServletRequest session attribute "authUser"

If none of these return a non-empty string, the authentication will fail with error:

"You have an anonymous session since you are not logged in, but this section requires you to be logged in. Maybe No username found. Your identity provider might not be sending your username to this application. Either you need to use a different identity provider, or ask your IT department to send your username to this application."

If the username is obtained in the above step, the Grouper UI will attempt to convert this to a subject, trying as either an id or an identifier. By default it will search in all subject sources. If you want to constrain the login to specific subject sources, this can be configured in grouper-ui.properties value grouper.ui.authentication.sourceIds. For example, you may want to limit logins to regular people, excluding irrelevant accounts such as GrouperSystem. You can specify multiple sources as a comma-separated list.

Since the resolver will look up the subject by either id or identifier, the SQL or LDAP queries in subject.properties may be adjusted to resolve on alternative fields, in case the login username differs from the normal usage of id or identifier. For example, if a source normally uses uid as identifier but the login scheme utilizes eduPersonPrincipalName style usernames (e.g. uid@example.com), an LDAP source's searchSubjectByIdentifier parameter can be modified to use both as identifiers:

subjectApi.source.myLdap.search.searchSubjectByIdentifier.param.filter.value = (&(|(uid=%TERM%)(eduPersonPrincipalName=%TERM%))(objectclass=eduPerson))

As an alternative, if the web server sets a "uid" http header after login (e.g., if using a Shibboleth SSO identity provider that releases uid), the configuration property grouper.ui.authentication.http.header can be set to "uid". In this case, the resolver will use the uid header value as the %TERM% to look up.

Note: if you use a load balancer or reverse proxy that offloads the SSL then you need to set this in the tomcat server.xml <Connector> element for AJP. Something (maybe csrfguard) will redirect from non SSL to SSL and that will send 302's to ajax and cause errors when trying to parse XML and cant.

<Connector ... scheme="https" secure="true" />

Tomcat authentication using realms (v2.5+)

For a UI/WS that was installed using the Grouper Installer, Tomcat web.xml authentication is not used anymore. Grouper has usernames and encrypted passwords in the database. Initially the GrouperSystem subject is used since that is the only subject available when Grouper is installed. This should be replaced in the UI and could be replaced in the WS. It is not recommended to use tomcat-users.xml anymore, but you could use another type of tomcat or apache authentication. See also this page.

Authentication using Shibboleth Single Sign-on (SSO)

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

This setup assumes an Apache web server with the mod_shib module available, on a server with a Shibboleth service provider (SP) already set up. The servlet container (Tomcat or other) is connected to Apache, typically by proxy_ajp or another mechanism, and the authentication is removed from Tomcat and the Grouper servlet configuration as described below. Apache takes control over the authentication, thus maintaining a login session independent of Grouper. 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.

Configure Shibboleth so that it will protect any content that lives under the main Grouper install directory. To do this, enable mod_shib (your location and version may vary), and require Shibboleth for the /grouper/* URI;
```
LoadModule mod_shib /usr/lib64/shibboleth/mod_shib_22.so

<Location /grouper>
Authtype shibboleth
ShibRequireSession On
require shibboleth
ShibUseHeaders On</Location>
```

Then add an AJP proxy to the Apache configuration to forward requests for /grouper to the Tomcat install

LoadModule proxy_ajp_module modules/mod_proxy_ajp.so

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

Add an AJP connector to Tomcat. The Tomcat conf/server.xml configuration may already have an AJP connector set up. If so, make sure the property tomcatAuthentication= "false" is included.
```
<Connector port= "8009"   protocol= "AJP/1.3"   tomcatAuthentication= "false"   redirectPort= "8443"   />
```

Remove authentication from the servlet application. From the grouper WEB-INF/web.xml file, remove all security-constraint, login-config, and security-role sections:

  <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>grouper_user</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>grouper_user</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>grouper_user</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>grouper_user</role-name>
  </security-role>

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

CAS Authentication to the Grouper UI

Thanks to California Polytechnic State University for providing information on Authentication to Grouper using CAS.

Method 1: Tomcat Container Authentication
Method 2: Client Configuration Using web.xml
Previous way to integrate CAS with Grouper (< Grouper v2.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

Child pages