Package com.avoka.tm.security

Class Saml2Parser

  • public class Saml2Parser
extends Object

    Provides a SAML2 (Security Assertion Markup Language) response parser - a helper class for SSO Filter / Security Manager Get SSO Auth Token script.

    A SAML2 Response is sent by an Identity Provider (like Microsoft ADFS server) to a Service Provider (TM). The Identity Provider http POST as SAML Response to TM (Service Provider) receives the SAML token as HttpServletRequest request parameter. The parser first Base64 decodes the SAML response converting the raw response to XML. Note the response structure varies greatly from different types of Identity Providers software and the way they are configured.

    Saml2Parser Usage

    Example 1 and 2 demostrate the use of the parser.

    There is a static convenience method has SAMLResponse(request). Requests that don't have a SAMLResponse may be redirected back to the Identity Provider.

    A parser is constructed using new Saml2Parser() then chains Fluent style properties setters. These properties include setting the validation certificate and the keystore holding the private encryption key. In a live TM system these are configured in the associated Security Manager's Certificates tab.

    Processing checks are run to validate the SAML response. By default the class will try to run all the checks. If your token has Assertion Signatures but no Response Signature then use skip skipResonseSignatureValidation(), see example 2 below. It is possible for unit testing to save a SAMLResponse captured in Chrome Tools or this tool. The issue with using this response to run a test in the future it will fail because of the timestamp checks. To get it working will have to skip a number the date checks listed in the table below.

    Once you have completed calling the setters and skip method you can call parse(request). This validates the class has been setup correctly and if configured incorrectly will throw an IllegalArgumentException. Otherwise it will try validating and parsing the SAMLResponse, returning a Saml2ParserResult which if successful result.isValid will contain an result.ssoAuthToken. The SsoAuthToken holds the user attributes (name, email, groups etc) parsed from the SAML Token. It is returned by the Security Manager Get SSO Auth Token script.

    Logging

    The Saml2ParserResult provides the following properties which are useful for troubleshooting:

    • responseRaw: The raw SAMLResponse (String) taken from the request parameter. This can be useful for debug the Saml2Parser in a separate unit test.
    • responseBase64: The SAMLResponse XML (String) after it has been Base64 decoded. This is useful to inspect the
    • error: This will be present when result.isValid is false, it will be null when result.isValid is true. It holds the Throwable error that occurred during validation and parsing. The error can be inspected to the cause of failure. The SecurityLogger can log this error and display the failure message and stack trace.
    • infoLog: A summary level log that records when higher level sections have been started or completed. Use the Security Logger to store this log. Below is a Sample info log. 
       Start parse()
 Start validateAndParse()
 Skipping ResponseSignatureValidation
 pre: responseSucessfulValidation(response
 Skipping responseDateCheck
 Assertion signature validated
 Skipping AssertionConditionCheck
 Skipping assertionAuthnStatementCheck
 Skipping assertionSubjectCheck
 Execution Duration(ms): 16
    • debugLog: A detailed level log in text format, includes all the info log plus a lot of logging in the validation and parsing. Below shows some of the extra detail captured in the detail log. 
       New AttributeStatement
 parseAttributeStatements(): unencrypted attribute.getName() http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
 parseAttributeStatements(): unencrypted attribute.getName() http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
 parseAttributeStatements(): unencrypted attribute.getName() http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
 parseAttributeStatements(): unencrypted attribute.getName() http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
 parseAttributeStatements(): unencrypted attribute.getName() http://schemas.xmlsoap.org/claims/Group
 parseAttributeStatements(): unencrypted attribute.getName() http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname
 unencrypted attributes added for AttributeStatement
 Finished adding encrypted attributes for AttributeStatement
 Start parseAttributes(
 getSSOAuthToken() XMLObject getFirstChild().getTextContent(): peter
 getSSOAuthToken() XMLObject getFirstChild().getTextContent(): [email protected]
 getSSOAuthToken() XMLObject getFirstChild().getTextContent(): panda
 getSSOAuthToken() XMLObject getFirstChild().getTextContent(): [email protected]
 getSSOAuthToken() XMLObject getFirstChild().getTextContent(): CN=TransactionManagerAccess,OU=Group,OU=Marketing,DC=test,DC=avoka,DC=com
 getSSOAuthToken() XMLObject getFirstChild().getTextContent(): peter.panda
 parseAssertions(): subject not encryptedparseAssertions(): NameID=org.opensaml.saml.saml2.core.impl.NameIDImpl@2e11485, NameID.getValue=:peter.panda
 Execution Duration(ms): 16

    By default the Saml2Parser does not do any logging direct to the TM or server logs. Use the SecurityLogger to capture these properties. You must explicitly add the output to the SecurityLogger (logger.info result.responseRaw) as per Example 1 below.

    Example 1

    This is called by the Security Manager Get SSO Auth Token script

     import com.avoka.core.groovy.SecurityLogger as logger

 import com.avoka.tm.security.*
 import com.avoka.fc.core.util.RedirectUtils
 import com.avoka.fc.core.util.PortalUtils
 import com.avoka.fc.core.entity.SecurityManager
 import com.avoka.fc.core.util.RedirectUtils

 // Stores the Entry URL into the session which is used by the Auth Ok Response Script.
 if (!Saml2Parser.hasSamlToken(request)) {
     logger.info "No SAML Token, Storing sessionEntryUrl and redirecting to ADFS server"
     RedirectUtils.storeSessionEntryUrl(request)
     return null
 }

 Saml2ParserResult result = new Saml2Parser()
                          .setValidationCertData(securityManager.getSsoValidatorCertData())
                          .setKeystoreData(securityManager.getSsoKeystoreData())
                          .setKeystorePassword(securityManager.getSsoKeystorePassword())
                          .setPrivateKeyAlias(securityManager.getSsoPrivateKeyAlias())
                          .setPrivateKeyPassword(securityManager.getSsoPrivateKeyPassword())
                          .setGroupAttribName("http://schemas.xmlsoap.org/claims/Group")
                          .setRPIdentifier("https://{TM_Server_IP}/{PORTAL_Context}")
                          .parse(request)

 if (result.isValid) {
     return result.ssoAuthToken

 } else {
      logger.debug result.debugLog
      logger.debug result.responseRaw
      logger.info result.validationErrors.join("\n")

      logger.info "Redirecting to " + PortalUtils.getNotAuthorizedPath(portal)
      throw new RedirectException(PortalUtils.getNotAuthorizedPath(portal))
 }

    Example 2

    This Groovy example shows how to bypass a some of the inbuilt checking when parsing the SAMLToken

     Saml2ParserResult result = new Saml2Parser()
                          .setValidationCertData(securityManager.getSsoValidatorCertData())
                          .setKeystoreData(securityManager.getSsoKeystoreData())
                          .setKeystorePassword(securityManager.getSsoKeystorePassword())
                          .setPrivateKeyAlias(securityManager.getSsoPrivateKeyAlias())
                          .setPrivateKeyPassword(securityManager.getSsoPrivateKeyPassword())
                          .setGroupAttribName("http://schemas.xmlsoap.org/claims/Group")
                          .setRPIdentifier("https://{TM_Server_IP}/{PORTAL_Context}")
                          .setUrlDecodeResponse()
                          .skipRequireEncryption()
                          .skipResponseDateCheck()
                          .skipAssertionSubjectCheck()
                          .skipAssertionAuthnStatementCheck()
                          .skipAssertionConditionCheck()
                          .skipAssertionSignatureValidation()
                          .parse(request)

    SAML Token Structure

    Example SAML2 Tokens can be found on www.samltool.com.

    The following table show is the XML Node Hierarchy of the SAML Response 

     Node Heirachy                                Description                                     Skip Method
 ----------------------------------------------------------------------------------------------------------------------------------------------------------------
 Response                                     Attr: IssueInstant tstamp                       skipResponseDateCheck()
                                                    Destination                               skipDestinationEndpointCheck()

     Signature (optional):                    Signature for the whole response.               skipResonseSignatureValidation()

     Issuer                                   Issuing server url eg ADFS server

     Assertion (List):                        Holder for the user details.
                                              Normally Encrypted.                             skipRequireEncryption()

         Signature (optional):                The signature for the assertion.                skipAssertionSignatureValidation()

         Issuer:                              url of the issuing server

         Subject:
             NameID                           This gets written to ssoAuthToken.username
             SubjectConfirmation
                 SubjectConfirmationData      Attr:  notOnOrAfter (tstamp)                    skipAssertionSubjectCheck()
                                              recipient should be the same as RPIdenifier     skipDestinationEndpointCheck()

         Conditions:                          Attr:  notBefore and notOnOrAfter (tstamp)      skipAssertionConditionCheck()
             AudienceRestriction
                 Audience (List):             Check Relying Party Identity in List            skipAssertionConditionCheck() also requires parser.setRPIdentifier()

         AttributeStatement
             Attribute (List):                Contains the details for each user attrib.

         AuthnStatement                       Attr: NotOnOrAfter tstamp                       skipAssertionAuthnStatementCheck()
                                                    IssueInstant
    Since:
    5.1.4

    • Field Detail

      • REQUEST_PARAM_SAML_RESPONSE

        protected static final String REQUEST_PARAM_SAML_RESPONSE
        The SAMLResponse - Request Parameter Name.
        See Also:
        Constant Field Values

    • Constructor Detail

      • Saml2Parser

        public Saml2Parser()

    • Method Detail

      • hasSamlToken

        public static boolean hasSamlToken​(HttpServletRequest request)
        Returns true if the request has a SAML2 SAMLRequest or SAMLResponse request parameters.
        Parameters:
        request - the HttpServletRequest Containing the SAMLResponse (required)
        Returns:
        true if has a SAMLRequest or SAMLResponse request parameter

      • setValidationCertData

        public Saml2Parser setValidationCertData​(byte[] validatorCertData)
        Sets the token signing certificate used for validating the SAML2 Signature.
        Parameters:
        validatorCertData - byte[] the certificate used for validating the SAML2 Signature (Optional)
        Returns:
        the Saml2Parser

      • setKeystoreData

        public Saml2Parser setKeystoreData​(byte[] keystoreData)
        Sets the keystore that holds the private key and public Certificate keys.
        Parameters:
        keystoreData - byte[] that holds the private key and keys (Optional)
        Returns:
        the Saml2Parser

      • setKeystorePassword

        public Saml2Parser setKeystorePassword​(String keystorePassword)
        Sets the keystore password.
        Parameters:
        keystorePassword - String
        Returns:
        the Saml2Parser

      • setPrivateKeyAlias

        public Saml2Parser setPrivateKeyAlias​(String privateKeyAlias)
        Sets the Private Key Alias for the keystore.
        Parameters:
        privateKeyAlias - String
        Returns:
        the Saml2Parser

      • setPrivateKeyPassword

        public Saml2Parser setPrivateKeyPassword​(String privateKeyPassword)
        Sets the Private Key Password.
        Parameters:
        privateKeyPassword - String
        Returns:
        the Saml2Parser

      • setRPIdentifier

        public Saml2Parser setRPIdentifier​(String rpIdentifier)
        Sets the Relying Party Identifier used by the security manager.
        Parameters:
        rpIdentifier - (Optional) String for this space / environment and eg https://tm.server.com/sso
        Returns:
        the Saml2Parser

      • setGroupAttribName

        public Saml2Parser setGroupAttribName​(String groupAttribName)
        Sets the Group Attribute Name.
        If the SAML2 attribute parser has groupAttributeName configured then the SSOAuthenticationToken will any parsed groups as Spring GrantedAuthoritys.
        Parameters:
        groupAttribName - String
        Returns:
        the Saml2Parser

      • setDestinationEndpoint

        public Saml2Parser setDestinationEndpoint​(String destinationEndpoint)
        Sets the DesinationEndpoint for Response Destination attribute and Assertion Subject. SubjectConfirmationData recipient attribute.

        Used for unit testing, This value that is normally used is request.getRequestURL()

        Parameters:
        destinationEndpoint - the destinationEndpoint to set.
        Returns:
        the Saml2Parser

      • setUrlDecodeResponse

        public Saml2Parser setUrlDecodeResponse()
        Specify whether to URL decode the SAML response befpre Base64 decoding.
        Returns:
        the Saml2Parser

      • skipRequireEncryption

        public Saml2Parser skipRequireEncryption()
        Specify whether to skip the encryption requirement and allow an unencypted SAML token to be parsed.
        Returns:
        the Saml2Parser

      • skipResponseSignatureValidation

        public Saml2Parser skipResponseSignatureValidation()
        Specify whether to skip the execution of the Response Signature Validation.
        Returns:
        the Saml2Parser

      • skipResponseDateCheck

        public Saml2Parser skipResponseDateCheck()
        Specify whether to skip the execution of the Response Date Check on the Response:@IssueInstant timestamp attribute.
        Returns:
        the Saml2Parser

      • skipAssertionSignatureValidation

        public Saml2Parser skipAssertionSignatureValidation()
        Specify whether to skip the execution of the Assertion Signature Validation checks.
        Returns:
        the Saml2Parser

      • skipAssertionAuthnStatementCheck

        public Saml2Parser skipAssertionAuthnStatementCheck()
        Specify whether to skip the execution of the Assertion AuthnStatment checks.
        Returns:
        the Saml2Parser

      • skipAssertionConditionCheck

        public Saml2Parser skipAssertionConditionCheck()
        Specify whether to skip the execution of checks associated with the Assertion Condition.
        Returns:
        the Saml2Parser

      • skipAssertionSubjectCheck

        public Saml2Parser skipAssertionSubjectCheck()
        Specify whether to skip the execution of checks associated with the Assertion Subject.
        Returns:
        the Saml2Parser

      • skipDestinationEndpointCheck

        public Saml2Parser skipDestinationEndpointCheck()
        Specify whether to skip the execution of checks associated with the Response. Destination attribute and the Assertion SubjectConfirmationData recipient.
        Returns:
        the Saml2Parser

      • parse

        public Saml2ParserResult parse​(HttpServletRequest request)
        Parse the SAMLResponse from the given POST request.
        Parameters:
        request - the servlet request which contains the SAML Token (required)
        Returns:
        the Saml2ParserResult