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 running on a Linux VM. We will use Docker Compose to define and run the containers. You can also use another container runtime if so desired.

info

Make sure to choose a Docker host that is reachable from Azure Managed HSM and that can reach the Securosys HSM. If needed, configure firewall rules and domain settings in Azure accordingly.

Download

Download the ZIP file with the release artifacts.

Define the Docker Compose

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

Example configuration:

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
    restart: unless-stopped

On the public side, the EKM Proxy must be exposed using port 443. This port is mapped to a port inside the container, in this case, 8080.

Define the Application Config

Edit the application.yml file, which defines the configuration options the proxy will use. For example, it tells the proxy where it can reach the HSM, how to authenticate against the HSM, and which TLS keys and 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.

Obtain a TLS Server Certificate

Azure requires that the EKM Proxy is served via TLS 1.3. Therefore, you need to generate a server private key and obtain a server certificate for it from a CA. This can be a public or private CA. The subject alternative name (SAN) of the certificate should match the FQDN of the proxy host.

Put the server key PEM in the keystore.private-key field and the server certificate in the keystore.certificate field. Note down the certificate of the root CA that issued the server certificate, as you will need this later.

Leave the truststore.certificate and ekm.allowedClientCns fields empty for now, you will configure them later.

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

docker login securosys.jfrog.io

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: SecurosysPrimusXSeries version 2.57020251112

Get started withCloudHSM for free.

Need help?Contact Support.

Other questions?Ask Sales.

Download​

Define the Docker Compose​

Define the Application Config​

Obtain a TLS Server Certificate​

Logging​

Deploy the Proxy​