> ## Documentation Index
> Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting SAML

export const LwTemplate = ({title = "Key questions to get you started", icon = "sparkles", cta = "Powered by Agent Studio", linkHref = "https://lucidworks.com/demo/?utm_source=docs&utm_medium=referral&utm_campaign=docs_cta_ai"}) => {
  const [isLoaded, setIsLoaded] = useState(false);
  useEffect(() => {
    const timer = setTimeout(() => {
      setIsLoaded(true);
    }, 500);
    return () => clearTimeout(timer);
  }, []);
  return <div className="lw-template-container">
      <Card title={title} icon={icon}>
        {isLoaded && <span dangerouslySetInnerHTML={{
    __html: `<lw-template id="a029c1a9-28be-427e-b0e1-5d918920246a"></lw-template
            >`
  }} />}
        <Link href={linkHref} className="agent-studio-link text-left text-gray-600 gap-2 dark:text-gray-400 text-sm font-medium flex flex-row items-center hover:text-primary dark:hover:text-primary-light group-hover:text-primary group-hover:dark:text-primary-light">Powered by Lucidworks Agent Studio</Link>
      </Card>
    </div>;
};

[old doc.lw link]: https//doc.lucidworks.com/app-studio/4.2/3164

[localhost link]: http://localhost:3000/docs/5/app-studio/reference/modules/security/authentication/saml/troubleshooting

[mintlify link]: https://doc.lucidworks.com/docs/5/app-studio/reference/modules/security/authentication/saml/troubleshooting

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](http://docs.spring.io/spring-security-saml/docs/1.0.x/reference/htmlsingle/) extension for underlying SAML compliant client behavior, a useful reference is the [Spring documentation](http://docs.spring.io/spring-security-saml/docs/1.0.x/reference/htmlsingle/).

<LwTemplate />

## Debugging

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

```xml wrap  theme={"dark"}
<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:

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

   ```xml theme={"dark"}
   <filter-chain pattern="/saml/metadata/**" filters="metadataDisplayFilter"/>
   ```

   For example:

   ```xml theme={"dark"}
   ...
   <filter-chain pattern="/saml/logout/**" filters="samlLogoutFilter"/>
   <filter-chain pattern="/saml/metadata/**" filters="metadataDisplayFilter"/>
   <filter-chain pattern="/saml/SSO/**" filters="samlWebSSOProcessingFilter"/>
   ...
   ```

2. Add the bean definition for this filter:

   ```xml theme={"dark"}
   <!-- 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"/>
   ```

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

<Accordion title="Configure Fusion for SAML">
  [SAML 2.0](https://en.wikipedia.org/wiki/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](/docs/5/fusion/operations/security/access-control/security-realms). 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

  {/* // tag::realm-config[] */}

  1. In the Fusion workspace, navigate to **System** > **Access Control**.
  2. Click **Security Realms**.
  3. Click **Add Security Realm**.
  4. 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.

     {/* // All except Kerberos: */}

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

  {/* // end::realm-config[] */}

  5. 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`

       <Note>  The URL format may differ depending on the SAML Identity Provider.</Note>

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

  6. Optional: Under **Groups Mapping**, specify the Group Name Attribute and add group mappings.

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

  ```json theme={"dark"}
  {
   "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"
  }
  ```

  ## References

  * [http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf](http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf)
  * [http://docs.oasis-open.org/security/saml/v2.0/saml-glossary-2.0-os.pdf](http://docs.oasis-open.org/security/saml/v2.0/saml-glossary-2.0-os.pdf)
</Accordion>