Configure API Client and Client Authentication

Updated: August 7, 2017

The first step is to configure the API client library to communicate with the SmartKey server and configure the client to authenticate with the server. The SmartKey Developer’s Guide contains more information on types of authentication that can be performed.

import com.fortanix.sdkms.v1.ApiClient;

APIClient client = new ApiClient();

Configure SmartKey server (Optional)

You will need to perform this step if you are using an on-premises SmartKey server. If you are using the cloud SmartKey service, you may skip this step. You may set the server that the client will talk to with the ApiClient.setBasePath() method.

ApiClient client = new ApiClient();
client.setBasePath("https://apps.sdkms.example.com");

Configure Authentication

The method used to configure authentication varies depending on what type of authentication you wish to perform. User authentication and app authentication allow different APIs to be accessed. The SmartKey Developer’s Guide contains more information on authentication.

You should use only one of the following authentication methods.

Configure User Authentication

User authentication is configured with the ApiClient.setUsername() and ApiClient.setPassword() methods:

client.setUsername("user@example.com");
client.setPassword(...);

Configure App Authentication with an API Key

App authentication with an API key is configured with the ApiClient.setBasicAuthString() method. The API key for an application can be found in the SmartKey UI by examining the app’s properties.

client.setBasicAuthString(<API key copied from UI>);

Configure App Authentication with an App Certificate

App authentication with an client certificate requires some additional configuration. First, you will need to configure the client’s username with the application’s UUID with ApiClient.setUsername(). The application’s UUID can be found on the application’s details page in the UI. You must also configure the Java network libraries to use the correct certificate and private key when connecting to the server. The client certificate and client private key must be supplied in a PKCS#12 archive.

// Configure the app that this program will log in as.
client.setUsername(<App UUID copied from the UI>)

// Configure java to provide a client certificate during the TLS handshake.
System.setProperty("javax.net.ssl.keyStoreType", "pkcs12");
System.setProperty("javax.net.ssl.keyStore", <path to the PKCS#12 archive>);
System.steProperty("javax.net.ssl.keyStorePassword, <password of the PKCS#12 archive>);

Set the Default Client Configuration

If you will be reusing the same API client configuration for multiple API calls, you will want to set this configuration as the default API client configuration. The default configuration will be as a default for all API client objects that don’t have another configuration explicitly assigned to them.

import com.fortanix.sdkms.v1.Configuration;

Configuration.setDefaultApiClient(client);

Log In and Configure Bearer Token

Once you have configured one of the above authentication methods and set the default client configuration, you will need to log in to the SmartKey server using those credentials and retrieve a bearer token. The bearer token will be used for authorizing all other types of API calls. Logging in is achived by creating an AuthenticationApi object and calling its authorize() method. When authorization has been granted, you must configure the API client to use the returned bearer token for API calls.

import com.fortanix.sdkms.v1.api.AuthenticationApi;
import com.fortanix.sdkms.v1.auth.ApiKeyAuth;
import com.fortanix.sdkms.v1.model.AuthResponse;

AuthenticationApi authApi = new AuthenticationApi();
AuthResponse response = authApi.authorize();

// client here should be the same client you set as the default above.
ApiKeyAuth auth = (ApiKeyAuth) client.getAuthentication("bearerToken");
auth.setApiKey(response.getAccessToken());
auth.setApiKeyPrefix("Bearer");

End Your Session

Bearer tokens are valid a limited period of time. User bearer tokens will expire after 24 hours of inactivity, and application bearer tokens will expire after 10 minutes of inactivity. An application may terminate its session to immediately invalidate its bearer token. It is a good idea to do this before an application exits to limit the possibility of a stolen bearer token being used to access the SmartKey server.

authApi.terminate();

Protecting Authentication Secrets

The user’s password, API key, or client certificate private key will grant access to all of the keys and methods that the user or application has access to. You should protect these like other sensitive information and not store these in the clear in scripts.

Enabling Client Library Debugging

More verbose debugging for the client library can be enabled via the ApiClient.setDebugging() method.

config.setDebugging(true);

Enabling TLS Debugging

SSL session debugging can be enabled in the Java configuration. This can be helpful in debugging why client certificate based authorization is not working.

System.setProperty("javax.net.debug", "all");

Configuring an TLS Trust Store

If you are using an on-premises SmartKey server deployment, you may need to configure your client to use your own SSL certificate as the root of trust for the SSL connection. You may do this via the javax.net.ssl.trustStore property.

System.setProperty(javax.net.ssl.trustStore, <your trustore path>);

The truststore should be a Java truststore file.

You should not need to do this if you are using the cloud SmartKey instance at https://www.smartkey.io.