3.0 Configuring NTLM

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Authentication
2.x3.03.1

This page describes configuration methods prior to Alfresco Version 3.2. Refer to Alfresco Authentication Subsystems for Alfresco Versions 3.2 and up.

NTLM authentication can be used to provide single signon to Alfresco 3.0 Explorer client and the new Alfresco 3.0 Share client. The password that is sent over the network is more secure than when using basic authentication. Note that since Alfresco 3.0 NTLMv2 is now supported which is more secure that the NTLMv1 previously supported - and NTLMv2 will automatically downgrade to NTLMv1 if the client does not support it.

NTLM passthru authentication can also be used to replace the standard Alfresco user database and use a Windows server/domain controller, or list of servers, to authenticate users accessing Alfresco. This saves having to create user accounts within Alfresco.

Note that the support of NTLMv2 is only for configurations storing psswords (or hashes) in Alfresco. As NTLMv2 has been designed to avoid 'man-in-the-middle' attacks, any passthru authentication is impossible.

Table of Contents

• 1 Alfresco Explorer and WebDav SSO using NTLM


• 2 Alfresco Share SSO using NTLM


• 3 NTLM Passthru Authentication
  
  
  
  • 3.1 NTLM Passthru Properties
  
  
  • 3.2 Domain Mappings
  
  
  • 3.3 Possible problems
  
  
  • 3.4 Enabling NTLM users
  
  

Alfresco Explorer and WebDav SSO using NTLM

By using NTLM authentication to access Alfresco Explorer and Alfresco WebDAV sites the web browser can automatically login.

Internet Explorer will use your Windows logon credentials when requested by the web server when NTLM is configured. Firefox and Mozilla also support the use of NTLM but you need to add the URI to the Alfresco site that you want to access to network.automatic-ntlm-auth.trusted-uris option (available through writing about:config in the URL field) to allow the browser to use your current credentials for login purposes.

The Opera web browser does not currently support NTLM authentication, the browser is detected and will be sent to the usual Alfresco logon page.

To configure NTLM authentication for the Alfresco web application, edit the web.xml file in the WEB-INF folder and change the servlet filter that is used. Change the following :-

  <filter>
     <filter-name>Authentication Filter</filter-name>
     <filter-class>org.alfresco.web.app.servlet.AuthenticationFilter</filter-class>
  </filter>

to use the NTLM servlet filter

  <filter>
     <filter-name>Authentication Filter</filter-name>
     <filter-class>org.alfresco.web.app.servlet.NTLMAuthenticationFilter</filter-class>
  </filter>

