Kerberos Authentication

Kerberos is a secure authentication protocol that uses secret-key cryptography and a trusted third-party service to verify user identities. It’s widely used for single sign-on (SSO) and provides both authentication and authorization with minimal user interaction.

To configure Kerberos Authentication for Directory Watcher event sources, complete the setup steps outlined below.

Prerequisites

Before you configure Kerberos Authentication for Directory Watcher event sources, ensure the following prerequisites are met.

Active Directory (AD) domain membership
- The domain or realm name of your AD environment must be known.
- Both the client machine and the file server must be joined to the same AD domain.
  - Join a Windows server to an AD domain
  - Join a Linux server to an AD domain
Rapid7 Collector
- The Rapid7 Collector must be installed on a Windows or Linux machine.
Administrative access
- Administrator privileges are required on all machines involved in the configuration.
SMB user account
- Create a user in AD to act as the SMB user. You can choose any username, but you will need both the username and password to generate the Kerberos keytab file.
Kerberos keytab file
- A keytab file is required for Kerberos authentication. You can create this file using the ktpass utility on the AD machine.

Create a Kerberos keytab file

Open a Command Prompt as an administrator.
Run the following ktpass command to generate a keytab file, replacing the placeholders as specified below:


ktpass /out C:\smb.keytab /princ WILDCARDS/smbuser@wildcards.tor.rapid7.com /mapuser smbuser@wildcards.tor.rapid7.com /pass password /ptype krb5_nt_principal

Replace the placeholders as follows:
- WILDCARDS: Your AD domain name
- smbuser: The SMB user you created
- wildcards.tor.rapid7.com: Your fully qualified domain name (FQDN)
- password: The password for the SMB user
This command includes a specified Kerberos principal using the /princ flag.
Note: This guide assumes the use of keytabs for Kerberos authentication. It is possible to authenticate without a keytab, but those steps are not covered here.
Learn more about the ktpass command

Configure Kerberos Authentication

To enable Kerberos authentication for Directory Watcher event sources, complete the following steps on your client and file server machines.

Configure Kerberos Authentication on Windows

Ensure both the client machine (which runs the Rapid7 Collector) and the file server are joined to the Active Directory (AD) domain that you intend to authenticate against.
Move the keytab file you created as a prerequisite to a known folder location on the client machine’s local disk (C:).
In the C:\Windows folder of the client machine, create a new file named krb5.ini.
Populate the krb5.ini file with your Kerberos configuration. Use the following template, updating the values to match your environment:


[libdefaults]
    default_realm = WILDCARDS.TOR.RAPID7.COM
    ticket_Lifetime = 1440m
    renew_lifetime = 1h
    forwardable = true
[realms]
WILDCARDS.TOR.RAPID7.COM = {
    kdc = 11.1.11.111
    admin_server = 11.1.11.111
}
[domain_realm]
    .wildcards.tor.rapid7.com = WILDCARDS.TOR.RAPID7.COM
    wildcards.tor.rapid7.com = WILDCARDS.TOR.RAPID7.COM

For more information about configuring the krb5.ini file, see IBM’s Kerberos configuration file documentation .

In the same folder, create a new file named login.conf.
Add the following configuration to login.conf, replacing the placeholders as specified below:


KrbLogin {
    com.sun.security.auth.module.Krb5LoginModule required
    useKeyTab=true
    storeKey=true
    keyTab="File:///C:/kerberos/smb256.keytab"
    useTicketCashe=true
    principal="WILDCARDS/smbuser@WILDCARDS.TOR.RAPID7.COM"
    debug=true
    refreshKrb5Config=true;
};

com.sun.security.jgss.initiate {
    com.sun.security.auth.module.Krb5LoginModule required
useKeyTab=true
    storeKey=true
    keyTab="File:///C:/kerberos/smb256.keytab"
    useTicketCashe=true
    principal="WILDCARDS/smbuser@WILDCARDS.TOR.RAPID7.COM"
    debug=true
    refreshKrb5Config=true;
};

Replace the placeholders as follows:
- keyTab: Full path to the Kerberos keytab file on the client machine.
- principal: The AD user principal created with the ktpass command.
We recommend including both modules (com.sun.security.auth.module.Krb5LoginModule and com.sun.security.jgss.initiate) to ensure compatibility.
For details, see Oracle’s Login Configuration File documentation .

On the client machine (where the collector is installed), go to C:\Program Files\Rapid7\Collector\conf.
Open the config.properties file in a text editor.
Add the following parameter: org.osgi.framework.bootdelegation=sun.*,com.sun.*

Example configuration:


felix.auto.deploy.action=install,start
felix.log.level=1
org.osgi.framework.bootdelegation=sun.*,com.sun.*

# WEB PROXY PROPERTIES
# note: if any of the following properties are modified, the collector service must be restarted for the chagnes to take effect

# If Web Proxy is setup for HTTPS communications in your environment, please uncomment the following properties and add your configuration

# https.proxyHost=proxy.host.com
# https.proxyPort=443

