Integrating with Maverick Synergy
This guide shows you how to connect your Java SSH client to SSH Teams in a simple way.
You will do four things:
- Add the Maven dependencies.
- Add a secure device store.
- Register your device once.
- Connect with a short-lived certificate that is created for that session.
Before You Start
Make sure you already have:
- A running SSH Teams server URL.
- A user account in SSH Teams.
- Java and Maven installed.
Step 1: Add Maven Dependencies
Add these dependencies to your pom.xml.
<dependencies>
<dependency>
<groupId>com.sshtools</groupId>
<artifactId>sshteam-lib</artifactId>
<version>0.0.2-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>com.sshtools</groupId>
<artifactId>jadaptive-hsm</artifactId>
<version>0.0.1</version>
</dependency>
<dependency>
<groupId>com.sshtools</groupId>
<artifactId>maverick-synergy-client</artifactId>
<version>3.2.0-SNAPSHOT</version>
</dependency>
</dependencies>
Step 2: Add a Device Store (Required)
The device store is where your app keeps local registration data.
Your device store must:
- Save data per SSH Teams server URL.
- Keep private key data encrypted at rest.
- Return the same values later so refresh and sign-in continue to work.
Here is a full example using jadaptive-hsm:
package com.sshtools.sshteam.examples;
import java.nio.file.Path;
import java.util.Objects;
import com.jadaptive.hsm.encrypt.HsmEncryptionProvider;
import com.jadaptive.hsm.encrypt.SoftwareEncryptionProvider;
import com.sshteam.lib.AbstractFileDeviceStore;
import com.sshteam.lib.DeviceStoreEncryption;
/**
* Example DeviceStore using jadaptive-hsm for encryption at rest.
*/
public final class HsmBackedDeviceStore extends AbstractFileDeviceStore {
HsmBackedDeviceStore(Path baseDir, HsmEncryptionProvider provider) {
super(baseDir, new HsmDeviceStoreEncryption(provider));
}
public static HsmBackedDeviceStore defaultStore() throws Exception {
Path storeDir = Path.of(defaultString(
System.getenv("SSHTEAM_EXAMPLES_STORE_DIR"),
Path.of(System.getProperty("user.home"), ".sshteam-examples").toString()));
String keystoreFile = defaultString(System.getenv("SSHTEAM_EXAMPLES_HSM_FILE"), "sshteam-examples-hsm.p12");
String keystoreAlias = defaultString(System.getenv("SSHTEAM_EXAMPLES_HSM_ALIAS"), "sshteam-examples");
String keystorePassword = defaultString(System.getenv("SSHTEAM_EXAMPLES_HSM_PASSWORD"), "changeit-changeit");
HsmEncryptionProvider provider = SoftwareEncryptionProvider.builder()
.setEnabled(true)
.setKeystoreDir(storeDir.toString())
.setKeystoreSubdir("")
.setKeystoreFilename(keystoreFile)
.setKeystoreAlias(keystoreAlias)
.setKeystorePassword(keystorePassword)
.build();
provider.init();
return new HsmBackedDeviceStore(storeDir, provider);
}
private static String defaultString(String value, String fallback) {
return value == null || value.isBlank() ? fallback : value;
}
private static final class HsmDeviceStoreEncryption implements DeviceStoreEncryption {
private final HsmEncryptionProvider provider;
private HsmDeviceStoreEncryption(HsmEncryptionProvider provider) {
this.provider = Objects.requireNonNull(provider, "provider cannot be null");
}
@Override
public String encrypt(String serverUrl, String plainText) throws Exception {
String scoped = serverUrl + "\n" + plainText;
return provider.encrypt(scoped);
}
@Override
public String decrypt(String serverUrl, String cipherText) throws Exception {
String scoped = provider.decrypt(cipherText);
String prefix = serverUrl + "\n";
if (!scoped.startsWith(prefix)) {
throw new IllegalStateException("Encrypted value scope does not match server URL");
}
return scoped.substring(prefix.length());
}
}
}
Step 3: Register the Device Once
Run this once on the machine that will request certificates.
import java.net.InetAddress;
import com.sshteam.lib.SshteamClient;
public final class RegisterDeviceWithHsmExample {
public static void main(String[] args) throws Exception {
String serverUrl = args[0];
boolean waitForAuthorization = args.length > 1 ? Boolean.parseBoolean(args[1]) : true;
boolean ignoreSslTrust = args.length > 2 && Boolean.parseBoolean(args[2]);
String clientId = "sshteam-lib-examples";
String deviceName = "sshteam-lib-examples-" + InetAddress.getLocalHost().getHostName();
HsmBackedDeviceStore store = HsmBackedDeviceStore.defaultStore();
SshteamClient client = new SshteamClient(store, serverUrl, ignoreSslTrust);
SshteamClient.RegistrationResult result = client.register(
clientId,
deviceName,
5,
600,
waitForAuthorization,
true);
System.out.println("Registration status: " + result.status());
System.out.println("Server: " + result.server());
System.out.println("Message: " + result.message());
}
}
If this returns a pending status, open the verification URL and approve the device.
Step 4: Connect with an Ephemeral Certificate
Now you can ask SshteamClient to create a short-lived certificate identity for this SSH host.
You only need one call:
SshKeyPair certIdentity = client.generateEphemeralCertificate(
sshHost,
sshPort,
sshUsername,
SshKeyPairGenerator.ED25519);
Then use that identity with Maverick Synergy:
import java.time.Duration;
import java.util.Arrays;
import com.sshteam.lib.SshteamClient;
import com.sshtools.client.SshClient;
import com.sshtools.client.SshClient.SshClientBuilder;
import com.sshtools.common.publickey.SshKeyPairGenerator;
import com.sshtools.common.ssh.components.SshKeyPair;
public final class MaverickSynergyCertificateAuthExample {
public static void main(String[] args) throws Exception {
String sshTeamServer = args[0];
String sshHost = args[1];
int sshPort = Integer.parseInt(args[2]);
String sshUsername = args[3];
boolean ignoreSslTrust = args.length > 4 && Boolean.parseBoolean(args[4]);
SshteamClient client = new SshteamClient(
HsmBackedDeviceStore.defaultStore(),
sshTeamServer,
ignoreSslTrust);
SshKeyPair certIdentity = client.generateEphemeralCertificate(
sshHost,
sshPort,
sshUsername,
SshKeyPairGenerator.ED25519);
try (SshClient ssh = SshClientBuilder.create()
.withTarget(sshHost, sshPort)
.withUsername(sshUsername)
.withIdentities(certIdentity)
.withConnectTimeout(Duration.ofSeconds(30))
.build()) {
System.out.println("Connected host: " + ssh.getHost() + ":" + ssh.getPort());
System.out.println("Authenticated: " + ssh.isAuthenticated());
System.out.println("Remote public keys: " + Arrays.toString(ssh.getRemotePublicKeys()));
}
}
}
Quick Checklist
If connection fails, check these first:
- Your device was registered and approved.
- Your SSH Teams user has permission for this server.
- The SSH host and port are correct.
- Your local clock is correct.
You’re Ready
Once this is set up, your app can create fresh SSH identities when needed.
That means you do not need to keep a long-lived private key on every machine.