(Quick Reference)

4 Configuration - Reference Documentation

Authors: Aaron J. Zirbes

Version: 1.0.0

4 Configuration

Configuring the plugin

The plugin has defauls that are set up to work out of the box with the Shibboleth IdP implementation used at the University of Minnesota. If your IdP diverges from this setup, you'll have to change the settings in use by this plugin.

All of the configuration settings are set in your grails-app/conf/Config.groovy file.

Configuring for Development

As stated before, this plugin only works in production and/or test, and you should supplement this plugin with the spring-security-mock plugin, or some other authentication method for development. The way to set up this configuration is as follows:

environments {
    production {
	…
        // Enable shibboleth, disable mock
        grails.plugins.springsecurity.shibboleth.active = true
        grails.plugins.springsecurity.mock.active = false
	…
    }
    development {
	…
        // Enable Mock security for development mode
        grails.plugins.springsecurity.shibboleth.active = false
        grails.plugins.springsecurity.mock.active = true
        grails.plugins.springsecurity.ipRestrictions = [ '/**': ['127.0.0.0/8', '::1/128'] ]
	…
    }
    test {
	…
        // Enable shibboleth, disable mock
        grails.plugins.springsecurity.shibboleth.active = true
        grails.plugins.springsecurity.mock.active = false
	…
    }
}

Configuring for your IdP

Any property overrides must be specified in grails-app/conf/Config.groovy using the grails.plugins.springsecurity suffix, for example
grails.plugins.springsecurity.shibboleth.principalUsername.attribute = 'EPPN'

There are several configuration options for the Shibbolet Natibe SP plugin. In practice the defaults are fine for most deployments and only a few will need to be overridden.

Name	Default	Meaning
remoteAddress.roles	`null`	This is used to automatically apply roles to the user based only on their origin IP address. This takes a parameter of a Map of role names, followed by a list of IP subnets. This is useful to assign roles to users based on if they are logged in from your intrantet, VPN, or wireless so you can restrict authentication methods depending on origin using nothing but security annotations.
shibboleth.authenticationInstant.attribute	'Shib-Authentication-Instant'	This is the attribute that is exposed by the IdP to tell the SP when the user was originally authenticated.
shibboleth.authenticationMethod.attribute	'Shib-Authentication-Method'	This is the attribute that tells the application what method was used to authenticate the user. This can be used by the ShibbolethUserDetailsService to assign specific roles based on authentication.
shibboleth.authenticationMethod.roles	`null`	This is a map of 'ROLE_NAME': 'auth-method-string'' that allows the ShibbolethUserDetailsService to load specific roles based on the method of authentication. This is useful to differentiate between guest logins, standard logins, two-factor authentication and the like.
shibboleth.email.attribute	`null`	The name of the attribute to use for the `email` address in the UserDetails object
shibboleth.extraAttributes	`null`	This is a list of any extra attributes you want loaded into the ShibbolethAuthenticationToken that will be exposed via the Spring Secuirity services and tags for use in your application.
shibboleth.fullName.attribute	`null`	The name of the attribute to use for the `fullName` in the UserDetails object
shibboleth.identityProvider.attribute	'Shib-Identity-Provider'	This is the attribute that tells the application which IdP was used to authenticate the user.
shibboleth.loginUrl	'/Shibboleth.sso/Login?target={0}'	The URL used by the Shibboleth Native SP to log users in. The parameter `{0}` is replaced by the AuthenticationFilter URL. You shouldn't need to modify this at all.
shibboleth.logoutUrl	'/Shibboleth.sso/Logout'	This is the default logout re-direct URL. This will log the user out of the application in addition to logging out of the local Shibboleth SP instance.
shibboleth.principalUsername.attribute	'EPPN'	This is the name of the principal attribute, usually the same as the username. This is pretty standard, and shouldn't need modification.
shibboleth.roles.attribute	`null`	This is the attribute exposed by the IdP that contains any roles you wish to use in your application. Typically these are filled in by grouper, or LDAP, or Active Directory.
shibboleth.roles.loadFromUserDetailsService	`false`	Whether or not to load additional roles from the `userDetailService` bean. The default `userDetailService` in spring-security-core is the DAO (GORM) User Details Service.
shibboleth.roles.prefix	'SHIB_'	This is the prefix assigned to all of the roles pulles from the shibboleth roles attribute. This helps prevent role name collisions with other roles used.
shibboleth.roles.separator	','	This is the delimeter that separates the role names in the roles attribute
shibboleth.useShibbolethUserDetails	`true`	Whether or not to use the Shibboleth User Details Service, or a different `UserDetailsService`. If set to `false` then the plugin will load the user details from what ever UserDetailsService is set. The default in spring-security-core is the DAO (GORM) UserDetailsService.
shibboleth.username.attribute	'EPPN'	The name of the attribute to use for the username
shibboleth.username.stripAtDomain	`false`	Remove the '@domain.com' from the username attribute, commonly found in an EPPN if you don't wish to use it. This breaks support for federated applications.

Configuration settings from spring-security-ldap that affect the behavior of this plugin

If all three of these settings are configured and enabled, then the Shibboleth plugin will attempt to load roles from LDAP rather than from the shibboleth.roles.attribute configuration setting.

