Configuring CIFS

The aim of this configuration is to allow the use of OpenKM as a remote drive using the CIFS protocol. Two ways of configuiring it will be depicted below:

• Authentication using the Database
• Authentication using Active Directory

Database Authentication

This is the simplest case. You have to configure the following parts:

• OpenKM Server
• OpenKM Configuration
• Windows Client

OpenKM server

If the system cannot be started with root permissions, the ports commented below must be over 1024 (the default system ports are 138,137,139 and 445), so it is necessary to redirect the original ports to the new ones. To do this it is necessary to execute the following commands as root or using sudo:

modprobe iptable_nat
iptables -F
iptables -t nat -F
iptables -P INPUT ACCEPT
iptables -P FORWARD ACCEPT
iptables -P OUTPUT ACCEPT
iptables -t nat -A PREROUTING -p tcp --dport 445 -j DNAT --to-destination :1445
iptables -t nat -A PREROUTING -p tcp --dport 139 -j DNAT --to-destination :1139
iptables -t nat -A PREROUTING -p tcp --dport 137:139 -j DNAT --to-destination :1137-1139
iptables -t nat -A PREROUTING -p udp --dport 137:139 -j DNAT --to-destination  :1137-1139

Caution

Sometimes for testing purpose, it is required to access CIFS from the local server machine. In this case, the above configuration is insufficient and executing the following commands is required:

iptables -t nat -A OUTPUT -p tcp -d 127.0.0.1 --dport 445 -j REDIRECT --to-port 1445
iptables -t nat -A OUTPUT -p tcp -d 127.0.0.1 --dport 139 -j REDIRECT --to-port 1139
iptables -t nat -A OUTPUT -p tcp -d 127.0.0.1 --dport 137 -j REDIRECT --to-port 1137
iptables -t nat -A OUTPUT -p tcp -d 127.0.0.1 --dport 138 -j REDIRECT --to-port 1138

 OpenKM Configuration

To configure it go to Administration > Confguration and change the following properties:

Field / Property	Type	Description	Value
system.cifs.server	Boolean	Property to enable or disable CIFS.	true
system.cifs.authenticator.class	String	Class used by CIFS to authenticate against OpenKM.	com.openkm.integration.cifs.authenticator.DatabaseCIFSAuthenticator Depending the on authentication adapter values should be user the proper authenticar class: com.openkm.integration.cifs.authenticator.DatabaseCIFSAuthenticator com.openkm.integration.cifs.authenticator.LdapCIFSAuthenticator
system.cifs.debug	Boolean	Property used to allow a detailed log of CIFS functionality.	false
system.cifs.domain.name	String	Domain or workgroup where OpenKM server is installed.
system.cifs.hostname	String	Hostname where OpenKM is installed.	0.0.0.0
system.cifs.port.datagram	Integer	Port number used by datagrams.	By default 1138
system.cifs.port.name	Integer	Port number used by CIFS.	By default  1137
system.cifs.port.session	Integer	Port number used by session.	By default  1139
system.cifs.port.smb	Integer	Port number used by SMB.	By default 1445
system.cifs.shared.name	String	Property to inidicate the name of the repository	By default the name is repository

Caution

After changing these properties OpenKM must be restarted.

Caution

If it is not a fresh installation of OpenKM, it is important to reset user passwords from the OpenKM Administration Configuration (no matter if it is the same password) in order to generate an md4 version needed for authentication.

Windows client

It is necessary to modify a Local Security Policy. To do it, go to Control Panel → Administrative Tools → Local Security Policy → Local Policies → Security Options:

Note

Network Security Option: access LAN Manager Authentication Level and select: Send LM & NTLM: Use NTLMv2 session security if negotiated.

Note

You can also enable this by lauching the following command from the command line: 

REG ADD “HKLM\SYSTEM\CurrentControlSet\Control\Lsa” /v “LmCompatibilityLevel” /t “REG_DWORD” /d “1” /f

Maybe you need to restart the operating system too.

 Then to connect to the remote machine, go to Computer → Map Network Drive:

• Drive: Any letter available
• Folder: \\server_ip\repository OR \\server_name\repository
• Connect using different credentials (chek it if the Windows user and password are different to OpenKM user).

Then click on the finish button.

Caution

If connecting using different credentials was checked, a new window to input the corresponding credentials will appear.

Note

You can also do this by lauching the following command from command line: 

net use \\\ /user: and as an example: net use Z: \\server_ip\repository OR \\server_name\repository /user:okmAdmin admin_password

Active Directory Authentication

In this case, we are beginning with the assumption that the system has already been integrated with Active directory. From this point it will be necessary to configure:

• Active Directory
• OpenKM Server
• OpenKM configuration
• Windows client

Active Directory

