Configuring CIFS

The aim of this configuration is to allow viewing OpenKM as a remote drive using CIFS protocol. Below, two ways of configuring it are described:

• Database authentication
• Authentication using Active Directory

Caution

This integration works only with SMBv1, which is disabled by default in Windows 10. If you want to enable it, open a PowerShell and follow these steps:

> Get-WindowsOptionalFeature -Online -FeatureName smb1protocol
> Disable-WindowsOptionalFeature -Online -FeatureName smb1protocol
> Enable-WindowsOptionalFeature -Online -FeatureName smb1protocol

After that, you need to restart the server. More info at How to detect, enable and disable SMBv1, SMBv2, and SMBv3 in Windows.

Database Authentication

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

• OpenKM Server
• OpenKM Configuration
• Windows Client

OpenKM server

If the system could not 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:

echo 1 > /proc/sys/net/ipv4/ip_forward
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 purposes, it is necessary to access CIFS from the local server machine. In this case, the above configuration is insufficient and you must execute the following commands:

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 > Configuration 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 on the 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 enable detailed logging 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 indicate 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 in OpenKM Administration Configuration (no matter if they are the same) in order to generate the MD4 version needed for authentication.

Windows client

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

Note

Set the option “Network security: LAN Manager authentication level” to: Send LM & NTLM: Use NTLMv2 session security if negotiated.

Note

You can also do this by launching the following command from the 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_ip\repository OR \\server_name\repository
• Connect using different credentials (check this if the Windows username and password are different from the OpenKM user).

Then click the Finish button.

Caution

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

Note

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

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

Caution

If you get a wrong password error, try resetting the password of the user from OpenKM Administration Configuration.

Active Directory Authentication

In this case, it is assumed that the system was previously integrated with Active Directory. The following will need to be configured:

• 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 this, follow these steps:

1. Create a Computer Object that will be the one corresponding to 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 to negotiate between the client and the server.

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) to a domain user. This user must be used only and exclusively for this purpose because if this user is used to log on to another computer, it will not be able to log on to the application server. Once the user is created, modify its properties to prevent password changes and to prevent the account from expiring. Finally, select the Account tab and enable the Do not require Kerberos preauthentication option in the Account Options selection. For this example, a user called servercifs is created.

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 an 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 note:
     1. tomcat.example.com@EXAMPLE.COM:  full name of the Tomcat server and its domain.
     2. servercifs@EXAMPLE.COM : user created previously.
     3. cifs.keytab: file where the private key exported for use by the Tomcat server is stored.

6. A Service Principal Name (SPN) needs to be set up with CIFS and a server name, for example: tomcat.example.org where the Tomcat servlet container is running. This is used with the domain user, and its keytab 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 the user is the user previously created. 

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

OpenKM server in Active Directory configuration

The following steps must be followed:

Introduce the server into the domain

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

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/hosts due to previously 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 cannot be started with root permissions, the ports mentioned below must be above 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, 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 purposes, it is necessary to access CIFS from the local server machine. In this case, the above configuration is insufficient and you must execute the following commands:

$ 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/krb5.conf”.

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

Caution

Preserve the krb5.conf default configuration and make only the suggested changes 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 the following content:

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

As can be observed:

• JLANServerCIFS corresponds with the property system.cifs.ldap.login.entry
• Property principal corresponds to the property: system.cifs.ldap.principal
• The keytab property is the secure location where the previously created .keytab file containing the key to access Active Directory has been copied.

Note

The file is usually found in the folder JRE/lib/security. However, it could be placed in any location with minimal security.

Enable Java login configuration.

To enable Java login, it is necessary to change the configuration of the Java security file that is usually placed at: 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 previous section.

Note

The default value ${java.home}/lib/security could be changed to any other path where the previously created file cifs.login.config has been stored.

OpenKM Configuration in Active Directory Configuration

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

Field / Property	Type	Description	Value
system.cifs.server	Boolean	Property to activate or deactivate CIFS	true
system.cifs.authenticator.class	String	Class used by CIFS to authenticate against OpenKM	com.openkm.integration.cifs.authenticator.LdapCIFSAuthenticator Depending on the 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 enable detailed logging of CIFS functionality	false
system.cifs.domain.name	String	Domain or workgroup 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 purposes	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 indicate 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 this, go to Control Panel → Administrative Tools → Local Security Policy → Local Policies → Security Options:

Note

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

Note

You can also do this by launching the following command from the 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 (check this if the Windows username and password are different from the OpenKM user).

Then click the Finish button. 

Caution

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

Note

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

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