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

# Authentication

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

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

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

The Security Module provides authentication and authorization capabilities to the search application. It supports multiple authentication providers and will pass authentication credentials on to search engines capable of handling authorization (for example, the FAST Security Access Module), providing personalization and role based filtering. The Security Module can be extended and customized via a pluggable API.

The Security module supports a number of authentication providers, including:

* **Single sign-on** via Windows Integrated Authentication
* **Container-managed** authentication
* **Form-based** authentication
* **Cookie-based** authentication
* **Pass-through** authentication
* **Custom authentication providers** via API

<LwTemplate />

## Authentication methods

### OAuth

Authentication against OAuth 2.0 services is possible using the individual authentication provider modules which simplify the configuration of OAuth parameters and deal with the differences that exist between common OAuth endpoints.

A general OAuth provider can be used by including the `twigkit.security.provider.oauth` module. This requires a custom `spring-security.xml` file, but it is recommended to use one of the prepackaged modules we provide for these services.

[Read more about OAuth authentication.](/docs/5/fusion/dev-portal/appkit/reference/modules/security/authentication/oauth/overview)

### SAML

We have a method of configuring SAML authentication with a simplified process. SAML is still a complex standard and so a lot of the relevant information from the previous SAML instructions is still included here.

Appkit provides an extension for SAML based authentication. SAML is a recognized standard for authentication with many providers and implementations available.

[Read more about SAML authentication.](/docs/5/fusion/dev-portal/appkit/reference/modules/security/authentication/saml/overview)

## Available security providers

Appkit supports a range of security providers for authentication and authorization. Typically one of these providers is used in an application:

### Active Directory

While integration with Active Directory can be achieved using the LDAP setup, Spring Security provides a tailored security provider which makes configuring security using Active Directory easier.

**Set Up Active Directory Authentication for Appkit**