It is necessary to create a user that OpenKM, using a private key, will use to validate the credentials of the incoming CIFS request. To do so, the next steps must be followed:

1. Create a Computer Object that will be the one corresponding with the OpenKM server.

2. Once created, modify its properties by enabling the property Trusted for Delegation.

   1. Trusted for Delegation: This step is important because, if not enabled, it will not be possible for the client and server to negotiate.

3. The server must authenticate against Active Directory before validating the tickets sent by the client.This authentication is performed using a file (keytab) that maps the service (application server) with a domain user. This user must be used only and exclusively for this purpose because if this user is used to login on another computer, this user will cannot be be loged in to the application server at the same time. Once the user is created, its properties are set to not allow the modification of the password and prevent the expiration of the account . Finally, select the Account tab and enable the Do not require Kerberos preauthentication option in the Account Options selection. For this example, the created user is called servercifs.

4. Select the Account tab and enable the Do not require Kerberos preauthentication option in the Account Options section.

5. Generate keytab file. This file is an encoded copy of the private key of a user in kerberos. It is used by the web application as an authentication proxy of the credentials sent by the user. The following command is executed:

    ktpass -princ cifs/tomcat.example.com@EXAMPLE.COM -mapuser servercifs@EXAMAPLE.COM -crypto all -kvno 0 \        -ptype KRB5_NT_PRINCIPAL -pass * -out cifs.keytab -kvno 0

   • it is important to highlight:
     1. tomcat.example.com@EXAMPLE.COM: the full name of the tomcat server and its domain.
     2. servercifs@EXAMAPLE.COM : the user created previously.
     3. cifs.keytab: file where the private key is exported that will be used by the Tomcat server.

6. A Service Principal Name (SPN) needs to be set up with CIFS and a server name:forexample: tomcat.example.org where tomcat servlet container is running. This is used with domain user anditskeytab is then used as a service credential:

   C:\> setspn -A cifs/tomcat.example.org servercifs
   
   C:\> setspn -A cifs/tomcat.example.org servercifs@EXAMPLE.COM

   Note

   Where tomcat.example.org is the machine where the tomcat servlet container is running and servercifs is the user previously created. 

   Usually the previous command “ktpass” should create the service cifs/tomcat.example.org, when it is created an error will be raised indicating is already present.

OpenKM server in Active Directory configuration

The following steps must be folowed:

Introduce server in domain

The first thing to do is to include the application server inside the domain, if it was not done previously. To do it follow the guide below:

http://cerowarnings.blogspot.com.es/2011/11/how-to-linux-en-dominio-windows.html

One thing to take into account is to add the following configuration to the file /etc/host to prevent known issues:

# ldap in /etc/hosts
192.168.1.110 example.com
192.168.1.110 Schema.Configuration.example.com
192.168.1.110 Configuration.example.com
192.168.1.110 DomainDnsZones.example.com
192.168.1.110 ForestDnsZones.example.com

Redirect the required ports

If the system could not be started with root permissions, the ports commented bellow must be over 1000 (the default system ports are 138,137,139,445), so it is necessary to redirect the original ports to the new ones. To do this it is necessary to execute the following commands as root or using sudo:

$ modprobe iptable_nat
$ iptables -F
$ iptables -t nat -F
$ iptables -P INPUT ACCEPT
$ iptables -P FORWARD ACCEPT
$ iptables -P OUTPUT ACCEPT
$ iptables -t nat -A PREROUTING -p tcp --dport 445 -j DNAT --to-destination :1445
$ iptables -t nat -A PREROUTING -p tcp --dport 139 -j DNAT --to-destination :1139
$ iptables -t nat -A PREROUTING -p tcp --dport 137:139 -j DNAT --to-destination :1137-1139
$ iptables -t nat -A PREROUTING -p udp --dport 137:139 -j DNAT --to-destination  :1137-1139

Caution

Sometimes for testing purpose, it is required to access CIFS from the local server machine. In this case, the above configuration is insufficient and the following commands are required:

$ iptables -t nat -A OUTPUT -p tcp -d 127.0.0.1 –dport 445 -j REDIRECT –to-port 1445
$ iptables -t nat -A OUTPUT -p tcp -d 127.0.0.1 –dport 139 -j REDIRECT –to-port 1139
$ iptables -t nat -A OUTPUT -p tcp -d 127.0.0.1 –dport 137 -j REDIRECT –to-port 1137
$ iptables -t nat -A OUTPUT -p tcp -d 127.0.0.1 –dport 138 -j REDIRECT –to-port 1138

kerberos configuration file

Install kerberos client:

$ apt-get krb5-user krb5-config

Before starting the application Kerberos must be configured properly to validate tickets correctly. In Linux systems this file is located at “/etc/kbr5.conf”.