also add the following servlet filter mappings :-

  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/navigate/*</url-pattern>
  </filter-mapping>

  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/command/*</url-pattern>
  </filter-mapping>

  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/download/*</url-pattern>
  </filter-mapping>
  
  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/template/*</url-pattern>
  </filter-mapping>
  
  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/n/*</url-pattern>
  </filter-mapping>
  
  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/c/*</url-pattern>
  </filter-mapping>

  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/t/*</url-pattern>
  </filter-mapping>
  
  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/d/*</url-pattern>
  </filter-mapping>
  
  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/wcservice/*</url-pattern>
  </filter-mapping>
  
  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/wcs/*</url-pattern>
  </filter-mapping>
  
  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/ajax/*</url-pattern>
  </filter-mapping>

Important Note: Changes for Alfresco 3.0SP1 and Alfresco Labs3Stable - there is an additional commented out section in the web.xml file that should be enabled:

  <filter>
     <filter-name>WebScript NTLM Authentication Filter</filter-name>
     <filter-class>org.alfresco.web.app.servlet.WebScriptNTLMAuthenticationFilter</filter-class>
  </filter>

In addition please use the modified filter-mapping section that will already be present in the web.xml file - these sections are different and relate to the above filter addition:

  <filter-mapping>
     <filter-name>WebScript NTLM Authentication Filter</filter-name>
     <url-pattern>/wcservice/*</url-pattern>
  </filter-mapping>
  
  <filter-mapping>
     <filter-name>WebScript NTLM Authentication Filter</filter-name>
     <url-pattern>/wcs/*</url-pattern>
  </filter-mapping>

To configure NTLM authentication for Alfresco WebDAV access edit the web.xml file and change the following :-

  <filter>
     <filter-name>WebDAV Authentication Filter</filter-name>
     <filter-class>org.alfresco.repo.webdav.auth.AuthenticationFilter</filter-class>
  </filter>

to use the NTLM servlet filter

  <filter>
     <filter-name>WebDAV Authentication Filter</filter-name>
     <filter-class>org.alfresco.repo.webdav.auth.NTLMAuthenticationFilter</filter-class>
  </filter>

Note: All NTLM filter settings should already be in the web.xml file in commented out sections.

Alfresco Share SSO using NTLM

By using NTLM authentication to access Alfresco Share sites the web browser can automatically login.

In Alfresco 3.0 the new Alfresco Share application exists as an entirely separate web application to the main Alfresco Repository/Explorer WAR file. It can run in the same app-server instance on the same machine to the main Alfresco web application or can run on a completely separate app-server instance on a completely different machine altogether. The Share application uses HTTP(S) to communicate with the configured Alfresco Repository. Therefore to use NTLM with Share, you must first enable NTLM for Alfresco Explorer web application as above, then edit the Share application web.xml file in the WEB-INF folder and change the servlet filter that is used. Enable the following servlet filter:

  <filter>
     <filter-name>Authentication Filter</filter-name>
     <filter-class>org.alfresco.web.site.servlet.NTLMAuthenticationFilter</filter-class>
     <init-param>
        <param-name>endpoint</param-name>
        <param-value>alfresco</param-value>
     </init-param>
  </filter>

Then add the following filter mappings:

  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/page/*</url-pattern>
  </filter-mapping>
  
  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/p/*</url-pattern>
  </filter-mapping>
  
  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/s/*</url-pattern>
  </filter-mapping>

Note: The NTLM settings should already be in the web.xml file in a commented out section.

Finally, you need to make a configuration change to the Share application. The Share web application supports overriding of application config files in a very similar way to the Alfresco Explorer web client. To use NTLM with Share, find the .sample configuration override file:

\tomcat\shared\classes\alfresco\web-extension\webscript-framework-config-custom.xml.sample

Copy and rename the file to:

\tomcat\shared\classes\alfresco\web-extension\webscript-framework-config-custom.xml

Then edit the file and uncomment this section thus:

   <config evaluator='string-compare' condition='Remote'>
      <remote>
         
         <endpoint>
            <id>alfresco</id>
            <name>Alfresco - user access</name>
            <description>Access to Alfresco Repository WebScripts that require user authentication</description>
            <connector-id>alfresco</connector-id>
            <endpoint-url>http://yourserver:8080/alfresco/wcs</endpoint-url>
            <identity>user</identity>
            <external-auth>true</external-auth>
         </endpoint>
         
      </remote>
   </config>

Note: change the endpoint-url value to point to your Alfresco Server location.

Note: the additional <external-auth>true</external-auth> parameter since 3.0SP1/Labs3Stable.

Now restart the Share web application. If you have correctly setup NTLM for both the Alfresco repository and Share web applications NTLM will be the active authentication mechanism.

NTLM Passthru Authentication

NTLM passthru authentication can be used instead of the Alfresco user database. In this case a Windows server such as a domain controller is used to authenticate the user and provides the list of available users.

To configure Alfresco to use one or more Windows servers for passthru authentication rename the ntlm-authentication-context.xml.sample file located in the directory /alfresco/extension to ntlm-authentication-context.xml. Please note that the /alfresco/extension directory containing the sample configuration files may be located in the shared classpath of the application server such as [TOMCAT_HOME]/shared/classes as is the case in the Tomcat distribution of Alfresco.

The above file registers NTLM implementations of the authenticationDao and authenticationComponent bean definitions.

    <bean id='authenticationDao' class='org.alfresco.repo.security.authentication.DefaultMutableAuthenticationDao'>
        <property name='allowSetEnabled' value='true' />
        <property name='allowGetEnabled' value='true' />
        <property name='allowDeleteUser' value='true' />
        <property name='allowCreateUser' value='true' />
    </bean>    

    <bean id='authenticationComponent'
          class='org.alfresco.repo.security.authentication.ntlm.NTLMAuthenticationComponentImpl'
          parent='authenticationComponentBase'>
        <property name='useLocalServer'>
            <value>true</value>
        </property>
        <property name='personService'>
            <ref bean='personService' />
        </property>
        <property name='nodeService'>
            <ref bean='nodeService' />
        </property>
        <property name='transactionService'>
            <ref bean='transactionComponent' />
        </property>
        <property name='guestAccess'>
            <value>true</value>
        </property>
    </bean>

NTLM Passthru Properties

There are a number of properties available to configure the NTLM authentication component bean, note that the 'domain' and 'servers' properties are mutually exclusive :-

• domain
  

Set the domain to use for passthru authentication. This will attempt to find the domain controllers using a network broadcast. Make sure that you use the Windows NetBIOS domain name, not the forest name.  The network broadcast does not work in all network configurations, in this case use the server property to specify the domain controller list by name or address. 

• guestAccess
  

Allow guest access to Alfresco if the authenticating server indicates the logon was allowed guest access. Valid values are true or false.
This option should not be used as guest access does not currently map to a valid Person object in Alfresco.

• servers
  

Comma delimited list of server names or addresses that are used for authentication. The passthru authenticator will load balance amongst the available servers, and can monitor server online/offline status.

Each server name/address may be prefixed with a domain name using the format <domain>\<server>. If the client specifies a domain name in its logon request then the appropriate server will be used for the authentication. Domain mappings may also be specified to route authentication requests to the appropriate server (see below).

If a server handles authentication for multiple domains then multiple entries can be added in the server list prefixed with each domain name.

There should be at least one entry in the server list that does not have a domain prefix, this is the catch all entry that will be used if the client domain cannot be determined from the NTLM request or via domain mapping.

NOTE: The servers parameter should not be set in conjunction with useLocalServer. You may only set one or the other. For example:

       <property name='useLocalServer'>
           <value>false</value>
       </property>
       <property name='servers'>
           <value>192.168.4.12,192.168.4.11</value>
       </property>

• useLocalServer
  

Use the local server for passthru authentication by using loopback connections into the server. Valid values are true or false.

• protocolOrder
  

Specifies the type of protocols and the order of connection for passthru authentication sessions. The default is to use NetBIOS, if that fails then try to connect using native SMB/port 445.
Specify either a single protocol type or a comma delimited list with a primary and secondary protocol type. The available protocol types are 'NetBIOS' for NetBIOS over TCP and 'TCPIP' for native SMB.

• offlineCheckInterval
  

Specifies how often passthru servers that are marked as offline are checked to see if they are now online. The default check interval is 5 minutes.
The check interval is specified in seconds.

Domain Mappings

Domain mappings are used to determine the domain a client is a member of when the client does not specify its domain in the logon request.

To specify the domain mapping rules that are used when the client does not supply it's domain in the NTLM request add the <DomainMappings> section to the file-servers.xml 'Filesystem Security' config section :-

<DomainMappings>
  <Domain name='ALFRESCO' subnet='192.168.1.0' mask='192.168.1.255'/>
</DomainMappings>

There are two types of domain mapping rule available :-

 <Domain name='...' subnet='...' mask='...'/>
 <Domain name='...' rangeFrom='...' rangeTo='...'/>

The NTLM authentication component can also use the domain prefixed server name format and also use the domain mappings to route authentication requests to the appropriate server.

A sample NTLM authentication component server list :-

<property name='servers'>
  <value>ALFRESCO\ADSERVER,OTHERDOM\OTHERSRV</value>
</property>

If the client uses a numeric IP address to access the web server it will not send the domain in the NTLM request as the browser assumes it is an Internet address.

Possible problems

When you see an error after overriding the NTLM configuration in the the application-context.xml file saying:

Error creating bean with name 'descriptorComponent' defined in class path resource [alfresco/application-context.xml]: 
Can't resolve reference to bean 'systemBootstrap' while setting property 'systemBootstrap';

You can try to override the 'db.url' property line in the 'repository.properties' file to:

db.url=jdbc:mysql:///${db.name}?useServerPrepStmts=false

Enabling NTLM users

Configuring Alfresco to use NTLM has the (often unexpected) side-effect of disabling the existent admin account. The solution is to 'enable' an existent NTLM user. File custom-authority-services-context.xml in tomcat\shared\classes\alfresco\extension (or equivalent) allows such a configurations.
(in 2.1(linux) it can be found in tomcat/webapps/alfresco/WEB-INF/classes/alfresco/authority-services-context.xml

For example...

<beans>
    <bean id='authorityService' class='org.alfresco.repo.security.authority.AuthorityServiceImpl'>
        <property name='authenticationComponent'>
            <ref bean='authenticationComponent' />
        </property>
        <property name='personService'>
            <ref bean='personService' />
        </property>
        <property name='nodeService'>
            <ref bean='nodeService' />
        </property>
        <property name='authorityDAO'>
            <ref bean='authorityDAO' />
        </property>
        <property name='permissionServiceSPI'>
            <ref bean='permissionServiceImpl' />
        </property>
        <property name='adminUsers'>
            <set>
                <value>smithj</value> <!-- add an NTLM user as an Administrator -->
                <value>admin</value>
                <value>administrator</value>
            </set>
        </property>
        <property name='adminGroups'>
            <set>
                <value>ALFRESCO_ADMINISTRATORS</value>
            </set>
        </property>
    </bean>
</beans>