# If your Web Proxy requires authentication, please provide the username and password
# If applicable provide the domain to which the username belongs

# https.proxyUser=username
# https.proxyPassword=password
# https.proxyUserDomain=domain

Restart the Rapid7 Collector service to apply all configuration changes.

Configure Kerberos Authentication on Linux

Ensure both the client machine (which runs the Rapid7 Collector) and the file server are joined to the Active Directory (AD) domain that you intend to authenticate against.
After creating the keytab file, use an scp command to copy the Keytab to the client machine. You can place the keytab in a named folder in the etc directory on the linux machine.
In the etc directory, create a new file named krb5.conf.
Populate the krb5.conf file with your Kerberos configuration. Use the following template, updating the values to match your environment:


[libdefaults]
    default_realm = WILDCARDS.TOR.RAPID7.COM
    ticket_Lifetime = 1440m
    renew_lifetime = 1h
    forwardable = true
    rdns = false
[realms]
WILDCARDS.TOR.RAPID7.COM = {
    kdc = 11.1.11.111
    admin_server = 11.1.11.111
}
[domain_realm]
    .wildcards.tor.rapid7.com = WILDCARDS.TOR.RAPID7.COM
    wildcards.tor.rapid7.com = WILDCARDS.TOR.RAPID7.COM

For more information about configuring the krb5.ini file, see IBM’s Kerberos configuration file documentation .

In the same etc folder, create a new file named login.conf.
Add the following configuration to login.conf, replacing the placeholders as specified below:


KrbLogin {
    com.sun.security.auth.module.Krb5LoginModule required
    useKeyTab=true
    storeKey=true
    keyTab="/etc/kerberos/smb256.keytab"
    useTicketCashe=true
    principal="WILDCARDS/smbuser@WILDCARDS.TOR.RAPID7.COM"
    debug=true
    refreshKrb5Config=true;
};

com.sun.security.jgss.initiate {
    com.sun.security.auth.module.Krb5LoginModule required
useKeyTab=true
    storeKey=true
    keyTab="/etc/kerberos/smb256.keytab"
    useTicketCashe=true
    principal="WILDCARDS/smbuser@WILDCARDS.TOR.RAPID7.COM"
    debug=true
    refreshKrb5Config=true;
};

Replace the placeholders as follows:
- keyTab: Full path to the Kerberos keytab file on the client machine.
- principal: The AD user principal created with the ktpass command.
We recommend including both modules (com.sun.security.auth.module.Krb5LoginModule and com.sun.security.jgss.initiate) to ensure compatibility.
For details, see Oracle’s Login Configuration File documentation .

On the client machine (where the collector is installed), go to etc/opt/rapid7/collector/conf/.
Open the config.properties file in a text editor.
Add the following parameter: org.osgi.framework.bootdelegation=sun.*,com.sun.*

Example configuration:


felix.auto.deploy.action=install,start
felix.log.level=1
org.osgi.framework.bootdelegation=sun.*,com.sun.*

# WEB PROXY PROPERTIES
# note: if any of the following properties are modified, the collector service must be restarted for the chagnes to take effect

# If Web Proxy is setup for HTTPS communications in your environment, please uncomment the following properties and add your configuration

# https.proxyHost=proxy.host.com
# https.proxyPort=443

# If your Web Proxy requires authentication, please provide the username and password
# If applicable provide the domain to which the username belongs

# https.proxyUser=username
# https.proxyPassword=password
# https.proxyUserDomain=domain

Additionally, you may need to alter the hosts file in the etc directory of your linux machine or client machine. Here you may need to add the IP address and machine name of the AD machine you are attempting to authenticate to. For example:


127.0.0.1 localhost
127.0.1.1 wildcards-collector-1.wildcards.tor.rapid7.com wildcards-collector-1
11.1.11.111 DOMAIN_MACHINE_NAME

Restart the Rapid7 Collector service to apply all configuration changes.

Configure an Event Source to Use Kerberos Authentication

After you finish configuring Kerberos, you can select Kerberos Authentication as the authentication type when adding a new event source.

From the Add Event Source page, select the appropriate Collector.
Under Collection Method, select Watch Directory.
Under Authentication Type, select Kerberos Authentication.
Create a new credential:
1. In the Credential dropdown, select Create new….
2. In the Name field, enter a name for the new credential.
3. In the Username field, enter the username for the target host.
4. In the Password field, enter the password for the target host.
In the UNC path field, enter the machine name for the fileServer that will contain your logs, along with the specific directory location on the fileserver.
In the Kerberos Realm field, enter the Kerberos realm (domain).
In the Scan interval field, specify the desired log scan frequency in seconds.
Optionally, you can alter the specific data collection rules in the File pattern and Filter fields.
You may need to specifically share the directory you wish to watch with the user created during the steps above. As your file server will be part of the AD domain, you can right-click on the specific directory in your local file explorer, click Share with > Specific people… and choose which users within the domain have access to this directory.

Your event source is now configured to use Kerberos Authentication.