How we configured SAML 2.0 on GRAILS

The aim of this article is to configure Service Provider (SP) in grails application for SAML 2.0 identity provider (idP) on SSO server. OpenAM SSO server will be used as idP. Grails application with grails-spring-security-saml plugin will be used as SP.

Some Theory

Security Assertion Markup Language (SAML) is an XML-based open standard data format for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider.

The only and the most important requirement is that SAML addresses are  web browser single sign-on (SSO). Single sign-on solutions are common at the intranet level (using cookies, for example) but extending these solutions beyond the intranet has been problematic and has led to the proliferation of non-interoperable proprietary technologies.

The SAML specification defines three roles: the principal (typically a user), the identity provider (IdP), and the service provider (SP). In the use case addressed by SAML, the principal requests a service from the service provider. The service provider requests and obtains an identity assertion from the identity provider.

Before delivering the identity assertion to the SP, the IdP may request some information from the principal – such as a username and password – in order to authenticate the principal. SAML specifies the assertions between the three parties: in particular, the messages that assert identity that are passed from the IdP to the SP. In SAML, one identity provider may provide SAML assertions to many service providers. Similarly, one SP may rely on and trust assertions from many independent IdPs.

(http://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) 

Configure OpenAM (identity provider)

• Download OpenAM, deploy OpenAM.war on tomcat. Perform installation on server url
  1. Create Custom Configuration with OpenAM User Data Store as User Data Store Settings
  2. Login as amAdmin user

• Key generation for OpenAM server OpenAM is supplied with a default keystore, it’s recommended to create your own keystore with an own signing key
  1. Generate a new key and keystore (skip if you have one already):

               
               keytool -genkeypair -alias mykey -keyalg RSA -keysize 1024 -validity 365 -storetype JKS -keystore keystore.jks
               
             

  2. Now you need to encrypt your passwords (keystore and private key) with SSOAdm for ability to use them with OpenAM:

               
                 openam/bin/ampassword -e .keypass  # for private key
                 openam/bin/ampassword -e .storepass # for keystore
               
             

  3. Move the new files (keystore.jks, .storepass, .keypass) to ~/openam/openam folder and override the previous ones
  4. Restart OpenAM

• Configure IDP
  1. Create a new Realm1 in Access Control tab. Add new users in Subjects of realm.
  2. Make sure that the email field is not empty. Email will be used for authorization.
  3. Create new Circle of Trust (COT) in Federation tab. Add Realm1 to created Circle of Trust.
  4. Press “Create hosted Identity Provider” on main page.
  5. Fill the following fields: Realm: Realm1, Name: http://localhost:8090/OpenAMIdp, Existing Circle of Trust: COT, Signing Key: choose key added in previous step.
  6. Now you can download xml file with idP metadata on url: http://localhost:8090/OpenAM/saml2/jsp/exportmetadata.jsp?entityid=http://localhost:8090/OpenAMIdp&realm=/Realm1.

Install and configure grails-spring-security-saml plugin

• Install plugin grails-spring-security-saml by adding it in BuildConfig.groovy:

            
              plugins {
                ...
                compile ":spring-security-saml:1.0.0.M20"
                ...
            
     

• Accept idP certificate:

            
              keytool -import -alias myIdp -keystore samlKeystore.jks -file Idp.cer
            
      

• Generate Key for SP:

            
              keytool -genkey -alias apollo -keyalg RSA -keystore samlKeystore.jks
            
      

  Java keytool commands: List keys:

            
              keytool -list -v -keystore samlKeystore.jks
            
      

  Delete key:

            
              keytool -delete -alias badKey -keystore samlKeystore.jks
            
      

• Configure plugin. We need to configure the plugin for ability to use our keystore and the keys we have generated. In Config.groovy we set the needed properties.
  1. General Settings

               
                 grails.plugins.springsecurity.saml.active=true
                 grails.plugins.springsecurity.saml.responseSkew=300
                 grails.plugins.springsecurity.saml.active=true
                 grails.plugins.springsecurity.saml.responseSkew=300 //Specifies the maximum permitted time between the timestamps in the SAML Response and the clock on the Jive instance.
                 grails.plugins.springsecurity.saml.afterLoginUrl = '/'
                 grails.plugins.springsecurity.saml.afterLogoutUrl = '/search'
                 grails.plugins.springsecurity.saml.metadata.url = '/saml/metadata'
               
     

  2. Auto created settings

               
                 grails.plugins.springsecurity.saml.autoCreate.active = true  //If you want the plugin to generate users in the DB as they are authenticated via SAML
                 grails.plugins.springsecurity.saml.autoCreate.assignAuthorities=true  //If you want the plugin to assign the authorities that come from the SAML message.
               
     

  3. Key manager settings

               
                 grails.plugins.springsecurity.saml.keyManager.storeFile = 'classpath:security/samlKeystore.jks'
                 grails.plugins.springsecurity.saml.keyManager.storePass = 'nalle123'
                 grails.plugins.springsecurity.saml.keyManager.passwords = [ apollo: 'nalle123' ]
                 grails.plugins.springsecurity.saml.keyManager.defaultKey = 'apollo'
               
     

• Generate Metadata. Generate SP metadata with the help of saml plugin. Run application. There is a UI available as the metadata controller (http://localhost:8080/myApp/metadata). After metadata is generated, you have to save sp.xml for the ability to reference it in your config. Store for the current session: it has to be “yes”. Otherwise, it doesn’t allow the download of the metadata There are a lot of options with S Entity base URL: URL of the public app Entity alias: you can make it unique. It is used SP server, when you are generating more than one file without restarting the server. Include Idp Discovery: turn it off, if Idp doesn’t support it SSO Bindings: select which bindings to support. In case of OpenAM, all 3 bindings are supported Entity ID: we use the url of the metadata file Security profile: define the way of signing and encryption of verification. It is recommended to select MetaIOP igning key: use generated key «apollo» Encryption key: use generated key «apollo» SSL/TLS key: use generated key «apollo» And more settings: Sign metadata: true Require signed authentication Assertion: true Sign sent AuthNRequests: true Require signed LogoutRequest: true Require signed LogoutResponse: true Require signed ArtifactResolve: true
• Download and save sp.xml in grails-app/conf/security/folder. Copy ipd.xml, which we have generated on OpenAM server configuration, in the same folder. Add sp and idp settings in Config.groovy:

            
              grails.plugins.springsecurity.saml.metadata.sp.file = 'security/sp.xml'
              grails.plugins.springsecurity.saml.metadata.providers = [idp: 'security/idp.xml']
              grails.plugins.springsecurity.saml.metadata.defaultIdp = 'idp'
              grails.plugins.springsecurity.saml.metadata.sp.defaults = [
                  local: true,
                  alias: 'localSp',
                  securityProfile: 'metaiop',
                  signingKey: 'apollo',
                  encryptionKey: 'apollo',
                  requireArtifactResolveSigned: true,
                  requireLogoutRequestSigned: true,
                  requireLogoutResponseSigned: true
              ]
            
      

• Reload Grails application and open localhost:8080/myApp/metadata. Check idp and sp providers to be listed.

We configured SP.

Import and configure SP on OpenAM server

• First import certificates from SP:

            
              keytool -import -alias mySp -keystore keystore.jks -file sp.cer
            
      

• On main page select “Register Remote Service Provider”. Select Realm1 and upload generated sp.xml.

If grails SAML plugin still in development and there are no documentation, the best documentation is the source code.

Well that's all. We have set up, configured OpenAM server and configured Grails application to use SAML.

Links

• Using Grails Spring Security Saml Plugin http://slid.es/beckje01/saml
• grails-spring-security-saml plugin with sources http://grails.org/plugin/spring-security-saml https://github.com/fpanwaskar/grails-spring-security-saml
• Spring Security Core Plugin for grails and documentation http://grails.org/plugin/spring-security-core http://grails-plugins.github.io/grails-spring-security-core/docs/manual/guide/single.pdf
• OpenAM server http://forgerock.org/openam.html
• Spring Security SAML src/sample https://github.com/spring-projects/spring-security-saml