Troubleshooting SAML

The SAML authentication standard is a broad XML specification covering a range of functionality and ‘binding’ protocols. As such, it is not uncommon to encounter problems integrating applications (Service Provider’s) with SAML Identity Providers. Numerous technologies can form the SSO back-end (Identity Provider) and there is no ‘one-size-fits-all’ approach. If you have reviewed the main SAML documentation for integration in Appkit and are encountering problems, here we document tips and tricks picked up from previous installations. Because Appkit uses the Spring Security SAML extension for underlying SAML compliant client behavior, a useful reference is the Spring documentation.

Debugging

To enable detailed debugging, add this to your logback.xml file:

<logger name="org.opensaml" level="TRACE"/>
<logger name="org.springframework.security" level="TRACE"/>

You will now see the content of any SAML request and response messages, as well as a lot of extra debugging information. Also, if you suspect a certificate or SSL related error, you can start the JVM/Tomcat with this argument:

-Djava.net.debug=ssl

IdP rejects an authentication request (AutnRequest) from app

A range of issues could cause this. Most commonly, it is because the request from the application failed validation which is often due to the IdP lacking the correct configuration. You must ensure that the endpoints and application identifiers match in the IdP’s configuration for the application. For example if using ADFS, this is the ‘Relying Party Trust’ configuration. If manually configuring this is proves problematic, you can ensure that the IdP has the correct configuration for the app by generating an SP ‘metadata’ XML file that can be imported into the IdP. To enable this you must:

Add this to spring-security.xml in the filter chain:

<filter-chain pattern="/saml/metadata/**" filters="metadataDisplayFilter"/>

For example:

...
<filter-chain pattern="/saml/logout/**" filters="samlLogoutFilter"/>
<filter-chain pattern="/saml/metadata/**" filters="metadataDisplayFilter"/>
<filter-chain pattern="/saml/SSO/**" filters="samlWebSSOProcessingFilter"/>
...

Add the bean definition for this filter:

<!-- The filter is waiting for connections on URL suffixed with filterSuffix and presents SP metadata there -->
<beans:bean id="metadataDisplayFilter" class="org.springframework.security.saml.metadata.MetadataDisplayFilter"/>

Deploy the application and browse to http://your-app-server/saml/metadata/. This should generate the SP metadata XML file describing the applications configuration which can then be imported to almost any compliant IdP in the administration console/configuration.

After the issue is resolved in production, we recommend that you remove this filter because it exposes information about the authentication mechanism.

IdP rejects authentication or sends back a status code in response message indicating an error

It is worth inspecting the status code in the response message and the logs from the IdP as a next step. This issue is often found if the configuration matches at both the IdP and SP, but there is a ‘trust’ issue, which can be related to the signing certificates used. We have found some IdPs (ADFS for example) that reject self-signed certificates from the application. It is recommended to use a genuine trusted certificate to avoid this problem.

Illegal Key Size error

You might find you get an error at some stage that is a java.security.InvalidKeyException or similar stating ‘Illegal Key Size’. This is because a key has been used with a size larger than that which the JVM accepts by default. This is a known Java issue to do with cryptography restrictions shipped with a standard JVM. The solution is to install the ‘unrestricted JCE policy files’ in the JVM on which the application is running. You can obtain this from Oracle and it is usually installed in the JRE directory in lib/security. Make sure you install the files for the correct version of Java.

Fusion rejects a SAML assertion

There are a few reasons why Fusion might reject a SAML assertion. If you’re having issues:

Check that IdP Issuer matches <saml:Issuer> in the SAML payload.
Check that App Issuer matches <saml:Audience> in the SAML payload.
When using encrypted certificates, you must provide the X.509 key info in the SAML payload, which must match the Certificate Fingerprint in Fusion.

Refer to Configure Fusion for SAML for more information.

Configure Fusion for SAML