<Accordion title="Set Up Active Directory Authentication for Appkit">
  {/* // Update how-to header information */}

  {/* // formatted */}

  {/* // tag::intro[] */}

  While integration with Active Directory can be achieved using the LDAP setup, Spring Security provides a tailored security provider which makes configuring security using Active Directory easier.

  {/* // end::intro[] */}

  This article describes how to set up authentication against an Active Directory server. It assumes that your Appkit application is managed as a [Maven](https://maven.apache.org/) project with all project dependencies described in a [Maven POM file](https://maven.apache.org/pom.html).

  ## 1. Add the security provider dependency

  Authentication against Active Directory requires the Active Directory module.

  **To enable the Active Directory module**

  1. Remove any existing security provider dependency from the `pom.xml` under the root of the project.
  2. Add this within the `dependencies` tag:

     ```
     <dependency>
         <groupId>twigkit</groupId>
         <artifactId>twigkit.security.provider.active-directory</artifactId>
         <version>${project.parent.version}</version>
     </dependency>
     ```
  3. To configure Appkit to invoke this module on startup, change the `security.conf` file in `src/main/resources/conf/security/` to contain:

     ```
     type: spring_security
     ```

  ## 2. Configure security filtering in the application

  Spring Security operates using a Servlet filter that must be mapped in the `web.xml` file in `src/main/webapp/WEB-INF`:

  ```xml theme={"dark"}
  <!-- Spring Security -->
      <context-param>
          <param-name>contextConfigLocation</param-name>
          <param-value>classpath:spring-security.xml</param-value>
      </context-param>

      <listener>
          <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
      </listener>

      <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>
  <!-- Spring Security Ends -->
  ```

  Added this as the first filter in the chain (at the top of the `web.xml` file).

  ## 3. Point the application to the security backend

  No Spring Security XML file is required. Just add this in a file named `active-directory.conf` in `src/main/resources/conf/security`:

  ```yaml theme={"dark"}
  ldap-server-url: ldap://sharepoint-dc-mtyy7623.cloudapp.net:389/
  domain: sharepoint-dev.twigkit.com
  ```

  Configure this to point to the Active Directory server implementing the LDAP protocol and the domain under which users are located.

  #### The LDAP protocol

  Note the use of the LDAP protocol in the url - `ldap://`. In some cases, SSL encryption is used with the 'LDAPS' protocol. This requires the certificate is trusted by the authentication client (the JVM running Appkit). There are several ways to configure the keystore for the JVM to trust the certificate from the LDAP server. The most common way to do this is to [import the certificate into the JVM’s default keystore](http://docs.oracle.com/cd/E19509-01/820-3399/ggfrj/index.html).

  ### Authentication manager configuration

  Unlike the configuration for the LDAP module, the Active Directory specific configuration is minimal. A user can then login using either their username or the fully qualified principal (for example, `bloggsj@my-domain.com`). By default roles are assigned using the `memberOf` attribute values of the user entry.

  ## 4 Verify the configuration

  You can now verify the authentication in an Appkit application using the login form on a login page which is typically located in `src/main/webapp/login.jsp` in your application source tree.
</Accordion>

### Fusion Sessions API

The Fusion security provider for Appkit allows authentication against Fusion using the Fusion Sessions API. With this provider configured, an application deployed within a Fusion defined 'realm' such as `native` can securely authenticate a user against Fusion.

**Set Up Lucidworks Fusion Authentication**

<Accordion title="Set Up Lucidworks Fusion Authentication">
  The Fusion security provider for Appkit allows authentication against Fusion using the Fusion Sessions API. With this provider configured, an application deployed within a Fusion defined 'realm' such as `native` can securely authenticate a user against Fusion.

  These sections describe how to set up Fusion authentication using the Sessions API within an Appkit application.

  ## 1. Add the security provider dependency

  Authentication against Fusion using the Sessions API requires Appkit’s Fusion security provider module. To enable this module, first remove any existing security provider dependency from the `pom.xml` under the root of the project and insert this within the `dependencies` tag:

  ```xml theme={"dark"}
  <dependency>
      <groupId>twigkit</groupId>
      <artifactId>twigkit.security.provider.fusion</artifactId>
      <version>${project.parent.version}</version>
  </dependency>
  ```

  ## 2. Update security.conf and add fusion.conf

  To invoke this module when Appkit starts up, add this to `security.conf` in `src/main/resources/conf/security/`:

  ```yaml theme={"dark"}
  type: spring_security
  ```

  Then configure the session host, which security realm to use and the session timeout in `fusion.conf` in `src/main/resources/conf/security/fusion`. For example:

  ```yaml theme={"dark"}
  session-host: http://localhost:8764
  session-timeout: 30
  realm-name: native
  ```

  The session-timeout parameter should be a time in minutes and be equal to your Fusion session timeout. By default, this
  value is 10. For further information, refer to the Fusion Session Api documentation.

  ## 3. Configure security filtering in the application

  Spring Security operates using a Servlet filter which must be mapped in the web.xml file in `src/main/webapp/WEB-INF`:

  ```xml theme={"dark"}
  <!-- Spring Security -->
      <context-param>
          <param-name>contextConfigLocation</param-name>
          <param-value>classpath:spring-security.xml</param-value>
      </context-param>

      <listener>
          <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
      </listener>

      <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>
  <!-- Spring Security Ends -->
  ```

  This should be added as the first filter in the chain (at the top of the web.xml file).

  ## 4. Instruct the application to use the Fusion security provider

  For integration with security providers supported by Spring Security, configuration is managed in the [spring-security.xml](/assets/appkit-misc/4.2/spring-security.xml) file in `src/main/resources`.

  Leave the initial section of this file dealing with HTTP URL patterns as configured. Remove any existing authentication manager configuration below that initial section, and add this:

  ```xml theme={"dark"}
  <!-- Fusion authentication provider -->
  <beans:bean id="fusionAuthenticationProvider" class="twigkit.security.fusion.FusionAuthenticationProvider"/>

  <!-- Authentication manager configuration -->
  <authentication-manager>
      <authentication-provider ref="fusionAuthenticationProvider"/>
  </authentication-manager>
  ```

  Now when a user logs into Appkit, if they have been successfully authenticated against Fusion, they will receive a session cookie that can be re-used to send subsequent requests. Access to Fusion in this way can extend for up to 10 minutes if there is no activity and up to a maximum of 8-hours if a request is received within a 10-minute interval.
</Accordion>

### HTTP Headers

Appkit supports authentication via generic HTTP headers passed through from a component behind a secure firewall sitting in front of the Appkit application. If there is such an authentication component in the environment where you are using Appkit, you can configure the HTTP headers that the application will use to pick up the user’s details.

**Set Up HTTP Headers Authentication**

<Accordion title="Set Up HTTP Headers Authentication">
  Appkit supports authentication via generic HTTP headers passed through from a component behind a secure firewall sitting in front of the Appkit application. If there is such an authentication component in the environment where you are using Appkit, you can configure the HTTP headers that the application will use to pick up the user’s details.

  ## Adding header security

  1. Add this dependency to the `pom.xml` file:
     ```xml theme={"dark"}
     <dependency>
         <groupId>twigkit</groupId>
         <artifactId>twigkit.security.provider.http-header</artifactId>
         <version>${project.parent.version}</version>
     </dependency>
     ```
  2. Modify `conf/security/security.conf` to contain this:
     ```
     type: header
     ```

  ## Configuring the headers used

  Create a new configuration file in `conf/security/header/header.conf`.

  A typical configuration might look like:

  ```yaml theme={"dark"}
  user-id: remote_user
  roles: x-group
  ```

  Here, the user’s ID will be extracted from the value of the `remote_user` header and roles from the `x-group` header.

  All possible properties are listed here:

  **user-id**: name of header that contains the ID of the user

  **roles**: name of the header that contains the user’s roles - multiple values will be picked up from the header if specified by the comma separated header value convention

  **domain**: name of the header that contains the domain for the user

  **detail-prefix**: prefix of any headers containing values which should be added to the user’s details (for example, if `X-USER-` a header with the name `X-USER-DEPARTMENT` and its value will be added as an entry to the user details map)
</Accordion>

### Kerberos

The Kerberos security provider for Appkit allows authentication using Kerberos. With this provider configured, an application deployed within a Kerberos 'realm' can securely authenticate a user against a Kerberos 'Key Distribution Center'. This module is primarily intended to simplify the process of authenticating a user silently in a Windows environment by leveraging the built in support for integrated Windows authentication in Internet Explorer. However it should be possible to use this module to authenticate the user in any Kerberos compliant environment.

**Set Up Kerberos Authentication**

<Accordion title="Set Up Kerberos Authentication">
  The Kerberos security provider for Appkit allows authentication using Kerberos. With this provider configured, an application deployed within a Kerberos 'realm' can securely authenticate a user against a Kerberos 'Key Distribution Center'. This module is primarily intended to simplify the process of authenticating a user silently in a Windows environment by leveraging the built in support for integrated Windows authentication in Internet Explorer. However it should be possible to use this module to authenticate the user in any Kerberos compliant environment.

  This guide focuses on how to set up Kerberos authentication within an Appkit application in a Windows environment. It assumes Kerberos is enabled and already working on a domain controller.

  ## 1 Add the security provider dependency

  Authentication against Kerberos requires the Kerberos provider module. To enable this module first remove any existing security provider dependency from the `pom.xml` under the root of the project and add this within the `dependencies` tag:

  ```xml theme={"dark"}
  <dependency>
      <groupId>twigkit</groupId>
      <artifactId>twigkit.security.provider.kerberos</artifactId>
      <version>${project.parent.version}</version>
  </dependency>
  ```

  Then to configure Appkit to invoke this module on startup change the `security.conf` file in `src/main/resources/conf/security/` to contain:

  ```yaml theme={"dark"}
  type: kerberos
  ```

  ## 2 Configure security filtering in the application

  This module uses Spring Security which operates using a Servlet filter which must be mapped in the `web.xml` file in `src/main/webapp/WEB-INF`:

  ```xml theme={"dark"}
  <!-- Spring Security -->
      <context-param>
          <param-name>contextConfigLocation</param-name>
          <param-value>classpath:spring-security.xml</param-value>
      </context-param>

      <listener>
          <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
      </listener>

      <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>
  <!-- Spring Security Ends -->
  ```

  This should be added as the first filter in the chain (at the top of the web.xml file). Remove any existing spring-security.xml file in the project because this configuration is pre-packaged by the Kerberos module.

  ## 3 Configure the application for the Kerberos environment

  To use Kerberos with an application, a 'keytab' file is required. This identifies the application (service) and the host on which it is running in a special encrypted host key. You must configure a service principal and obtain a keytab file (usually done on the domain controller using Windows powershell) prior to configuring the Appkit application. After you have the service principal name and the keytab file configuration is easy. Add a file named `kerberos.conf` to `src/main/resources/conf/security/` with these parameters:

  ```yaml theme={"dark"}
  service-principal: HTTP/sharepoint-sp@sharepoint-dev.twigkit.com
  keytab-location: classpath:sharepoint-dev.keytab
  debug: true
  # optional (defaults to '/WEB-INF/pages/login.jsp')
  login-page: /WEB-INF/pages/login.jsp
  ```

  Set the service principal and keytab location accordingly. The debug parameter provides useful logging output from the Kerberos protocol interactions, and is recommended to be set to true for development. The login page is optional and provides a fallback page. If this is a standard Appkit login.jsp file, then the fallback form will be used to attempt login using form-based authentication (see [Fallback strategy](#fallback-strategy) for more information). Alternatively this can direct to an 'unauthorized' error or debug page.

  ## 4 Test the authentication

  Login to an account within the Kerberos 'realm' and navigate to the application in IE. The user should be silently authenticated.

  ## Further information on using the Kerberos provider

  ### Fallback strategy

  This module includes a default fallback strategy in the event Kerberos authentication fails. Reasons for failure can include:

  * Incorrect configuration of the application
  * An invalid keytab file
  * A browser that does not support Kerberos via the SPNEGO/Negotiate protocol
  * Unauthorized access
  * Access from outside the Kerberos 'realm'
  * The environment is not configured correctly for Kerberos (for example, some other authentication mechanism 'preferred')

  The fallback strategy is such that if Kerberos authentication fails a form is presented to attempt form based authentication. The page used is configurable as described above, and if forms based authentication is not supported it is recommended to point to a 'failure' or error page. In some scenarios it makes sense to have this fallback, depending on the nature of the security and environment in which the application is deployed.
  It should be noted that while a browser such as Internet Explorer supports NTLM, and often will attempt to fall back on this, this is not part of Kerberos and, due to restrictions in current Java runtimes, this is not supported.

  ### General troubleshooting

  First, check all of the above reasons the authentication can fail or 'fall back' from Kerberos. Use the `debug` configuration parameter and check the logs for information that could help to identify the cause. If it is a Windows environment it is recommended to check with the systems administrators that everything works correctly on the domain controller (check the Kerberos key distribution service, permissions of the service principal account, etc). You can view the headers passed from the browser in the debug information in the logs, these might provide an indication of why authentication failed (if Kerberos is used).

  If you find or suspect that NTLM is used, ensure you are trying to access the site using the host name configured in the SPN (service principal name). For example, if the SPN is `HTTP/sharepoint-sp@sharepoint-dev.twigkit.com`, you must use the URL for the host machine `sharepoint-sp`: either `http://sharepoint-sp/` or `http://sharepoint-sp.sharepoint-dev.twigkit.com/`. Using 'localhost' or another alias will not work.

  ### Authentication works but the user is prompted for a username and password

  Usually in a Windows environment Kerberos allows silent authentication (single sign on via the account logged into the machine). In some cases the user is presented with a dialog (not an HTML form) the first time they visit the application or if the session expires, but when they enter their credentials it works fine. This can be a simple case that the user’s Windows credentials are not correctly configured or IE has 'integrated windows authentication' disabled. Make sure this is enabled in IE and that the credentials are saved correctly in the user account settings under the 'Control Panel'.

  ### How does this differ from Integrated Windows Authentication?

  Previously in Appkit, the only way to do silent 'integrated' authentication with Windows was using the Tomcat ISAPI connector, as described in our article about Integrated Windows Authentication.

  The Kerberos Security module simplifies the process for Kerberos enabled environments and keeps all of the configuration within the application.
</Accordion>

### LDAP

Appkit allows for authentication against a server using LDAP (Lightweight Directory Access Protocol). It assumes that your Appkit application is managed as a [Maven](https://maven.apache.org/) project with all project dependencies described in a [Maven POM file](https://maven.apache.org/pom.html).

**Set Up LDAP Authentication**

<Accordion title="Set Up LDAP Authentication">
  Appkit allows for authentication against a server using LDAP (Lightweight Directory Access Protocol). It assumes that your Appkit application is managed as a [Maven](https://maven.apache.org/) project with all project dependencies described in a [Maven POM file](https://maven.apache.org/pom.html).

  ## 1 Add the security provider dependency

  Authentication against LDAP requires the LDAP module. To enable this module first remove any existing security provider dependency from the `pom.xml` under the root of the project and add this within the `dependencies` tag:

  ```xml theme={"dark"}
  <dependency>
      <groupId>twigkit</groupId>
      <artifactId>twigkit.security.provider.ldap</artifactId>
      <version>${project.parent.version}</version>
  </dependency>
  ```

  Then to configure Appkit to invoke this module on startup change the `security.conf` file in `src/main/resources/conf/security/` to contain:

  ```yaml theme={"dark"}
  type: spring_security
  ```

  ## 2 Configure security filtering in the application

  Spring Security operates using a Servlet filter that must be mapped in the `web.xml` file in `src/main/webapp/WEB-INF`:

  ```xml theme={"dark"}
  <!-- Spring Security -->
      <context-param>
          <param-name>contextConfigLocation</param-name>
          <param-value>classpath:spring-security.xml</param-value>
      </context-param>

      <listener>
          <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
      </listener>

      <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>
  <!-- Spring Security Ends -->
  ```

  Add this Servlet filter as the first filter in the chain (at the top of the `web.xml` file).

  ## 3 Point the application to the security backend

  No Spring Security XML file is required. Add this in a file named `ldap.conf` in `src/main/resources/conf/security`:

  ```yaml theme={"dark"}
  ldap-server-url: ldap://sharepoint-dc-mtyy7623.cloudapp.net:389/
  manager-dn: sharepoint-dev@sharepoint-dev.twigkit.com
  manager-password: abcdef123*
  user-search-base: CN=Users,dc=sharepoint-dev,dc=twigkit,dc=com
  user-search-filter: (uid={0})
  group-role-attribute: cn
  group-search-base: CN=Groups,DC=sharepoint-dev,DC=twigkit,DC=com
  group-search-filter: (member={0})
  role-prefix: ROLE_
  ```

  The first three settings configure the LDAP server’s location and manager credentials. The manager is the account used by Spring Security to access the LDAP server. The DN for this user should be available from the LDAP server or directory containing the user.

  The remaining settings reference the LDAP server configuration to be used and provide the attributes required to determine the username and roles.

  * `user-search-base` is the DN used under which users are retrieved
  * `user-search-filter` is the property used to determine a match against the username specified by the user
  * `group-role-attribute` is the property from which the name of the roles will be populated
  * `group-search-base` is the DN used under which groups are retrieved
  * `group-search-filter` is the property used to determine the group membership of a user
  * `role-prefix` is a prefix applied to the roles reported by Spring Security

  The roles picked up from LDAP can later be used for security trimming and personalization.

  #### The LDAP server protocol

  Note the use of the LDAP protocol in the URL - `ldap://`. In some cases SSL encryption is used with the 'LDAPS' protocol. This requires the certificate is trusted by the authentication client (the JVM running Appkit). There are several ways to configure the keystore for the JVM to trust the certificate from the LDAP server. The most common way to do this is to [import the certificate into the JVM’s default keystore](http://docs.oracle.com/cd/E19509-01/820-3399/ggfrj/index.html).

  ## 4 Verify the configuration

  You can now verify the authentication in an Appkit application using the [widget:login-form](/docs/4/app-studio/reference/tags/lightning.directive.widgetLoginForm) on a login page which is typically located in `src/main/webapp/login.jsp` in your application source tree.
</Accordion>

### Siteminder

Appkit can integrate with a SiteMinder single-sign-on authentication provider. SiteMinder is typically installed in a web server placed in front of the application server that runs Appkit.

**Set Up SiteMinder Authentication**

<Accordion title="Set Up SiteMinder Authentication">
  {/* // Update how-to header information */}

  {/* // formatted */}

  {/* // tag::intro[] */}

  Appkit can integrate with a SiteMinder single-sign-on authentication provider. SiteMinder is typically installed in a web server placed in front of the application server that runs Appkit.

  {/* // end::intro[] */}

  To enable SiteMinder authentication:

  1. Add this module to your POM (`pom.xml` file in the root of the application):

     ```xml theme={"dark"}
     <dependency>
      <groupId>twigkit</groupId>
      <artifactId>twigkit.security.provider.siteminder</artifactId>
      <version>${project.parent.version}</version>
     </dependency>
     ```
  2. Update your `security.conf` (found in `src/main/resources/conf/security/`) to use SiteMinder:

     ```yaml theme={"dark"}
     type: siteminder
     ```
</Accordion>

### Spring Security

The Spring Security authentication provider for Appkit interfaces with both [Spring Security](http://projects.spring.io/spring-security/) 3 and 4. Projects that adopt Appkit version 3 must switch to using Spring Security 4.

Authorized Spring principals become fully-qualified Appkit user profiles, along with any roles or groups that the Spring module provides. Spring Security integrates with a number of authentication protocols, including LDAP, Active Directory, Basic Authentication, Kerberos, JAAS, and others. For a full list, [see here.](http://docs.spring.io/spring-security/site/docs/3.1.1.RELEASE/reference/introduction.html)

**Set Up Spring Authentication**

<Accordion title="Set Up Spring Authentication">
  {/* // Update how-to header information */}

  {/* // formatted */}

  {/* // tag::intro[] */}

  The Spring Security authentication provider for Appkit interfaces with both [Spring Security](http://projects.spring.io/spring-security/) 3 and 4. Projects that adopt Appkit version 3 must switch to using Spring Security 4.

  Authorized Spring principals become fully-qualified Appkit user profiles, along with any roles or groups that the Spring module provides. Spring Security integrates with a number of authentication protocols, including LDAP, Active Directory, Basic Authentication, Kerberos, JAAS, and others. For a full list, [see here.](http://docs.spring.io/spring-security/site/docs/3.1.1.RELEASE/reference/introduction.html)

  {/* // end::intro[] */}

  Below you will find some common configurations of the `spring-security.xml` file for integrating with different security mechanisms for authentication and authorization.

  <Note>The references given are for Spring Security 3. For information on how these configurations would change with Spring Security 4, refer to the Release Notes for Appkit 3.</Note>

  The first portion of the configuration file contains the required access levels for URL patterns used in Appkit and in most cases stays the same for all configurations.

  ### Hard-coded users

  ```xml expandable theme={"dark"}
  <?xml version="1.0" encoding="UTF-8"?>
  <beans:beans xmlns="http://www.springframework.org/schema/security"
               xmlns:beans="http://www.springframework.org/schema/beans"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.springframework.org/schema/beans
             http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
             http://www.springframework.org/schema/security
             http://www.springframework.org/schema/security/spring-security-3.1.xsd">

      <http pattern="/styles/**" security="none"/>
      <http pattern="/assets/**" security="none"/>
      <http pattern="/javascript/**" security="none"/>
      <http pattern="/wro/**" security="none"/>

      <http use-expressions="true" disable-url-rewriting="true">
          <intercept-url pattern="/login/" access="isAnonymous()"/>
          <intercept-url pattern="/twigkit/resources/**" access="isAnonymous() or isAuthenticated()"/>
          <intercept-url pattern="/twigkit/services/gsa/auth/**" access="isAnonymous() or isAuthenticated()"/>
          <intercept-url pattern="/mock-response/search" access="isAnonymous() or isAuthenticated()"/>
          <intercept-url pattern="/**" access="isAuthenticated()"/>
          <form-login login-page="/login/" authentication-failure-url="/login/?access=denied"/>
          <http-basic/>
          <logout logout-url="/logout/" logout-success-url="/"/>
      </http>

      <!--
          Simple Configuration Example
      -->
      <authentication-manager>
          <authentication-provider>
              <user-service>
                  <user name="admin" password="admin" authorities="USER, ADMIN"/>
                  <user name="user" password="user" authorities="USER"/>
              </user-service>
          </authentication-provider>
      </authentication-manager>
  </beans:beans>
  ```

  Here, you can see that two users are configured - 'user' and 'admin'. Both have been assigned the role named 'USER' and the admin user also has the 'ADMIN' role.

  ### LDAP

  ```xml expandable theme={"dark"}
  <?xml version="1.0" encoding="UTF-8"?>
  <beans:beans xmlns="http://www.springframework.org/schema/security"
               xmlns:beans="http://www.springframework.org/schema/beans"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.springframework.org/schema/beans
             http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
             http://www.springframework.org/schema/security
             http://www.springframework.org/schema/security/spring-security-3.1.xsd">

      <http pattern="/local-data/**" security="none"/>
      <http pattern="/styles/**" security="none"/>
      <http pattern="/assets/**" security="none"/>
      <http pattern="/javascript/**" security="none"/>
      <http pattern="/wro/**" security="none"/>

      <http use-expressions="true" disable-url-rewriting="true">
          <intercept-url pattern="/login/" access="isAnonymous()"/>
          <intercept-url pattern="/twigkit/resources/**" access="isAnonymous() or isAuthenticated()"/>
          <intercept-url pattern="/twigkit/services/gsa/auth/**" access="isAnonymous() or isAuthenticated()"/>
          <intercept-url pattern="/mock-response/search" access="isAnonymous() or isAuthenticated()"/>
          <intercept-url pattern="/**" access="isAuthenticated()"/>
          <form-login login-page="/login/" authentication-failure-url="/login/?access=denied"/>
          <http-basic/>
          <logout logout-url="/logout/" logout-success-url="/"/>
      </http>

      <!-- Active Directory Configuration -->
      <ldap-server id="ldapServer" url="ldap://my-ldap.my-domain.com:389/" manager-dn="gsaindexing@my-domain.com"
                   manager-password="ABC1234567890*" />

      <authentication-manager>
         <ldap-authentication-provider server-ref="ldapServer"
                                        user-search-base="OU=[Root],DC=uk,DC=corp,DC=my-domain,DC=com"
                                        user-search-filter="sAMAccountName={0}"
                                        group-role-attribute="cn"
                                        group-search-base="OU=[Root],DC=uk,DC=corp,DC=my-domain,DC=com"
                                        group-search-filter="(member={0})"
                                        role-prefix="ROLE_" />
      </authentication-manager>
  </beans:beans>
  ```

  Note the use of the LDAP protocol. In some cases, SSL encryption is used with the 'LDAPS' protocol. This requires the certificate to be trusted by the authentication client (the JVM running Appkit). There are several ways to configure the keystore for the JVM to trust the certificate from the LDAP server. The most common way to do this is to [import the certificate into the JVM’s default keystore](http://docs.oracle.com/cd/E19509-01/820-3399/ggfrj/index.html).

  ### Spring 'remember me' feature

  Spring Security comes with a mechanism for allowing a user’s details to be remembered beyond the current browser session, avoiding the user having to provide credentials on a login page every time. This integrates with the 'remember' attributes on the [widget:login-form](/docs/4/app-studio/reference/tags/lightning.directive.widgetLoginForm) tag.

  There are two methods to allow the user’s session to be persistent using either a browser cookie or a database backed persistence method. The first is most commonly used, and to implement this all that is required is to add the remember-me line to the `spring-security.xml` HTTP configuration:

  ```xml expandable theme={"dark"}
  <http use-expressions="true" disable-url-rewriting="true">
      <intercept-url pattern="/login/" access="isAnonymous()"/>
      <intercept-url pattern="/twigkit/resources/**" access="isAnonymous() or isAuthenticated()"/>
      <intercept-url pattern="/twigkit/services/gsa/auth/**" access="isAnonymous() or isAuthenticated()"/>
      <intercept-url pattern="/mock-response/search" access="isAnonymous() or isAuthenticated()"/>
      <intercept-url pattern="/**" access="isAuthenticated()"/>
      <form-login login-page="/login/" authentication-failure-url="/login/?access=denied"/>
      <http-basic/>
      <logout logout-url="/logout/" logout-success-url="/"/>
      <remember-me key="KEY-U5ED-F0R-C00KIE-ENCRYPT1ON"/>
  </http>
  ```

  ### Re-directing users to the original requested URL post-login

  Spring Security provides an authentication strategy that allows a requested URL to be saved before requiring the user to log in; once credentials have been authenticated the user is re-directed to the original URL.

  This strategy is implemented as part of the `<form-login ...>` tag defined via the `authentication-success-handler-ref`. For example:

  ```xml theme={"dark"}
  <form-login login-page="/login/"
                      authentication-failure-url="/login/?access=denied"
                      authentication-success-handler-ref="login_success_handler"/>
  ```

  The `login_success_handler` is a reference to the Spring Security class that implements the described strategy. This class is defined via this bean that needs to be added to the `spring-security.xml` as follows:

  ```xml theme={"dark"}
  <http..>
      ...

  </http>

  <beans:bean id="login_success_handler" class="org.springframework.security.web.authentication.SavedRequestAwareAuthenticationSuccessHandler"/>
  ```
</Accordion>

### Tomcat Container

[Apache Tomcat](https://hub.docker.com/_/tomcat) is an open source Java servlet container. Tomcat implements Java enterprise specs, including the Java Servlet, JavaServer Pages JSP, and WebSockets APIs.

**Set Up Tomcat Container Authentication**

<Accordion title="Set Up Tomcat Container Authentication">
  {/* // Update how-to header information */}

  {/* // formatted */}

  {/* // tag::intro[] */}

  [Apache Tomcat](https://hub.docker.com/_/tomcat) is an open source Java servlet container. Tomcat implements Java enterprise specs, including the Java Servlet, JavaServer Pages JSP, and WebSockets APIs.

  {/* // end::intro[] */}

  To have Tomcat manage authentication for your application:

  1. Add this module to your POM (`pom.xml` file in the root of the application):

     ```xml theme={"dark"}
     <dependency>
      <groupId>twigkit</groupId>
      <artifactId>twigkit.security.provider.tomcat7</artifactId>
      <version>${project.parent.version}</version>
     </dependency>
     ```
  2. Set the requisite type in `security.conf` (found in `src/main/resources/conf/security/`):

     ```
     type: tomcat7
     ```

  This picks up the user and all roles from the configured Tomcat authentication mechanism. This is often used in Windows environments. More information on this type of authentication can be found [in the Tomcat documentation](http://tomcat.apache.org/tomcat-7.0-doc/windows-auth-howto.html).
</Accordion>

### Windows

Appkit can be used with [Integrated Windows Authentication](http://en.wikipedia.org/wiki/Integrated_Windows_Authentication) for [single sign on (SSO)](http://en.wikipedia.org/wiki/Single_sign-on) in your search application using Microsoft [Internet Information Services](http://www.iis.net/).

**Set Up Windows Authentication**

<Accordion title="Set Up Windows Authentication">
  {/* // Update how-to header information */}

  {/* // formatted */}

  {/* // tag::intro[] */}

  Appkit can be used with [Integrated Windows Authentication](http://en.wikipedia.org/wiki/Integrated_Windows_Authentication) for [single sign on (SSO)](http://en.wikipedia.org/wiki/Single_sign-on) in your search application using Microsoft [Internet Information Services](http://www.iis.net/).

  {/* // end::intro[] */}

  This article includes all the necessary steps to configure the IIS component on the Windows server. These instructions assume that your Appkit application is managed as a [Maven](https://maven.apache.org/) project with all project dependencies described in a [Maven POM file](https://maven.apache.org/pom.html).

  <Note>All screen shots and references to IIS configuration below were obtained from IIS 8.0 on a Windows Server 2012 VM. These might differ if using a different version of Windows or IIS.</Note>

  ## Interaction diagram

  <img src="https://mintcdn.com/lucidworks/J_LymSfRoWq3UOvg/assets/images/appkit/4.2/jumly-gsa-query-response-1.png?fit=max&auto=format&n=J_LymSfRoWq3UOvg&q=85&s=6f1145888e827a73a74dfbb77543648f" alt="Interaction diagram" width="1152" height="965" data-path="assets/images/appkit/4.2/jumly-gsa-query-response-1.png" />

  {/* 
    %%% jumly
    @found "Browser", ->
      @message "HTTP request", "Appkit", ->
    @message "HTTP request", "IIS", ->
    @message "Authenticate", "IIS", ->
         @message "Authenticated request", "Tomcat", ->
    @reply "Authenticated request", "Appkit"
    @reply "HTTP response", "Browser", ->
    @message "Render search UI", "Browser"
    %%%
    */}

  ## 1 Prerequisites

  ### 1.1 Make sure IIS is installed on your Windows server

  Install [IIS](https://www.iis.net/) on your Windows server.

  ### 1.2 Install the Oracle JDK on the Windows server

  Install the [Oracle Java SE Development Kit](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).

  ### 1.3 Install Tomcat

  Tomcat versions 7 and 8 are both supported. In this, we assume you are using Tomcat 8.0.21.

  **To install Tomcat**

  1. Download the [Tomcat installer](https://tomcat.apache.org/download-80.cgi) (Windows Service Installer `.exe`) and follow the installation instructions. After installation is complete, do not start the Tomcat service just yet.

     <Note>   Install Tomcat at a **whitespace-free path** (for example, `D:\tomcat8`). This path will be referred to as `CATALINA_HOME` hereafter. All the screenshots that follow assume you installed Tomcat in `D:\Tomcat8`.</Note>

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/14.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=a462098c07e93bff4e3899eec3f8db5e" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/14.png" />
  2. After the installation is complete, change Tomcat memory settings as follows:
     1. Run `%CATALINA_HOME%\bin\Tomcat8w.exe`
     2. On the Java tab, set Java Options to include:

        ```
        -Xms512m
        -Xmx2048m
        -XX:PermSize=128m
        -XX:MaxPermSize=1024m
        ```
  3. Repeat these settings in the input boxes below:

     ```
     Initial memory pool: 512
     Maximum memory pool: 2048
     ```

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/15.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=f0e422009111955c3ab289c47bce138c" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/15.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/16.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=e2e357bc4fdc18463b9dd47e7db7760c" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/16.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/17.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=793d9846ac31f157e7038b44e44cd089" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/17.png" />

  ### 1.4 Verify the Tomcat installation

  Start up Tomcat via Windows Services and go to `http://localhost:8080`. You should be presented with the default Tomcat manager application.

  ## 2 Configure and deploy the Appkit application

  ### 2.1 Configure the security provider

  Authentication against IIS requires the "generic" Appkit security provider module. This is a thin layer which integrates with the standard Java servlet API to pick up the user’s credentials for authentication. To enable this module first remove any existing security provider dependency from the `pom.xml` under the root of the project and add this within the `dependencies` tag:

  ```xml theme={"dark"}
  <dependency>
   <groupId>twigkit</groupId>
   <artifactId>twigkit.security.core</artifactId>
   <version>${project.parent.version}</version>
  </dependency>
  ```

  Then to configure Appkit to invoke this module on startup change the `security.conf` file in `src/main/resources/conf/security/` to contain:

  ```yaml theme={"dark"}
  type: generic
  ```

  Make sure to remove any existing security provider configuration if there is one including the 'Spring Security' XML file and Spring related entries in the `web.xml` file if Spring was previously being used in the application.

  ### 2.2 Deploy the application to Tomcat

  After these steps are completed, package your Appkit web application as a WAR file and deploy into Tomcat. Hereafter we assume you package the application as `myapp.war` so that the application can be accessed as `http://localhost:8080/myapp/`.

  ## 3 Configure the Tomcat-ISAPI connector

  The Tomcat ISAPI connector is a DLL file that you can download from the [Apache Tomcat](http://tomcat.apache.org/) website.

  Below, we assume that you have downloaded the ZIP file relevant to your OS type and extracted `isapi_redirect.dll` from the archive.

  ### 3.1 Configure Tomcat for ISAPI

  1. Add isapi\_redirect.dll to `%CATALINA_HOME%\bin`.
  2. Create [`%CATALINA_HOME%\conf\workers.properties.minimal`](/assets/appkit-misc/4.2/workers.properties.minimal) with:

     ```
     worker.list=worker1
     worker.worker1.host=127.0.0.1
     worker.worker1.port=8009
     worker.worker1.type=ajp13
     ```
  3. Create [`%CATALINA_HOME%\conf\uriworkermap.properties`](/assets/appkit-misc/4.2/uriworkermap.properties) with:

     ```
     /*=worker1
     ```
  4. (**Important**) In `%CATALINA_HOME%\conf\server.xml`, you must put `tomcatAuthentication="false"` on the AJP connector:

     ```xml theme={"dark"}
     <Ajp13Connector port="8009" tomcatAuthentication="false" />
     ```

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/26.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=7ec863d361ad866898f3a8edff3dba87" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/26.png" />

  <Note>From now on, we assume you installed Tomcat in `D:\Tomcat8` as noted above.</Note>

  ### 3.2 Configure Windows registry settings

  This key needs to be modified in the registry with the specified properties:

  ```
  HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0
  ```

  <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/27.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=3a3998b6a8c1d6b5906e63f692a8252d" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/27.png" />

  1. Add a string value with the name `extension_uri` and a value of `/jakarta/isapi_redirect.dll`
  2. Add a string value with the name `log_file` and a value pointing to where you want your log file to be (for example, `D:\Tomcat8\logs\isapi.log`).
  3. Add a string value with the name `log_level` and a value for your log level (can be `debug`, `info`, `error` or `emerg`).
  4. Add a string value with the name `worker_file` and a value which is the full path to your `workers.properties` file (for example, `D:\Tomcat8\conf\workers.properties.minimal`)
  5. Add a string value with the name `worker_mount_file` and a value which is the full path to your `uriworkermap.properties` file (for example, `D:\Tomcat8\conf\uriworkermap.properties`)

     To save trouble, you can create a file named [`tomcat_iis_settings.reg`](/assets/appkit-misc/4.2/registry-changes.reg) that includes this (replacing `D:\Tomcat8` with your own `CATALINA_HOME`):

     ```properties wrap theme={"dark"}
     Windows Registry Editor Version 5.00
     [HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0]
     @=""
     "extension_uri"="/jakarta/isapi_redirect.dll"
     "log_file"="D:\\Tomcat8\\logs\\isapi_redirect.log"
     "log_level"="error"
     "worker_file"="D:\\Tomcat8\\conf\\workers.properties.minimal"
     "worker_mount_file"="D:\\Tomcat8\\conf\\uriworkermap.properties"
     ```
  6. On the Windows server, double-click the `tomcat_iis_settings.reg` file to import the settings.

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/24.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=998d38fc03409864bfdc88f6d895d7ce" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/24.png" />

  ## 4 Configure the IIS

  This assumes that IIS is already installed on the Windows server.

  ### 4.1 Enable ISAPI Filters and ISAPI Extensions

  <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/9.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=3637686435f4a5a92a0bd47b558e49b3" alt="ISAPI Filters and ISAPI Extensions" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/9.png" />

  ### 4.2 Enable Windows authentication

  <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/10.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=ae14ec9688fc8081783b9d1baf889c51" alt="BASIC (optional) and Windows authentication" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/10.png" />

  ### 4.3 Enable CGI filtering

  <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/46.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=4f2666ce1d1cfd6a8f58d1d6daf26abb" alt="CGI filtering on the IIS" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/46.png" />

  ### 4.4 Configure the virtual directory and website on IIS

  1. Using the IIS management console, add a new virtual directory to your IIS/PWS web site. The name of the virtual directory must be `jakarta`. Its physical path should be the directory where you placed `isapi_redirect.dll` (in our example, it is `D:\Tomcat8\bin`). While creating this new virtual directory assign it with execute access.

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/28.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=980144795559f82938a418080379ac16" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/28.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/29.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=5a3d7fc223a25042409a4f5675490e23" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/29.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/30.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=5279351667e7d83be79fbf93be3c5f9c" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/30.png" />
  2. Using the IIS management console, add `isapi_redirect.dll` as a filter in your IIS/PWS web site. The name of the filter should reflect its task (here we use the name `jakarta`). Its executable must be `D:\Tomcat8\bin\isapi_redirect.dll`.

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/31.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=a0d14fb9129215846053566073ec1858" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/31.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/32.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=a36e82cc664bae41ee0690ba9e1d1c1e" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/32.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/33.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=d6e4177854f2e7fbd81b76f4a4c5aefe" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/33.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/34.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=9f8339ffcfeef9d59e33583531c58d20" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/34.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/35.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=b1f0d64f16d39c6a4379c101366e8798" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/35.png" />
  3. Enable Windows authentication for your IIS website:

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/37.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=e95e85b53d252a1bc7694ce025421aa2" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/37.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/36.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=2370fd949fd6a3143a88694ecb567623" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/36.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/40.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=864d05b1a12e69123989284ae30f40c9" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/40.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/38.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=360bc08b23353e55f7d4e8928c74bf54" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/38.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/39.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=0ce70e657139059f91d706acb46c5799" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/39.png" />
  4. On IIS Admin, select the server, and click ISAPI and CGI Restrictions. Then open it and Add… with the correct `isapi_redirect.dll` path:

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/41.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=6217352952b0f5c9027493c1055edd96" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/41.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/43.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=7e183ed24039faba63776155c6f5ca1a" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/43.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/44.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=a151c7f0b8619f8595d20ec5ea641690" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/44.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/45.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=ab73a5999e218398f9092c6bf94c4e32" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/45.png" />

       <img src="https://mintcdn.com/lucidworks/2KNayRvSeBNrjWMT/assets/images/appkit/4.2/windows-auth/42.png?fit=max&auto=format&n=2KNayRvSeBNrjWMT&q=85&s=830c1fe63ddecc1cb52671a1be61d266" alt="IIS screenshot" width="1920" height="1080" data-path="assets/images/appkit/4.2/windows-auth/42.png" />
  5. Restart IIS and Tomcat.

  ## 5 Verify the installation

  If all goes well, you should be able to visit `http://localhost/myapp/`, which should present the authenticated Windows user to the Appkit application.

  <Note>At this point, Tomcat would still be accessible on port 8080, so if you visit `http://localhost:8080/myapp/`, you should see the same interface, except that your user is not authenticated.</Note>

  ## 6 Troubleshooting

  ### Users receive the error 'the request entity is too large' in the browser

  This is usually due to an issue with the Tomcat-ISAPI communication and the settings of the AJP connector in Tomcat must be modified to increase the maximum packet size:

  1. In the `workers.properties` file referenced by the tomcat-connection definition, set the packet size to the maximum:

     ```json theme={"dark"}
     worker.<worker name>.max_packet_size=65536
     ```
  2. Set `packetSize` in the AJP Connector definition:

     ```xml wrap theme={"dark"}
     <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" packetSize="65536" tomcatAuthentication="false" />
     ```
</Accordion>

## Configuration

Primary configuration is done via the `security.conf` configuration file and other files in the `/conf/security/` folder. The Security Module however also supports mechanisms like Spring Security that might require its own configuration files (for example, spring-security.xml) and custom elements in `web.xml`.

Define the security provider in `security.conf` using one of the following options:

```yaml wrap  theme={"dark"}
type: spring_security
type: saml
type: kerberos
type: tomcat7
type: generic
type: siteminder
type: passthrough
type: oauth
```

### Spring security

Spring Security is an industry standard security framework for Java. It is a popular option allowing the security to be configured initially via a simple XML file, and offers a lot of flexibility due to its integration with many different technologies, supporting a range of security standards. The [spring documentation](http://projects.spring.io/spring-security/) contains thorough guides to the use of Spring Security.

By default Appkit applications are configured to use Spring Security with a simple hard-coded set of credentials in the provided `spring-security.xml` file, but you can see some other common configurations **Set Up Spring Authentication**. Further documentation on configuring Spring Security can be [found here](http://docs.spring.io/spring-security/site/docs/3.0.x/reference/ns-config.html).

<Accordion title="Set Up Spring Authentication">
  {/* // Update how-to header information */}

  {/* // formatted */}

  {/* // tag::intro[] */}

  The Spring Security authentication provider for Appkit interfaces with both [Spring Security](http://projects.spring.io/spring-security/) 3 and 4. Projects that adopt Appkit version 3 must switch to using Spring Security 4.

  Authorized Spring principals become fully-qualified Appkit user profiles, along with any roles or groups that the Spring module provides. Spring Security integrates with a number of authentication protocols, including LDAP, Active Directory, Basic Authentication, Kerberos, JAAS, and others. For a full list, [see here.](http://docs.spring.io/spring-security/site/docs/3.1.1.RELEASE/reference/introduction.html)

  {/* // end::intro[] */}

  Below you will find some common configurations of the `spring-security.xml` file for integrating with different security mechanisms for authentication and authorization.

  <Note>The references given are for Spring Security 3. For information on how these configurations would change with Spring Security 4, refer to the Release Notes for Appkit 3.</Note>

  The first portion of the configuration file contains the required access levels for URL patterns used in Appkit and in most cases stays the same for all configurations.

  ### Hard-coded users

  ```xml expandable theme={"dark"}
  <?xml version="1.0" encoding="UTF-8"?>
  <beans:beans xmlns="http://www.springframework.org/schema/security"
               xmlns:beans="http://www.springframework.org/schema/beans"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.springframework.org/schema/beans
             http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
             http://www.springframework.org/schema/security
             http://www.springframework.org/schema/security/spring-security-3.1.xsd">

      <http pattern="/styles/**" security="none"/>
      <http pattern="/assets/**" security="none"/>
      <http pattern="/javascript/**" security="none"/>
      <http pattern="/wro/**" security="none"/>

      <http use-expressions="true" disable-url-rewriting="true">
          <intercept-url pattern="/login/" access="isAnonymous()"/>
          <intercept-url pattern="/twigkit/resources/**" access="isAnonymous() or isAuthenticated()"/>
          <intercept-url pattern="/twigkit/services/gsa/auth/**" access="isAnonymous() or isAuthenticated()"/>
          <intercept-url pattern="/mock-response/search" access="isAnonymous() or isAuthenticated()"/>
          <intercept-url pattern="/**" access="isAuthenticated()"/>
          <form-login login-page="/login/" authentication-failure-url="/login/?access=denied"/>
          <http-basic/>
          <logout logout-url="/logout/" logout-success-url="/"/>
      </http>

      <!--
          Simple Configuration Example
      -->
      <authentication-manager>
          <authentication-provider>
              <user-service>
                  <user name="admin" password="admin" authorities="USER, ADMIN"/>
                  <user name="user" password="user" authorities="USER"/>
              </user-service>
          </authentication-provider>
      </authentication-manager>
  </beans:beans>
  ```

  Here, you can see that two users are configured - 'user' and 'admin'. Both have been assigned the role named 'USER' and the admin user also has the 'ADMIN' role.

  ### LDAP

  ```xml expandable theme={"dark"}
  <?xml version="1.0" encoding="UTF-8"?>
  <beans:beans xmlns="http://www.springframework.org/schema/security"
               xmlns:beans="http://www.springframework.org/schema/beans"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.springframework.org/schema/beans
             http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
             http://www.springframework.org/schema/security
             http://www.springframework.org/schema/security/spring-security-3.1.xsd">

      <http pattern="/local-data/**" security="none"/>
      <http pattern="/styles/**" security="none"/>
      <http pattern="/assets/**" security="none"/>
      <http pattern="/javascript/**" security="none"/>
      <http pattern="/wro/**" security="none"/>

      <http use-expressions="true" disable-url-rewriting="true">
          <intercept-url pattern="/login/" access="isAnonymous()"/>
          <intercept-url pattern="/twigkit/resources/**" access="isAnonymous() or isAuthenticated()"/>
          <intercept-url pattern="/twigkit/services/gsa/auth/**" access="isAnonymous() or isAuthenticated()"/>
          <intercept-url pattern="/mock-response/search" access="isAnonymous() or isAuthenticated()"/>
          <intercept-url pattern="/**" access="isAuthenticated()"/>
          <form-login login-page="/login/" authentication-failure-url="/login/?access=denied"/>
          <http-basic/>
          <logout logout-url="/logout/" logout-success-url="/"/>
      </http>

      <!-- Active Directory Configuration -->
      <ldap-server id="ldapServer" url="ldap://my-ldap.my-domain.com:389/" manager-dn="gsaindexing@my-domain.com"
                   manager-password="ABC1234567890*" />

      <authentication-manager>
         <ldap-authentication-provider server-ref="ldapServer"
                                        user-search-base="OU=[Root],DC=uk,DC=corp,DC=my-domain,DC=com"
                                        user-search-filter="sAMAccountName={0}"
                                        group-role-attribute="cn"
                                        group-search-base="OU=[Root],DC=uk,DC=corp,DC=my-domain,DC=com"
                                        group-search-filter="(member={0})"
                                        role-prefix="ROLE_" />
      </authentication-manager>
  </beans:beans>
  ```

  Note the use of the LDAP protocol. In some cases, SSL encryption is used with the 'LDAPS' protocol. This requires the certificate to be trusted by the authentication client (the JVM running Appkit). There are several ways to configure the keystore for the JVM to trust the certificate from the LDAP server. The most common way to do this is to [import the certificate into the JVM’s default keystore](http://docs.oracle.com/cd/E19509-01/820-3399/ggfrj/index.html).

  ### Spring 'remember me' feature

  Spring Security comes with a mechanism for allowing a user’s details to be remembered beyond the current browser session, avoiding the user having to provide credentials on a login page every time. This integrates with the 'remember' attributes on the [widget:login-form](/docs/4/app-studio/reference/tags/lightning.directive.widgetLoginForm) tag.

  There are two methods to allow the user’s session to be persistent using either a browser cookie or a database backed persistence method. The first is most commonly used, and to implement this all that is required is to add the remember-me line to the `spring-security.xml` HTTP configuration:

  ```xml expandable theme={"dark"}
  <http use-expressions="true" disable-url-rewriting="true">
      <intercept-url pattern="/login/" access="isAnonymous()"/>
      <intercept-url pattern="/twigkit/resources/**" access="isAnonymous() or isAuthenticated()"/>
      <intercept-url pattern="/twigkit/services/gsa/auth/**" access="isAnonymous() or isAuthenticated()"/>
      <intercept-url pattern="/mock-response/search" access="isAnonymous() or isAuthenticated()"/>
      <intercept-url pattern="/**" access="isAuthenticated()"/>
      <form-login login-page="/login/" authentication-failure-url="/login/?access=denied"/>
      <http-basic/>
      <logout logout-url="/logout/" logout-success-url="/"/>
      <remember-me key="KEY-U5ED-F0R-C00KIE-ENCRYPT1ON"/>
  </http>
  ```

  ### Re-directing users to the original requested URL post-login

  Spring Security provides an authentication strategy that allows a requested URL to be saved before requiring the user to log in; once credentials have been authenticated the user is re-directed to the original URL.

  This strategy is implemented as part of the `<form-login ...>` tag defined via the `authentication-success-handler-ref`. For example:

  ```xml theme={"dark"}
  <form-login login-page="/login/"
                      authentication-failure-url="/login/?access=denied"
                      authentication-success-handler-ref="login_success_handler"/>
  ```

  The `login_success_handler` is a reference to the Spring Security class that implements the described strategy. This class is defined via this bean that needs to be added to the `spring-security.xml` as follows:

  ```xml theme={"dark"}
  <http..>
      ...

  </http>

  <beans:bean id="login_success_handler" class="org.springframework.security.web.authentication.SavedRequestAwareAuthenticationSuccessHandler"/>
  ```
</Accordion>

Appkit can be configured to use Spring Security for both authentication and role extraction.

### Container managed security

In this case the application server is responsible for authentication such as:

* Internet Information Server and Integrated Windows Authentication
* **Set Up Tomcat Container Authentication**

<Accordion title="Set Up Tomcat Container Authentication">
  {/* // Update how-to header information */}

  {/* // formatted */}

  {/* // tag::intro[] */}

  [Apache Tomcat](https://hub.docker.com/_/tomcat) is an open source Java servlet container. Tomcat implements Java enterprise specs, including the Java Servlet, JavaServer Pages JSP, and WebSockets APIs.

  {/* // end::intro[] */}

  To have Tomcat manage authentication for your application:

  1. Add this module to your POM (`pom.xml` file in the root of the application):

     ```xml theme={"dark"}
     <dependency>
      <groupId>twigkit</groupId>
      <artifactId>twigkit.security.provider.tomcat7</artifactId>
      <version>${project.parent.version}</version>
     </dependency>
     ```
  2. Set the requisite type in `security.conf` (found in `src/main/resources/conf/security/`):

     ```
     type: tomcat7
     ```

  This picks up the user and all roles from the configured Tomcat authentication mechanism. This is often used in Windows environments. More information on this type of authentication can be found [in the Tomcat documentation](http://tomcat.apache.org/tomcat-7.0-doc/windows-auth-howto.html).
</Accordion>

The application server can be configured to pick up the user’s credentials when the request is forwarded from a 'front-end' like IIS or Apache. In cases where authentication is done by the container it is still possible to do role extraction using Active Directory or LDAP for the user provider (see below).

### Generic security

The generic security option uses getRemoteUser() or the REMOTE\_USER variable provided through the servlet API. This is for authentication only, but it can be combined with other methods for picking up the roles assigned to a user and submitting them to the search platform (see Active Directory and LDAP role extraction below).

### Custom Providers

You can add your own SecurityProvider which would be responsible for providing the user identity to Appkit. To do this, implement the `twigkit.security.SecurityProvider` interface and bind the class using Guice in your custom module.

## Authorization, Role Extraction, and other features

#### Active Directory and LDAP Role Extraction

After the user’s identity has been established during the authentication stage, it is possible to carry out further authorization tasks such as role extraction or adding other metadata about the current user.

#### User and Domain Mapping

Appkit Security Module comes with pre-built filters to handle mapping between user names and domains. It is also possible to provide your own logic during this phase to deal with specific scenarios for determining a user’s credentials and details before rendering the page or passing them to the search platform.

## Security lifecycle

<img src="https://mintcdn.com/lucidworks/J_LymSfRoWq3UOvg/assets/images/appkit/4.2/jumly-gsa-query-response-1.png?fit=max&auto=format&n=J_LymSfRoWq3UOvg&q=85&s=6f1145888e827a73a74dfbb77543648f" alt="Security lifecycle" width="1152" height="965" data-path="assets/images/appkit/4.2/jumly-gsa-query-response-1.png" />

**1. Authentication**\
When the Security Module is installed, every request made to Appkit is filtered through the configured authentication provider. Credentials are added to the request via a ThreadLocal variable. Authentication providers can be container managed, single sign on or configured for form based authentication in Appkit.
You can create your own authentication provider by implementing and binding the twigkit.security.SecurityProvider class.

**2. Role Extraction**\
Next step in the filter chain can handle role/group extraction for the authenticated user. This is frequently done via an Active Directory/LDAP lookup. The role extraction mechanisms will add the roles for the user to the User object.

**3. Query**\
When the Security Module is used queries should be created using the secure version of the Query tag. The secure query tag will provide a reference to the user that is logged in and pass the identity on to the search platform if necessary. The Security Module also provides a number of processors and utilities for adding filters to the query based on business rules or identity/role information.

**4. Personalization**\
The User and Role information is available in the user interface. Using the Security Conditional tag you can customize the view to the user that is logged in.