Name	Default	Meaning
ldap.active	`true`	this must be set to true for spring-security-shibboleth to load roles from LDAP
ldap.authorities.retrieveGroupRoles	`true`	this must be set to true for spring-security-shibboleth to load roles from LDAP
ldap.usernameMapper.userDnBase	none, must be set	this must be set to true for spring-security-shibboleth to load roles from LDAP. This will be used to build the userDn that will be used to search LDAP for roles associated with the user. The full DN will be equivalent to "cn=${username},${userDnBase}"

Using a different User Details Service

You can use any User Details Service with the Shibboleth plugin as long as it implements GrailsUserDetailsService. This is accomplished by setting the userDetailsService in your grails-app/conf/spring/resources.groovy file.

For example:

beans = {
   userDetailsService(com.mycompany.myapp.MyUserDetailsService)
}

Configuring injected roles for your app

The following examples show how to use the roles attributes above to ensure that roles assigned to your authenticated users based on your configuration.

Sets the roles attribute to pull from grouper

grails.plugins.springsecurity.shibboleth.roles.attribute = 'Shib-Grouper-Roles'

Sets the separator for the grouper attribute to a comma

grails.plugins.springsecurity.shibboleth.roles.separator = ','

Tells the plugin to prefix all roles with 'SHIB_', for example, 'students' would become 'ROLE_SHIB_students'

grails.plugins.springsecurity.shibboleth.roles.prefix = 'SHIB_'

This maps IdPs to authentication methods to allow for security annotations for securing based on originating IdP server. In this example, the U of MN, and Northwestern University out of Chicago are assigned different roles.

grails.plugins.springsecurity.shibboleth.identityProvider.roles = [
    'ROLE_IDP_UMN': 'https://idp2.shib.umn.edu/idp/shibboleth',
    'ROLE_IDP_NORTHWESTERN_U': 'https://fed.it.northwestern.edu/shibboleth-idp/SSO' ]

This maps roles to authentication methods to allow for security annotations for securing based on method, this example is to assigne a role for Two-Factor Auth (M-Key)

grails.plugins.springsecurity.shibboleth.authenticationMethod.roles = [
    'ROLE_AUTH_METHOD_STANDARD': 'urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified',
    'ROLE_AUTH_METHOD_UMN_MKEY': 'https://www.umn.edu/shibboleth/classes/authncontext/mkey' ]

Allow location based roles. In this example, the first role assigns the role VPN from IP addresses coming from the VPN pool. The second tells the app the user is on campus, the last tells the app if the user is coming in from within the department.

grails.plugins.springsecurity.remoteAddress.roles = [
    'ROLE_IP_UMN_VPN': ['134.84.0.0/23'],
    'ROLE_IP_UMN_CAMPUS': ['160.94.0.0/16', '128.101.0.0/16', '134.84.0.0/16'],
    'ROLE_IP_UMN_DEPT': ['160.94.111.0/25', '128.101.11.222/25', '134.84.111.222/26'] ]

A Sample Configuration

What follows is a complete example configuration from grails-app/conf/Config.groovy.

// Used by Controllers grails.plugins.springsecurity.shibboleth.loginUrl = '/Shibboleth.sso/Login?target={0}' grails.plugins.springsecurity.shibboleth.logoutUrl = '/Shibboleth.sso/Logout'

// Token Attributes grails.plugins.springsecurity.shibboleth.principalUsername.attribute = 'EPPN' grails.plugins.springsecurity.shibboleth.authenticationMethod.attribute = 'Shib-AuthnContext-Method' grails.plugins.springsecurity.shibboleth.identityProvider.attribute = 'Shib-Identity-Provider' grails.plugins.springsecurity.shibboleth.authenticationInstant.attribute = 'Shib-Authentication-Instant'

// Used by Authentication Provider grails.plugins.springsecurity.shibboleth.roles.attribute = null grails.plugins.springsecurity.shibboleth.roles.separator = ',' grails.plugins.springsecurity.shibboleth.roles.prefix = 'SHIB_' grails.plugins.springsecurity.shibboleth.extraAttributes = [ 'uid', 'Shib-Session-Index', 'Shib-Session-ID', 'Shib-AuthnContext-Class', 'Shib-Application-ID' ]

// This maps IdPs to authentication methods to allow for security annotations // for securing based on originating IdP server grails.plugins.springsecurity.shibboleth.identityProvider.roles = [ 'ROLE_IDP_UMN': 'https://idp2.shib.umn.edu/idp/shibboleth', 'ROLE_IDP_NORTHWESTERN': 'https://fed.it.northwestern.edu/shibboleth-idp/SSO', 'ROLE_IDP_UMNTEST': 'https://idp-test.shib.umn.edu/idp/shibboleth' ]

// This maps roles to authentication methods to allow for security annotations // for securing based on method grails.plugins.springsecurity.shibboleth.authenticationMethod.roles = [ 'ROLE_AUTH_METHOD_STANDARD': 'urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified', 'ROLE_IP_UMN_DEPT': ['160.94.111.0/25', '128.101.11.222/25', '134.84.111.222/26'] ]

<< 3Installation

5Troubleshooting >>