Class Saml2Parser
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 Summary
Modifier and TypeFieldDescriptionprotected static final String
The SAMLResponse - Request Parameter Name. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic boolean
hasSamlToken
(jakarta.servlet.http.HttpServletRequest request) Returns true if the request has a SAML2 SAMLRequest or SAMLResponse request parameters.parse
(jakarta.servlet.http.HttpServletRequest request) Parse the SAMLResponse from the given POST request.setDestinationEndpoint
(String destinationEndpoint) Sets the DesinationEndpoint for Response Destination attribute and Assertion Subject.setGroupAttribName
(String groupAttribName) Sets the Group Attribute Name.setKeystoreData
(byte[] keystoreData) Sets the keystore that holds the private key and public Certificate keys.setKeystorePassword
(String keystorePassword) Sets the keystore password.setPrivateKeyAlias
(String privateKeyAlias) Sets the Private Key Alias for the keystore.setPrivateKeyPassword
(String privateKeyPassword) Sets the Private Key Password.setRPIdentifier
(String rpIdentifier) Sets the Relying Party Identifier used by the security manager.Specify whether to URL decode the SAML response befpre Base64 decoding.setValidationCertData
(byte[] validatorCertData) Sets the token signing certificate used for validating the SAML2 Signature.Specify whether to skip the execution of the Assertion AuthnStatment checks.Specify whether to skip the execution of checks associated with the Assertion Condition.Specify whether to skip the execution of the Assertion Signature Validation checks.Specify whether to skip the execution of checks associated with the Assertion Subject.Specify whether to skip the execution of checks associated with the Response.Specify whether to skip the encryption requirement and allow an unencypted SAML token to be parsed.Specify whether to skip the execution of the Response Date Check on the Response:@IssueInstant timestamp attribute.Specify whether to skip the execution of the Response Signature Validation.
-
Field Details
-
REQUEST_PARAM_SAML_RESPONSE
The SAMLResponse - Request Parameter Name.- See Also:
-
-
Constructor Details
-
Saml2Parser
public Saml2Parser()
-
-
Method Details
-
hasSamlToken
public static boolean hasSamlToken(jakarta.servlet.http.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
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
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
Sets the keystore password.- Parameters:
keystorePassword
- String- Returns:
- the Saml2Parser
-
setPrivateKeyAlias
Sets the Private Key Alias for the keystore.- Parameters:
privateKeyAlias
- String- Returns:
- the Saml2Parser
-
setPrivateKeyPassword
Sets the Private Key Password.- Parameters:
privateKeyPassword
- String- Returns:
- the Saml2Parser
-
setRPIdentifier
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
Sets the Group Attribute Name.
If the SAML2 attribute parser has groupAttributeName configured then theSSOAuthenticationToken
will any parsed groups as SpringGrantedAuthority
s.- Parameters:
groupAttribName
- String- Returns:
- the Saml2Parser
-
setDestinationEndpoint
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
Specify whether to URL decode the SAML response befpre Base64 decoding.- Returns:
- the Saml2Parser
-
skipRequireEncryption
Specify whether to skip the encryption requirement and allow an unencypted SAML token to be parsed.- Returns:
- the Saml2Parser
-
skipResponseSignatureValidation
Specify whether to skip the execution of the Response Signature Validation.- Returns:
- the Saml2Parser
-
skipResponseDateCheck
Specify whether to skip the execution of the Response Date Check on the Response:@IssueInstant timestamp attribute.- Returns:
- the Saml2Parser
-
skipAssertionSignatureValidation
Specify whether to skip the execution of the Assertion Signature Validation checks.- Returns:
- the Saml2Parser
-
skipAssertionAuthnStatementCheck
Specify whether to skip the execution of the Assertion AuthnStatment checks.- Returns:
- the Saml2Parser
-
skipAssertionConditionCheck
Specify whether to skip the execution of checks associated with the Assertion Condition.- Returns:
- the Saml2Parser
-
skipAssertionSubjectCheck
Specify whether to skip the execution of checks associated with the Assertion Subject.- Returns:
- the 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
Parse the SAMLResponse from the given POST request.- Parameters:
request
- the servlet request which contains the SAML Token (required)- Returns:
- the Saml2ParserResult
-