How to connect to Splunk Enterprise using the Splunk SDK for Java

You can use the IDE of your choice when you develop Java applications for Splunk Enterprise, such as Eclipse or IntelliJ. To use the Splunk SDK for Java, add splunk.jar to your project as you would any dependency. The splunk.jar file is located in the /splunk-sdk-java/dist folder. If it's not there, you probably haven't built the SDK yet—see Installation for more information.

To start a Splunk Enterprise session, the first thing your program must do is connect to Splunk Enterprise by sending login credentials to the splunkd server. Splunk Enterprise returns an authentication token, which is then automatically included in subsequent calls for the rest of your session. By default, the token is valid for one hour, but is refreshed every time you make a call to splunkd.

The basic steps are as follows:

  1. Import the Service class from com.splunk. The Service class is the primary entry point to the Splunk Enterprise client library and provides access to most of your Splunk Enterprise instance's resources.

  2. Create an instance of the Service class and provide your login credentials, by doing one of the following:

    • Create a map of arguments containing login parameters, then use the connect method to both create the Service object and log in. Use the ServiceArgs helper class to create the argument map.
    • Create a new Service object with parameters (such as the host and port), then use the login method to log in with a username and password.

Here's the example code to start a Splunk Enterprise session using the Service.connect method (examples showing how to use the Service.login method are also shown here but commented out). The credentials for logging in to the splunkd server are hard-coded, so replace them with your own. This example also prints the locally-installed Splunk Enterprise apps to the console to verify you connected successfully.

Before you run this, start the Splunk Enterprise server if you haven't already.

import com.splunk.*;       // The entry point to the client library

public class SplunkTest {

    public static void main(String[] args) {

        // Create a map of arguments and add login parameters
        ServiceArgs loginArgs = new ServiceArgs();
        loginArgs.setUsername("admin");
        loginArgs.setPassword("changeme");
        loginArgs.setHost("localhost");
        loginArgs.setPort(8089);
        
        // Create a Service instance and log in with the argument map
        Service service = Service.connect(loginArgs);


        // A second way to create a new Service object and log in
        // Service service = new Service("localhost", 8089);
        // service.login("admin", "changeme");

        // A third way to create a new Service object and log in
        // Service service = new Service(loginArgs);
        // service.login();

        // Print installed apps to the console to verify login
        for (Application app : service.getApplications().values()) {
            System.out.println(app.getName());
        }
    }
}

The previous example shows how the Splunk Enterprise server generates the token and passes it to the client to be used in subsequent calls. But, you can also log in with an existing session token. For example, if you want to use the same session token on multiple clients that are accessing a single Splunk Enterprise instance, you can log in on one client, get the session token using the Service.getToken method, and then pass that token to other clients to use when they log in (use the Service.setToken method).

You can also connect to Splunk Enterprise by using basic access authentication, for example if you have multiple Splunk Enterprise instances behind a load balancer and want to use the same session token for all. To create a token using a basic authorization header, Base64-encode a string with your credentials in the format "username:password" and prepend the authorization method ("Basic"). This example shows how:

import com.splunk.*;       // The entry point to the client library
import com.sun.org.apache.xerces.internal.impl.dv.util.Base64;

public class SplunkTest {

    public static void main(String[] args) {

        // Log in using a basic authorization header
        // Note: Do not call the Service.login method
        Service service = new Service("localhost", 8089);
        String credentials = "admin:changeme";
        String basicAuthHeader = Base64.encode(credentials.getBytes());
        service.setToken("Basic " + basicAuthHeader);
		
        // Print the session token
        System.out.println("Your session token: " + service.getToken());

        // Print installed apps to the console to verify login
        for (Application app : service.getApplications().values()) {
            System.out.println(app.getName());
        }
    }
}