This article describes how to set up Utimaco with Digital Access acting as IDP in case of SAML.

Utimaco HSM is already installed, configured and reachable from the host running the Digital Access containers.
Since Digital Access does not yet support generation of a key-pair in the HSM via Digital Access Admin UI, a key-pair must already be generated and imported to the HSM.

Step-by-step instructions

The instructions below need to be done in all Digital Access VMs running the administration and policy service.

Folder structure

In the Digital Access docker host, create a folder called “utimaco” with sub-folders as shown below:

$ tree -d utimaco utimaco/ ├── etc ├── lib └── log
Copy the required utimaco files: .so, .cfg, .pks files as shown below:

$ tree utimaco utimaco ├── etc │ ├── cs_pkcs11_R3.cfg │ └── P11.pks ├── lib │ └── libcs_pkcs11_R3.so └── log
Note : For older Utimaco Simulator versions, the .cfg, .so files could differ from R3.
Make sure the folder structure has the following owner and permissions:

sudo chown -R 1003:1003 utimaco

UID may be different depending on the container environment.

Set log path and level as shown below:
Set the path to .pks (Specifies the path to the external key storage if keysExternal is set to true) as shown below:

Note : Set this depending on your Utimaco version configuration
Set IP(s) of remote devices as shown below:

In the docker compose for admin service, mount the “utimaco” folder created in the first step in section "Create folder structure" above, and define the respective CS_PKCS11_R3_CFG environment variable. Utimaco reads this to locate its configuration file.
The same changes also need to be done in docker-compose files of all policy services.
If Utimaco logging required, adapt the above configuration to ensure that each Digital Access node logs to its own log file.
If Digital Access Admin and Digital Access policy is running on same host, make ENV CS_PKCS11_R3_CFG unique for each Digital Access container and specify a unique log location in Utimaco.cfg.

Select Manage System > Certificates > Add Server Certificate.
In the Add Server Certificate dialog, enable “Using Hardware Security Module”, and click Next to set HSM settings.
Export the certificate (or retrieve it externally), upload it in the Add Server Certificate dialog and save.
Now the Server Certificate can be used in SAML IDP to enable signing of SAML responses using the HSM.