Skip to content

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:

  1. Add the Maven dependencies.
  2. Add a secure device store.
  3. Register your device once.
  4. 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.