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)

• Modify EASA parameters (steps 1 - 3)

• Identity provider metadata from a file (steps 4 - 7)
     -or-
• Identity provider metadata from an URL (steps 8 - 9)

• SAML assertion attributes (step 10)
• Multiple EASA machines (step 11)
• Custom URL for EASA access (steps 12 - 15)
• Change the default 7200sec user-timeout length

• ADFS complains about 'signature trust failure'
• Exceptions
  SSLPeerUnverifiedException
  SAMLException
  XMLParseException

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

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> -->

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>

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>

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>

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>

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.

• 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>

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>

• 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.

• 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.

• 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”)