Install the EKM Proxy

In this step, you will install, configure, and deploy the Securosys External Key Management Proxy for Azure Key Vault.

In this guide, we will use Docker Compose to define and run the containers. You can also use another container runtime if so desired.

Download

Download the .zip file with the release artifacts.

Define the Docker Compose

Edit the file docker-compose.yml to define the proxy container that will be launched. A template for this file is included in the release artifacts.

services:
  azure_ekm_proxy:
    image: securosys.jfrog.io/azure-ekm/securosys-azure-ekm-proxy:latest
    container_name: azure_ekm_proxy
    ports:
      - "443:8080"
    volumes:
      # place for application configuration files
      - ./config-files:/etc/app/config
      # output folder of e.g. logfiles
      - ./output:/etc/app/logs
    environment:
      - logging.config=/etc/app/config/log/logback.xml
    restart: unless-stopped

Expose the EKM Proxy on port 443. If no domain controller is configured in your environment, define services.azure_ekm_proxy.ports:443:8080.

Define the Application Config

Edit the application.yml file, which defines the configuration options the proxy will use. It tells the proxy which database it should use, where it can reach the HSM, and how it should authenticate against APIs of the HSM and which Azure CN and TLS Certificate to use. A template for this file is included in the release artifacts.

Example configuration:

# Full template of the Securosys Azure EKM Proxy API configuration.

## HTTPS (TLS) CONFIGURATION
server:
  port: 8080 # the port the API shall listen on
  ssl:
    enabled: true # Required - DO NOT CHANGE - Enables SSL/TLS for the embedded server
    bundle: bundle_name # References the SSL bundle defined under spring.ssl.bundle.bundle_name
    enabled-protocols: TLSv1.3 # Required - DO NOT CHANGE - TLS protocol version
    ciphers:  # Required - DO NOT CHANGE - available ciphers
      - TLS_AES_256_GCM_SHA384
      - TLS_AES_128_GCM_SHA256
    client-auth: need # Required - DO NOT CHANGE - mTLS client-auth policy: need = required, want = optional, none = disabled
  servlet:
    context-path: /optional_prefix # An optional path prefix set during Azure EKM connection setup 

spring.ssl.bundle.pem.bundle_name: # Define a named SSL bundle using PEM-based configuration, only change "bundle_name"
  reload-on-update: false # Whether to automatically reload certificates when they change
  keystore:    # Path to server certificate (PEM) or whole pem file content
    certificate: | # Path to server private key (PEM) or whole pem file content
      -----BEGIN CERTIFICATE-----
      MIID+TCCAuGgAwIBAgIUGtUDkB7srguucEid2FApM1xUIkEwDQYJKoZIhvcNAQEL
      QUtPVzEQMA4GA1UECg..................................vjEvp6XzTw==
      -----END CERTIFICATE-----
    private-key: |
      -----BEGIN PRIVATE KEY-----
      MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC89g2RH2nLtBAt
      Mu3cepO4M............................................Pv3Rl9+IQ==
      -----END PRIVATE KEY-----
  truststore: # Path to CA certificate(s) trusted for client authentication (PEM) (from Managed HSM)
    certificate: |
      -----BEGIN CERTIFICATE-----
      MIID+TCCAuGgAwIBAgIUGtUDkB7srguucEid2FApM1xUIkEwDQYJKoZIhvcNAQEL
      QUtPVzEQMA4GA1UECg..................................vjEvp6XzTw==
      -----END CERTIFICATE-----

## Logging configuration
logging:
  config: /etc/app/config/log/logback.xml

## HSM configuration
  # Provide all necessary credentials for the HSM connection
  # Make sure you allowed an outbound firewall rule, to allow traffic to the HSM
hsm:
  # At first log in, the host and port are randomly selected. In case of an error, successive host and port combinations are selected.
    host: # Defines host - either via URL or IP
    - 'ch01-api.cloudshsm.com'
    - 'ch02-api.cloudshsm.com'
   #- '10.10.10.10'
   # Add more by listing sequentially                                                  
  port: # Define which API Ports to connect to
    - '2300'            
   #- '2400'
   # Add more by listing sequentially 
  user: 'replace-me_hsm-username' # Define HSM username
  setupPassword: 'replace-me_hsm-setupPassword' # This password will only be used once on an OTP basis
  proxyUser: 'replace-me_proxy-username' # Define CloudHSM proxy username credential, remove if not used
  proxyPassword: 'replace-me_proxy-password' # Define CloudHSM proxy password credential, remove if not used
  attestationKeyName: 'attestation-key' # Define label of attestation key

## Azure EKM CN configuration
ekm:
  # List of allowed Client CN
  allowedClientCns:
    - "CN=test-client-ekm" # Defines the allowed client CNs
   #- "CN=additional-CN"
   # Additional allowed CN, more can be added sequentially
   
## SWAGGER-UI Configuration (best practice is to disable swagger on production)
swaggerUI.enabled: false

HSM Configuration Parameter	Description
host	Specify the DNS or IP of the HSM or CloudHSM. See Connectivity Details for more information. Multiple hosts can be specified sequentially in their own lines to allow for multiple connections (HA cluster environments).
port	Specify the JCE port of the HSM or CloudHSM. See Connectivity Details for more information.
user	Specify the Partition where the keys are and will be stored.
setupPassword	Specify the setup password to establish the initial connection between the proxy and the HSM. When successful a permanent secret will be fetched, and the setup password will expire in the set amount of time.
proxyUser	Specify your proxy username, applicable to CloudHSM.
proxyPassword	Specify your proxy password, applicable to CloudHSM.
allowedClientCns	Specify the allowed Azure Managed HSM TLS certificate CN, more can be added sequentially as shown within the example.

Logging

The EKM Proxy collects logs to assist with troubleshooting. These logs can additionally be configured to log remotely to a syslog server, Splunk App, or to a TCP socket.

Edit the logback.xml file with your parameters if remote logging is desired.

Deploy the Proxy

Finally, start the container:

docker compose up --detach

The Proxy will fetch the permanent secret and establish a connection with your HSM. Example log output:

azure_ekm_proxy  | 2026.06.26 11:12:25.456 INFO  [           main] [km.business.service.HsmService] Successfully login to primus hsm
azure_ekm_proxy  | 2026.06.26 11:12:25.456 INFO  [           main] [km.business.service.HsmService] Primus HSM JCE provider information: SecurosysPrim          usXSeries version 2.57020251112

Next Steps

• Ensure your host has an existing domain and is reachable on the host name to allow Azure Managed HSM to connect to the EKM Proxy.
• Continue the integration by following the Tutorials - Integrate with Azure Key Vault guide.