Configuring NTLM

[resplin]

Obsolete Pages{{Obsolete}}

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

Authentication
Please Note: This article describes configuration methods now outdated in the Alfresco version 3.2 release. For a more up to date description, refer to Alfresco Authentication Subsystems.

NTLM authentication can be used to provide single signon to Alfresco,and the password that is sent over the network is more secure than when using basic authentication.

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.

Table of Contents

• 1 Using Client Side NTLM


• 2 NTLM Passthru Authentication
  
  
  
  • 2.1 NTLM Passthru Properties
  
  
  • 2.2 Domain Mappings
  
  
  • 2.3 Possible problems
  
  
  • 2.4 Version 2.0 and NTLM Authentication
  
  
  • 2.5 Enabling NTLM users
  
  
  • 2.6 Current restrictions
  
  

Using Client Side NTLM

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

Internet Explorer will use your Windows logon credentials when requested by the web server when NTLM is configured.
If IE sends the login popup window this probably means you will need to add the URL of your alfresco server to your IE Intranet sites in

Tools->Options->Security->Local Intranet ->Sites->adavanced
In the Intranet security->custom, at the bottom of the list
did you tick
User Authentication->Logon->Automatic login with current user name and password? (the 2nd possibility ''automatic logon only in Intranet zone' may also work depending on your settings)

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 support NTLM authentication, the browser is detected and will be sent to the usual Alfresco logon page.

To configure NTLM authentication for the main Alfresco site 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 mapping :-

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

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

To configure NTLM authentication for Alfresco WebDAV access edit the web.xml file in the WEB-INF folder 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>

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.samples 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/alfresco/extension as is the case in the Tomcat distribution of Alfresco.

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

    <bean id='authenticationDao' class='org.alfresco.repo.security.authentication.ntlm.NullMutableAuthenticationDao'>
       <property name='nodeService'>
           <ref bean='nodeService' />
       </property>
    </bean>      

    <bean id='authenticationComponentImpl' class='org.alfresco.repo.security.authentication.ntlm.NTLMAuthenticationComponentImpl'>
        <property name='useLocalServer'>
            <value>true</value>
        </property>
        <property name='personService'>
            <ref bean='personService' />
        </property>
        <property name='nodeService'>
            <ref bean='nodeService' />
        </property>
        <property name='guestAccess'>
            <value>false</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
  

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

Each server name or address can be prefixed with a domain name using the format <domain>\<server>. If the client specifies a domain name in its login 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. If a server handles authentication for multiple domains, then multiple entries can be added in the server list. Each entry must be prefixed with each domain name.

When a CIFS or HTTP client sends an NTLM logon, the NTLM details usually contain the client domain name. If the passthrough server list contains entries that have a domain prefix, then this will be used to route the passthrough request to the appropriate domain controller. Usually there should be at least one server list entry that does not have a domain prefix; this will be the catch all that is used when the client does not specify a domain.

The <DomainMappings> configuration tries to map particular network addresses or subnets to particular domain names. If the client NTLM request does not contain a domain name, then the domain mappings will be used to try and map the network address to a domain. If that fails, then the catch all server entry will be used as the passthrough server to which to authenticate against.

The <DomainMappings> configuration is optional. In an enterprise network, where the clients are logged onto a domain, it is not needed.

The same server can appear in the list as many times as required. If the same server handles logons for multiple domains, and could also be the catch all server.

Note: The servers parameter must 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>ALFRESCO\192.168.4.61, 192.168.4.61</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 could try to modify (= override since version 1.2) the 'db.url' property line in the 'repository.properties' file to:

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

After rebooting the Alfresco system the error was gone.

Version 2.0 and NTLM Authentication

Having reconfigured Alfresco v2.0 to use NTLM authentication, should login attempts fail, and an exception such as

Caused by: org.alfresco.error.AlfrescoRuntimeException: Not implemented
        at org.alfresco.repo.security.authentication.ntlm.NullMutableAuthenticationDao.loadUserByUsername(NullMutableAuthenticationDao.java:316)
        at net.sf.acegisecurity.providers.dao.DaoAuthenticationProvider.getUserFromBackend(DaoAuthenticationProvider.java:390)
        at net.sf.acegisecurity.providers.dao.DaoAuthenticationProvider.authenticate(DaoAuthenticationProvider.java:225) 

...appear then change the bean id attribute from 'authenticationComponentImpl' to 'authenticationComponent'.

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 existant 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>
    </bean>
</beans>

Current restrictions

• Alfresco v2.0 appears not to support NTLM logins from trusted domains.