In this file Domain, KDC server and allowed algorithms must be specified. The most importans algorithms are arcfour-hmac-md5 and rc4-hmac which Microsoft Active Directory offers.

Caution

From the default krb5.con configuration, make only the suggested changed shown below.

[libdefaults]
default_realm = EXAMPLE.COM
#these are mandatory for kerberos.
permitted_enctypes = aes128-cts rc4-hmac
default_tgs_enctypes = aes128-cts rc4-hmac
default_tkt_enctypes = aes128-cts rc4-hmac
[realms]
EXAMPLE.COM = {
   kdc = SERVER.example.com
   admin_server = SERVER.example.com
  default_domain = EXAMPLE.COM
}
[domain_realm]
  example.com = EXAMPLE.COM
 .example.com = EXAMPLE.COM

 cifs.login.config File

Create a configuration file needed to enable java login with content:

JLANServerCIFS{
com.sun.security.auth.module.Krb5LoginModule required
storeKey=true
useKeyTab=true
keyTab="/path/to/cifs.keytab"
principal="cifs/tomcat.example.com";
};

As we can observe:

• JLANServerCIFS correspond with the property system.cifs.ldap.login.entry
• Property principal correspind to the property: system.cifs.ldap.principal
• Property keytab it is the secure place where the previously created .keytab file that contains the key to access Active directory has been copied.

Note

The file is usually found in the folder JRE/lib/security. However it can be placed anywhere with a minimum amount of security.

Enable Java login configuration.

To enable java login, it is necessary to change the configuration of the Java security file that it is usually placed in: JRE/lib/security/java.security and add the following line:

login.config.url.1= file:${java.home}/lib/security/cifs.login.config where cifs.login.config is the file created in the prevous section.

Note

The default value ${java.home}/lib/security could be change to any other route where the previous created file jlan.login.config has been stored.

OpenKM Configuration in Active Directory Configuration

To configure it: go to Aministration > Confguration and change the following properties:

Field / Property	Type	Description	Value
system.cifs.server	Boolean	Property to active or deactive CIFS	true
system.cifs.authenticator.class	String	Class used by CIFS to authenticate against OpenKM	com.openkm.integration.cifs.authenticator.LdapCIFSAuthenticator Depending the on authentication adapter values the proper authenticator class should be used: com.openkm.integration.cifs.authenticator.DatabaseCIFSAuthenticator com.openkm.integration.cifs.authenticator.LdapCIFSAuthenticator
system.cifs.debug	Boolean	Property used to allow  detailed log of CIFS functionality	false
system.cifs.domain.name	String	Domain or work group where OpenKM server is installed	EXAMPLE
system.cifs.hostname	String	Hostname where OpenKM is installed	0.0.0.0
system.cifs.ldap.kdc	String	Name of the Active directory server	server.example.com
system.cifs.ldap.principal	String	Service created previously in Active Directory	cifs/tomcat.example.com
system.cifs.ldap.password	String	Password of the user created for authentication purpose	In the example the user was servercifs
system.cifs.ldap.realm	String	Name of the domain where Active directory is installed	EXAMPLE.COM
system.cifs.ldap.login.entry	String	Kerberos configuration name inside the configuration file	JLANServerCIFS
system.cifs.port.datagram	Integer	Port number used by datagrams	By default 1138
system.cifs.port.name	Integer	Port number used by cifs	By default 1137
system.cifs.port.session	Integer	Port number used by session	By default 1139
system.cifs.port.smb	Integer	Port number used by smb	By default 1445
system.cifs.shared.name	String	Property to inidicate the name of the repository	By default the name is repository

Caution

After changing these properties, OpenKM must be restarted.

Windows client in Active Directory configuration

It is necessary to modify a Local Security Policy. To do it, go to Controls Panel → Administrative Tools → Local Security Policy → Local Policies → Security Options: 

Note

Network Secutiry Option: LAN Manager authentication Level and select: Send LM & NTLM: Use NTLMv2 session security if negotiated.

Note

You can also do it by lauching the following command from command line: 

REG ADD “HKLM\SYSTEM\CurrentControlSet\Control\Lsa” /v “LmCompatibilityLevel” /t “REG_DWORD” /d “1” /f

  Then, to connect to the remote machine, go to Computer → Map Network Drive:

• Drive: Any letter available
• Folder: \\server_name\repository
• Connect using different credentials (chek if the Windows user and passwords are different from the OpenKM user).

Then click on the finish button. 

Caution

If “connect using different credentials” was checked, a new window to input the corresponding credentials will appear.

Note

You can also do it by lauching the following command from command line: 

net use \\\ /user: and as an example: net use Z: \\server_name\repository /user:okmAdmin admin_password