Configuring CIFS

The aim of this configuration is to allow to see OpenKM as a remote drive using CIFS protocol. Bellow it will be depicted two ways of configuiring it:

  • Authentication using Database
  • Authentication using Active Directory

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:

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

Sometimes for testing purpose, it is required to access CIFS from the local server  machine. In this case, the above configuration is insufficient and it is required to 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 > Confguration and change the following properties:

Field / PropertyTypeDescriptionValue
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  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

After changing these properties OpenKM must be restarted.

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

Windows client

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:

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

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_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 finish button.

If connect using different credentials was checked, a new window where introduce the corresponding credentials will appear.

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

net use <driver letter> \\<servername>\<sharename> /user:<username> <password> and as an example: net use Z: \\server_ip\repository OR \\server_name\repository /user:okmAdmin admin_password

Active Directory Authentication

In this case, it is considered that the system was integrated previously with Active directory.  In this case it will be necessary to configure:

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

Active Directory

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

  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 negotiate among client and 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 map 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 logon in another computer, this user will not be able to be used to logon the application server. Once created the user, its properties are modified to not allow the modification of the password and the non expiration of the account. Finally, select the Account tab and enable Do not required Kerberos preauthentication option in the Account Options selection. For this example, it is created a user call servercifs.
  1. Select the Account tab and enable the Do not require Kerberos preauthentication option in the Account Options section.
  1. 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 highlight :
      1. tomcat.example.com@EXAMPLE.COM:  full name of the tomcat server and its domain.
      2. servercifs@EXAMAPLE.COM : user created previously.
      3. cifs.keytab: file where it is exported the private key that will be used by the Tomcat server.
  2. A Service Principal Name (SPN) needs to be setup with CIFS and a server name: in example: tomcat.example.org where tomcat servlet container is running. This is used with 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

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

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

    Usually the previous command "ktpass" should create the service cifs/tomcat.example.org, when it's created will be raised an error indicating is yet 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:

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 due to previously known problems:

# 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

Sometimes for testing purpose, it is required to access CIFS from the local server  machine. In this case, the above configuration is insufficient and it is required to 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/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.

Preservate almost krb5.con default configuration and 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 can be observed:

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

The file is usually found in the folder JRE/lib/security. However it could be placed in any place with a minimum 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 place at: JRE/lib/security/java.secutity 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.

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 / PropertyTypeDescriptionValue
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 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  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 configurations 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

After changing this 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

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

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 it if the Windows user and passwords are different to OpenKM user).

Then click on finish button. 

If connect using different credentials was checked, a new window where introduce the corresponding credentials will appear.

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

net use <driver letter> \\<servername>\<sharename> /user:<username> <password> and as an example: net use Z: \\server_name\repository /user:okmAdmin admin_password