Allows Grails applications to easily integrate to federated authentication sources particuarly those served by Shibboleth service providers.
Groovy Gosu CSS JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Federated Grails

For application developers Federated environments can be somewhat daunting and complex.

By using this plugin Grails applications (particuarly those protected by Shibboleth service providers can easily integrate into federated authentication.

The plugin utilizes Apache Shiro as an underlying mechanism so serves managing access control requirements equally as well. I recommend you read the Shiro documentation before continuing to get a feel for how this plugin operates -


  • Subject - Security specific view of an entity capable of being authenticated to an application. It can be a human being, a third-party process, a server etc. Also referred to as ‘user’.
  • Principal - A subjects uniquely identifying attribute. This is generally mapped to the federation attribute eduPersonTargetedID. For non federated applications this is commonly referred to as a ‘username’
  • Credentials - Data used to verify identity at session establishment. For integrators this is the associated SAML assertion and is represented by a unique internal sessionID. For non federated applications this is usually a ‘password’
  • Attributes - A subjects identifying attributes. Names, email, entitlements etc.For non federated applications these need to manually entered. For federated applications they are in many cases automatically supplied.


To get started a very basic sample app is provided at test/dummy.

grails run-app

to try it out.


Prerequisite: Your Shibboleth SP is setup and working correctly (this doesn't apply if you simply wish to enable development mode on your local development environment).

Execute the supplied script to integrate

grails integrate-federation Package Subject
  • Package should be your applications package structure eg
  • Subject should be the name of your subject class you can change this to say User if this better suits your application.

All controllers except those supplied by the plugin will now be authenticated to the federation. Update grails-app/conf/SecurityFilters.groovy to make this more restrictive.

On completion of this integration your application will have been provided with the AuthController and Federated/Database Realms. Generally the best place to start making extensions is within the provisioning and update routines located within FederatedRealm.groovy. In addition your Subject domain object will be located within the appropriate folder structure under your grails-app/domains directory.


All configuration is managed in:

  • automatelogin - When the user needs to login they will be forwarded directly to the Shibboleth configured endpoint and not shown the login view.
  • federationactive - The application is being protected by a shibboleth instance
  • developmentactive - The application is in development mode and accounts may be specified on the login page
  • autoprovision - New users to the system will be automatically created
  • subject - The name of your subject class, generally Subject but maybe User is you changed during installation.
  • ssoendpoint - The endpoint within you Shibboleth SP configuration that will initiate a session
  • attributes - To use apache environment variables or HTTP headers to retrieve attributes. If you're making use of mod_jk to interface to your Tomcat instance from Apache this should be true.
  • mapping.XYZ - The set of attributes you expect to be delivered to your SP by remote IdP and available in your app


All contributions welcome. Simply fork and send a pull request when you have something new or log an issue.

For code changes please ensure you supply working tests and documentation.

Requests for additional information to go along with this documentation are also welcomed.


FederatedGrails was written by Bradley Beddoes on behalf of the Australian Access Federation.