...
...
...
TODO: replace this page entirely with a new content explaining the new dev-/test tooling for WAR and Docker deployments, see also https://confluence.nexusgroup.com/pages/viewpage.action?pageId=211419460
Info |
---|
This article is valid new for Smart ID Identity Manager 245.R1. |
Tomcat deployments
xy
Docker deployments
xy
OBSOLETE CONTENT BELOW!
In a production environment, the certificates used must be created by a real certificate authority (CA). By doing so, the trust is clear.
If it is not possible to use a CA, it is not recommended to use certificates with well-known private keys.
This article gives examples of scripts that makes it easy to set up the certificates needed with a new set of private keys. Those private keys are intended for a single machine or Identity Manager installation.
The procedure consists of these steps:
...
Set up a local CA
The CA can be used for several installations on the same machine.
...
Establish trust for the CA
The CA certificate is installed in the cacerts truststore of the active Java installations. This step has to be repeated after every Java upgrade. Thus having a single CA keeps maintenance low. In order to access a Java installation on Windows, the script needs to run in Windows command line, not in WSL2.
...
In this example we only create four P12 files: one for encryption and one for signing, one for email-signing and one for the device-enc CA . It is recommended to use multiple different ones for various signing- and encryption-related use-cases, but the default config in supplied Tomcat packages uses a common signing P12 as well as an encryption P12 for both config zip and database secrets.
Double-check PINs
You need to make sure that WEB-INF\classes\engineSignEncryptConfig.xml has the correct PINs that were used during bootstrapping.
Requirements
These scripts use OpenSSL 1.x. This can be installed on Windows and added to the PATH environment variable, or you can use a WSL2 Linux distribution with OpenSSL 1.x instead (e.g. Ubuntu 20.04).
The latest 1.x version of OpenSSL is recommended. Version 3 by default uses incompatible PKCS#12 algorithms.
If you insist on using version 3, then you need to change any "openssl pkcs12" calls in the .bat and .sh files from certsetup.zip to include the following extra parameter(s):
Mandatory parameter to enable the legacy provider:
-legacy
Also potentially needed, in case the legacy provider library is in the wrong path (as is the case with some OpenSSL builds for Windows) is this (make sure you locate the correct path first, instead of the examples below):
-provider-path "C:\folder\containing\legacy.dll"
or
-provider-path "/folder/containing/legacy.so"
Active Java installation is selected via JAVA_HOME environment variable.
Steps with installed OpenSSL for Windows
This was successfully tested with https://slproweb.com/download/Win64OpenSSL_Light-1_1_1m.msi .
Ensure that JAVA_HOME points to the folder of the Windows Java installation that will be used by Tomcat.
Download certsetup.zip.
Unpack it. (For example to C:\primestuff\certsetup)
Start a command line as administrator to execute the following:
Navigate to the batch files (
cd c:\primestuff\certsetup
)createca.bat
trustlocalCA.bat
createP12s.bat
Copy sign.p12, signConfig.p12, signJWS.p12, signJWT.p12, encryptConfig.p12, emailSigning.p12, deviceEncCA.p12 and hybridEncKeypair.p12 to WEB-INF\classes of your web applications.
Edit WEB-INF\classes\engineSignEncryptConfig.xml in your web applications and make sure it uses the pins that were set during bootstrapping for the respective files.
Steps using WSL2
...
Ensure that JAVA_HOME points to the folder of the Windows Java installation that will be used by Tomcat.
...
Download certsetup.zip.
...
Open WSL distribution using OpenSSL 1.x (e.g. Ubuntu 20.04)to execute the following:
Navigate to the batch files (
cd /mnt/c/primestuff/certsetup
→ depends on distribution, example is Ubuntu)./createca.sh
./createP12s.sh
...
Start a command line as administrator (Establishing the trust has to be done to the Java of Windows)
Navigate to the batch files (
cd c:\primestuff\certsetup
)trustlocalCA.bat
...
Copy sign.p12, signConfig.p12, signJWS.p12, signJWT.p12, encryptConfig.p12, emailSigning.p12, deviceEncCA.p12 and hybridEncKeypair.p12 to WEB-INF\classes of your web applications.
...
0.1. |
For development and test environments, test keys and certificates for all default descriptors can be generated using features of the IDM bootstrap.zip package and bootstrap docker container.
The bootstrap CA certificate generated by the procedure below will have a validity of 20 years, and each end-entity certificate will be valid for one year.
The generated PINs for every P12 file are automatically scrambled.
No keys and certificates will be generated for descriptions which absent from signencrypt.xml.
For Tomcat development or test deployment
Requirements
Tomcat not started
Tomcat folder containing unpacked IDM Operator and IDM Admin of IDM 5.0.0, or later versions, on Linux or Windows
unpacked bootstrapping.zipfor the respective IDM release
Instructions
Open a command-line window.
Change to the unpacked bootstrap folder containing create_sign_encrypt_certs.sh (linux) or create_sign_encrypt_certs.bat (windows).
Execute the respective script for your OS.
Linux:
./create_sign_encrypt_certs.sh --targetDir /PATH/TO/TOMCAT/webapps/idm-operator/WEB-INF/classes [OPTIONAL ARGS]
Windows:
create_sign_encrypt_certs.bat --targetDir C:\PATH\TO\TOMCAT\webapps\idm-operator\WEB-INF\classes [OPTIONAL ARGS]
Execute the script without any parameters to see all supported arguments (if you need the plain text passwords of the generated P12 files, then adding the passwordList argument is recommended):Code Block create_sign_encrypt_certs.bat / create_sign_encrypt_certs.sh --caDir <dir> CA cert directory - absolute or relative to bootstrapping directory (default: cacerts) --configFile <file> config to modify - absolute or relative to target directory (default: engineSignEncryptConfig.xml) --passwordList <file> optionally create file which lists unscrambled passwords - absolute or relative to target directory (will overwrite existing) --targetDir <dir> target directory for certificates - absolute or relative to current directory
Copy all P12files and engineSignEncryptConfig.xml from idm-operator/WEB-INF/classes to idm-admin/WEB-INF/classes optionally you can prune the files and XML entries which IDM Admin does not need.
For docker development or test deployment
Requirements
An unpacked SmartID package for the respective IDM release on a Linux/WSL docker host
No container started
Instructions
Open the smartid/docker/composefolder.
Prepare the files
init-smartid.env
andsmartid.env
according to the deployment documentation.
If you need the plain text passwords of the generated P12 files, then edit smartid/docker/compose/identitymanager/bootstrap/docker-compose.yml
and replacecommand: ["-configFile", "/usr/local/tools/config/signencrypt.xml", "-targetDir", "/usr/local/tools/certs"]
within the
create_sign_encrypt_certs
section withcommand: ["-configFile", "/usr/local/tools/config/signencrypt.xml", "-targetDir", "/usr/local/tools/certs", "-passwordList", "pwlist.txt"]
.
This will ensure the file smartid/docker/compose/certs/pwlist.txt will be created.
Execute the init script:
./init-smartid.sh
, which will guide you through the process, including bootstrapping.
Additional information
Expand | ||
---|---|---|
| ||
|