1.0 Overview
Configure the API client library to communicate with the Fortanix-Data-Security-Manager (DSM) server and configure the client to authenticate with the server. The Fortanix DSM Developer’s Guide contains more information on the types of authentication that can be performed.
import com.fortanix.sdkms.v1.ApiClient;
APiClient client = new ApiClient();
2.0 Configure Fortanix Data Security Manager Server (Optional)
You will need to perform this step if you are using an on-premises Fortanix DSM server. If you are using the cloud Fortanix DSM 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.smartkey.io");
3.0 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 Fortanix Authentication Guide contains more information on authentication.
You should use only one of the following authentication methods.
3.1 Configure User Authentication
Every authentication creates a session that grants a bearer token which can be passed for any other API requests. Please note that the bearer token expires if the session remains inactive for a long period of time. Please check with Fortanix DSM admin for the expiration values. By default, user sessions expire after 24 hours and app sessions expire after 10 min if remained idle.
The sample code below authenticates using provided credentials and then saves the bearer token in the API Client for subsequent use by other API requests.
User authentication is configured with the ApiClient.setUsername() and ApiClient.setPassword() methods:
client.setUsername("[email protected]");
client.setPassword(...);
3.2 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 Fortanix DSM UI by examining the app’s properties.
client.setBasicAuthString(<API key copied from UI>);
3.3 Configure App Authentication with an App Certificate
App authentication with a 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>);
4.0 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);
5.0 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 Fortanix DSM 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");
6.0 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 Fortanix DSM server.
authApi.terminate();
7.0 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.
8.0 Enabling Client Library Debugging
More verbose debugging for the client library can be enabled using the ApiClient.setDebugging() method.
config.setDebugging(true);
9.0 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");
10.0 Configuring a TLS Trust Store
If you are using an on-premises Fortanix DSM 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 using 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 Fortanix DSM instance at https://smartkey.io/.