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
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
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 |
After changing these properties, OpenKM must be restarted.
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:
Set the option "Network security: LAN Manager authentication level" to: Send LM & NTLM: Use NTLMv2 session security if negotiated.
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.
If "Connect using different credentials" was checked, a new window to enter the corresponding credentials will appear.
You can also do this by launching the following command from the command line:
net use <drive letter> \\<servername>\<sharename> /user:<username> <password> and, as an example: net use Z: \\server_ip\repository OR \\server_name\repository /user:okmAdmin admin_password
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:
- Create a Computer Object that will be the one corresponding to the OpenKM server.
- Once created, modify its properties by enabling the property Trusted for delegation.
- Trusted for delegation. This step is important because, if not enabled, it will not be possible to negotiate between the client and the server.
- 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.
- Select the Account tab and enable the Do not require Kerberos preauthentication option in the Account Options section.
-
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.
- It is important to note:
- 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
# 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 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
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.
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.
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.
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 |
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:
Option Network security: LAN Manager authentication Level and select: Send LM & NTLM: Use NTLMv2 session security if negotiated.
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.
If "Connect using different credentials" was checked, a new window to enter the corresponding credentials will appear.
You can also do this by launching the following command from the command line:
net use <drive letter> \\<servername>\<sharename> /user:<username> <password> and, as an example: net use Z: \\server_name\repository /user:okmAdmin admin_password