User Tools

Site Tools


Configure SAML Authentication

Introduction to SAML

The Security Assertion Markup Language or SAML is an XML-based data format for exchanging authentication and authorization data between an 'identity provider' and a 'service provider'.

The most important requirement that SAML addresses is web browser 'single sign-on' or SSO. Single sign-on allows a user to login with a single ID and password to gain access to a connected system or several systems without using different usernames or passwords. (https://en.wikipedia.org/wiki/SAML)

Instructions to configure SAML SSO for EASA

Troubleshooting


Instructions to configure SAML SSO for EASA

Prior to configuring SAML on EASA insure that HTTPS is enabled.

Modify EASA parameters

1. Edit: <SERVERDATA>\easa\admin\config\Authentication.properties

  • Comment out (ie. prepend a ' # ' to the line with the property): AuthenticationClass = backend.DefaultAuthenticator
  • Uncomment the block (ie. remove initial ' # ' from the line with the property):
    AuthenticationClass = com.easa.custom.auth.sso.saml.SAMLSSOAuthenticator
  • Save the file

2. Edit: <SERVERDATA>\easa\admin\config\auth.properties

  • Change the default admin user, set ' admin.user ' property to a valid user
  • Change ' create.user ' property to true
  • Change ' default.group ' property to the desired EASA user group
  • Save the file

3. Edit <EASAROOT>\webapps\easa\WEB-INF\web.xml

  • Uncomment the section relevant to SAML SSO by removing the <!-- and --> tags (below)
  • Save the file
<!-- <context-param>
  <param-name>contextConfigLocation</param-name>
  <param-value>
    /WEB-INF/spring-security-context.xml
  </param-value>
</context-param>

<filter>
  <filter-name>springSecurityFilterChain</filter-name>
  <filter-class>
  *org.springframework.web.filter.DelegatingFilterProxy
  </filter-class>
</filter>
<filter-mapping>
  <filter-name>springSecurityFilterChain</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

<listener>
  <listener-class>
    org.springframework.web.context.ContextLoaderListener
  </listener-class>
</listener> -->

Identity provider metadata from a file

4. If the identity provider’s metadata comes from a file then:

  • Upload that file to the EASA Server

5. Edit: <EASAROOT>\webapps\easa\WEB-INF\spring-security-context.xml

  • In the 'SSO User Configuration' section: uncomment the following FilesystemMetadataProvider bean,
<!-- <bean class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
  <constructor-arg>
    <value type="java.io.File">/usr/local/metadata/idp.xml</value>
  </constructor-arg>
  <property name="parserPool" ref="parserPool"/>
</bean> -->

6. Replace '/usr/local/metadata/idp.xml' with the full path of the identity provider’s metadata file.

7. Comment out the following HTTPMetadataProvider bean,

  • Enclose the block below in <!-- and --> tags…
<bean class="org.opensaml.saml2.metadata.provider.HTTPMetadataProvider">
  <constructor-arg>
    <value type="java.lang.String">https://idp.ssocircle.com/idp-meta.xml</value>
  </constructor-arg>
  <constructor-arg>
    <value type="int">5000</value>
  </constructor-arg>
  <property name="parserPool" ref="parserPool"/>
</bean>

Identity provider metadata from an URL

8. If the identity provider’s metadata comes from an URL, then:

  • Edit: <EASAROOT>\webapps\easa\WEB-INF\spring-security-context.xml
  • In the SSO User Configuration section, uncomment (if commented out) the HTTPMetadataProvider bean, above.
  • Replace: https://idp.ssocircle.com/idp-meta.xml
    With a valid URL that contains the identity provider’s metadata.

9. Comment out (if uncommented) the FilesystemMetadataProvider bean below.

  • Enclose the block below in <!-- and --> tags…
<bean class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
  <constructor-arg>
    <value type="java.io.File">/usr/local/metadata/idp.xml</value>
  </constructor-arg>
  <property name="parserPool" ref="parserPool"/>
</bean>

SAML assertion attributes

10. In the following samlUserDetailsService bean….

  • Complete the following four properties with their correct SAML assertion attributes:
    usernameAttribute
    firstNameAttribute
    lastNameAttribute
    emailAttribute
<bean id="samlUserDetailsService" 
     class="com.easa.custom.auth.sso.saml.AttributeSAMLUserDetailsService">
    <!-- If below is empty the NameID will be used -->
  <property name="usernameAttribute" value=""/> 
    <!-- Below optional -->
    <!-- Firstname may be first or full name -->
  <property name="firstNameAttribute" value="FirstName"/> 
  <property name="lastNameAttribute" value="LastName"/>
  <property name="emailAttribute" value="EmailAddress"/>
</bean>

Multiple EASA machines

11. If there is more than one EASA machine then each machine will need its own entityId in their metadata.

  • Change the entityID property value=com.easa.sso1 in the following MetadataGenerator bean to a unique name
<bean id="metadataGeneratorFilter" 
    class="org.springframework.security.saml.metadata.MetadataGeneratorFilter">
  <constructor-arg>
    <bean class="org.springframework.security.saml.metadata.MetadataGenerator">
      <property name="entityId" value="com.easa.sso1"/>
    </bean>
  </constructor-arg>
</bean>

Custom URL for EASA access

12. If an explicit domain name will be used in the URL used to access the EASA site,

  • The URL must be specified by adding a new property (below) to the above MetadataGenerator bean…
  • Substitute the appropriate domain name for myeasa : <property name="entityBaseURL" value="https://myeasa/easa"/>
  • Save the file

13. Once SAML SSO has been configured, restart the EASA Server.

14. In a browser enter the URL: <protocol>://<hostname>:<port>/easa/saml/metadata

15. Download the file (this is EASA’s service provider metadata for this machine).

This metadata file needs to be added to the identity provider.


Change the default 7200sec user-timeout length

  • If the default timeout is exceeded,
  • The user may be presented with a blank browser window
  • The logs may show the following Exceptions:
    org.springframework.security.authentication.CredentialsExpiredException
       Authentication statement is too old to be used with value… [time stamp]
    org.opensaml.common.binding.security.SAMLProtocolMessageXMLSignatureSecurityPolicyRule
       SAML protocol message was not signed, skipping XML signature processing
  • Modify the property below to change the authentication timeout,
    <bean id=“webSSOprofileConsumer” class=“org.springframework.security.saml.websso.WebSSOProfileConsumerImpl”>
       <property name=“maxAuthenticationAge” value=“some_number_other_than_7200”/>
    </bean>

Troubleshooting

ADFS complains about 'signature trust failure'

For reason's beyond our control ADFS will give a message, Signature trust establishment failed for metadata entry… with Java 7.

There is a workaround to turn off the metadata trust check as follows:

  • Edit: <SERVERDATA>\webapps\easa\WEB-INF\spring-security-context.xml
  • Replace the xml block below with the second xml block (replace C:/…<EASAROOT> with the actual path prefix)
  • Find,
<bean class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
  <constructor-arg>
  <value type="java.io.File">C:/...<EASAROOT>/webapps/easa/WEB-INF/FederationMetadata.xml</value>
  </constructor-arg>
  <property name="parserPool" ref="parserPool"/>
</bean>
  • Replace with,
<bean class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
  <constructor-arg>
    <bean class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
    <constructor-arg>
      <value type="java.io.File">C:/...<EASAROOT>/webapps/easa/WEB-INF/FederationMetadata.xml</value>
    </constructor-arg>
    <property name="parserPool" ref="parserPool"/>
    </bean>
  </constructor-arg>
  <constructor-arg>
    <bean class="org.springframework.security.saml.metadata.ExtendedMetadata"/>
  </constructor-arg>
  <property name="metadataTrustCheck" value="false"/>
</bean>

Exceptions

SSLPeerUnverifiedException

  • In the case of:
    javax.net.ssl.SSLPeerUnverifiedException: SSL peer failed hostname validation for name: null…
  • Modify the following MetadataGeneratorFilter bean to the one below it,
    (ie. Add a new extendedMetadata property with the new element bean, ExtendedMetaData)
  • Find,
<bean id="metadataGeneratorFilter" 
     class="org.springframework.security.saml.metadata.MetadataGeneratorFilter">
  <constructor-arg>
    <bean class="org.springframework.security.saml.metadata.MetadataGenerator">
      <property name="entityId" value="com.easa.sso"/>
    </bean>
  </constructor-arg>
</bean>
  • Replace with,
<bean id="metadataGeneratorFilter" 
    class="org.springframework.security.saml.metadata.MetadataGeneratorFilter">
  <constructor-arg>
    <bean class="org.springframework.security.saml.metadata.MetadataGenerator">
      <property name="entityId" value="com.easa.sso"/>
      <property name="extendedMetadata">
        <bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
          <property name="sslHostnameVerification" value="allowAll"/>
        </bean>
      </property>
    </bean>
  </constructor-arg>
</bean>
  • Save the file.
  • Recreate the metadata file, remove the old one, and add the new file to the identity provider.

SAMLException

  • In the case of:
    org.opensaml.common.SAMLException: Response issue time is either too old or with date in the future…
  • Modify the following WebSSOProfileConsumerImpl <bean/> to look like the one below it,
    (ie. Add and set a number of seconds in the responseSkew property)
  • Find,
<bean id="webSSOprofileConsumer" 
   class="org.springframework.security.saml.websso.WebSSOProfileConsumerImpl"/>
  • Replace with,
<bean id="webSSOprofileConsumer" 
   class="org.springframework.security.saml.websso.WebSSOProfileConsumerImpl">
      <property name="responseSkew" value="180"/>
</bean>
  • Save the file
  • If the exception persists, then,
    Increase the number of seconds in the responseSkew property
    Check again, adjust the value until it works.

XMLParseException

  • Copy the identity provider metadata file locally.
  • Identify and fix the broken XML so that it is valid.
  • Follow steps 4 - 7 above (“identity provider metadata from a file”)