SAML 2.0 is a standard for exchanging authentication and authorization data between security domains. The SAML protocol allows web-browser single sign-on (SSO) through a sequence of messages sent to and from the browser, which is the intermediary between Fusion and the SAML authority acting as the Identity Provider (IdP).To configure Fusion to use SAML 2.0 for user authentication and authorization you must create a SAML security realm. In addition to configuring the Fusion security realm, you must configure the SAML identity provider to recognize the Fusion application.Once Fusion is configured for a SAML realm, this realm is added to the list of available realms on the initial Fusion sign-on panel. When the SAML realm is chosen from the list of available realms, the browser then redirects to the IdP which handles user authentication. Upon successful authentication, the IdP sends a response back to the browser which contains authentication and authorization information as well as the URL of the Fusion application. The browser redirects back to the Fusion URL, passing along the SAML message with the user authentication and authorization information. Fusion then issues as session cookie which is used for subsequent user access.

Add a Security Realm

In the Fusion workspace, navigate to System > Access Control.
Click Security Realms.
Click Add Security Realm.
Enter the following information for the new realm:
- Enter a Name. The name must be unique and should be descriptive yet short.
- Select saml from the Type pulldown menu.
When you select a type, Fusion displays additional configuration options.
- The default value for Enabled is true. This setting controls whether or not Fusion allows user logins for this security realm.
- The default value for Ephemeral Users is false. When disabled, this setting prevents ephemeral users from being created in ZooKeeper during login. If enabled, this property negates Auto Create Users.
- The default value for Auto Create Users is true. If enabled, a user account is created automatically upon initial authentication. If disabled, then a Fusion user with admin permissions must create Fusion users.

Under SAML Realm, configure the following information:
- Enter the Identity Provider URL. This URL is used by the SAML authority for single sign-on. For example: https://www.my-idp.com/<my-app-path>/sso/saml
  The URL format may differ depending on the SAML Identity Provider.
- Enter the URL of the IdP Issuer. For example: http://www.my-idp.com/exk686w2xi5KTuSXz0h7.
  - IdP Issuer must match <saml:Issuer> in the SAML payload.
- Optionally, provide the App Issuer. This field is required if there is an audienceRestriction in the SAML assertion and must match <saml:Audience> in the SAML payload.
- In the Certificate Fingerprint, paste the contents of the SAML authority certificate, without the certificate header and footer.
- Optional: Enter the User ID Attribute. By default, the Fusion username is the same as the login name known to the Identity Provider. When another field or attribute in the user record stored by the IdP should be used as the Fusion username, that attribute name is the value of the User ID Attribute.
- Optional: Provide a Post Login Redirect URL. If not set, the Fusion URL is used.
- Optional: Provide a Logout URL.
Optional: Under Groups Mapping, specify the Group Name Attribute and add group mappings.
Click Save.

Configure SAML identity provider

To finish setup, register Fusion with your SAML identity provider. The amount of information required to register varies depending on the SAML authority.All systems require the Fusion URL to redirect to upon successful login. This includes the protocol, server, and port for the Fusion application, and path api/saml, such as https://www.my-fusion-app.com:8764/api/saml. If the Fusion application is running behind a load-balancer, then this URL is the load-balancer URL plus path api/saml. Note that the load-balancer should be session-sticky in order for the sequence of messages that comprise the SAML protocol to run to completion successfully.Some authorities may require additional information. In particular, the SAML 2.0 “AudienceRestriction” tag may be part of the SAML message. This tag specifies the domain for which the SAML trust conditions are valid, which is usually the domain in which the Fusion app is running, such as https://www.my-fusion-app.

Example SAML Realm configuration

The Fusion endpoint api/realm-configs returns a JSON list of all the configuration objects for all realms. After configuring a SAML realm named "saml-test" using the okta.com developer preview tool, the configuration object for this realm is:

{
 "name":"saml-test",
 "realmType":"saml",
 "enabled":true,
 "config":{
     "autoCreateUsers":true,
     "idpUrl":"https://dev-417804.oktapreview.com/app/dev417804_1/exk686w2xi5KTuSXz0h7/sso/saml",
     "issuer":"http://www.okta.com/exk686w2xi5KTuSXz0h7",
     "certificateFingerprint":"MIIDpDCCAoygAwIBAgIGAVQr4A4NMA0GCSqGSIb3DQEBBQUAMIGSMQswCQYDVQQGEwJVUzETMBEG\nA1UECAwKQ2FsaWZvcm5pYTEWMBQGA1UEBwwNU2FuIEZyYW5jaXNjbzENMAsGA1UECgwET2t0YTEU\nMBIGA1UECwwLU1NPUHJvdmlkZXIxEzARBgNVBAMMCmRldi00MTc4MDQxHDAaBgkqhkiG9w0BCQEW\nDWluZm9Ab2t0YS5jb20wHhcNMTYwNDE5MDAxNTI0WhcNMjYwNDE5MDAxNjI0WjCBkjELMAkGA1UE\nBhMCVVMxEzARBgNVBAgMCkNhbGlmb3JuaWExFjAUBgNVBAcMDVNhbiBGcmFuY2lzY28xDTALBgNV\nBAoMBE9rdGExFDASBgNVBAsMC1NTT1Byb3ZpZGVyMRMwEQYDVQQDDApkZXYtNDE3ODA0MRwwGgYJ\nKoZIhvcNAQkBFg1pbmZvQG9rdGEuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA\nuNz0trRFPw2d4xXoUvX2oWeZolTVeFtaTnB9SWUyjK4og0WdT7rNdBg10eTvB2ezBwXCf24UGGui\nr1kjkZjiHDqDxKtzQYWpGuzLCjh/4PxKFGDaiUNKcE1Ig5myiEBTvMvv99XtrcI75QdUGDhbMiBr\n2PR5FukWOYepzlBzqY0JSDzX9NYJBKPkz+syK4mj0I6dqtYOU+bcTvjF9sR7jiHtQ+d0Zl8rz1Ca\nyuE3mNUtFJ1IJrY/RArhH1AB6mXbV/de1CXmGhKQbqQAbx9SiKtki9n84gKEwuWdV0jIqcBLGxUQ\ngjbsaIVqed2oX+7F2fh6t0g/I8NPnOWXOTvA+wIDAQABMA0GCSqGSIb3DQEBBQUAA4IBAQCPt+DR\nliIsHO/iVnmLFPGfqrCO/gMv++xnq2wOB19YX7HhT1GIY2YZoVphrQpXH3OO0/8AZJ8ApCmq0E9x\nxUTQwQPBanVqlyLtu1Hr0c6dbAqcd5PtaEe6Ci33nayWPydhOmitvIyb/WtWtbel9HcdUkoGvkAl\ng305jnxkhwGLJm4jkzYe+eaYhd6oG3/JcHqKDGYGf7i2Z+ny0D7vxTeBQ+8PbZfsUKg0PlKyTocb\nydSmDPISsA1xOH5zlw+hzFIdKgD5vW7QZLvpIclNc2hqki/nWl/CHut0TnUuP/V3boREmhDu395n\n/u72pgNANfP7+2DTBb+CBTjGUsAxpKRF",
     "userIdAttribute":""
 },
 "roleNames":["search"],
 "id":"52e1c0d2-5e00-4c76-a3d4-57f1381bdb4f",
 "createdAt":"2016-04-19T19:49:04Z",
 "updatedAt":"2016-04-19T20:06:56Z"
}

Introduction to Fusion

Getting Data In

Getting Data Out

Operations

Reference

Developer Docs

Neural Hybrid Search

Release Notes

Debugging

IdP rejects an authentication request (AutnRequest) from app

IdP rejects authentication or sends back a status code in response message indicating an error

Illegal Key Size error

Fusion rejects a SAML assertion

Add a Security Realm

Configure SAML identity provider

Example SAML Realm configuration

References

Introduction to Fusion

Getting Data In

Getting Data Out

Operations

Reference

Developer Docs

Neural Hybrid Search

Release Notes

​Debugging

​IdP rejects an authentication request (AutnRequest) from app

​IdP rejects authentication or sends back a status code in response message indicating an error

​Illegal Key Size error

​Fusion rejects a SAML assertion

Debugging

IdP rejects an authentication request (AutnRequest) from app

IdP rejects authentication or sends back a status code in response message indicating an error

Illegal Key Size error

Fusion rejects a SAML assertion