MyOrg_CA certificate will be imported in PassPort from the ssl.jks or sso.jks where it has been exported in private chain format.MyOrg_CA certificate will be imported in PassPort from the ssl.jks or sso.jks where it has been exported in private chain format.

Question

How to generate and replace PassPort default certificates with custom ones ?

Answer

This KB clarifies the actions needed to replace the Axway default certificates with custom ones for SSL and SSO in PassPort.

Step 1. Backup files
Optional but recommended step
Make a backup of the default files:
../PassPort/conf/security/ssl.jks
../PassPort/conf/security/sso.jks
../PassPort/conf/security/truststore.jks
../PassPort/sso/webapps/ROOT/WEB-INF/web.xml,
../PassPort/conf/filereg.xml

Export/dump of PassPort database user schema.

before starting this procedure.

Step 2. Generate your custom certificates

For generating custom certificates you can use a graphic tool like XCA or OpenSSL.

This guide uses XCA. Please check the attached PDF file (create-certificates.pdf) that provides instructions for creating your custom certificates.

Please follow the instructions provided in the document or use your existing certificates if you already have such certificates.

At the end of this step you should have:

• MyOrg_ROOT.crt (public format), corresponding to the ROOT certificate
• MyOrg_CA.crt (public format), corresponding to the INTERMEDIATE certificate - this is optional
• MyOrg_USER_SSL.p12 (private format), corresponding to the SSL USER certificate
• MyOrg_USER_SSO.p12 (private format), corresponding to the SSO USER certificate

To follow this guide easily we are considering that the certificates were stored in ../PassPort/conf/security and that the password used was axway*

Step 3. Import the custom certificates in JKS files.
PassPort reads the certificates from Java KeyStore repositories so the certificates created at Step 2 need to be imported and made available in such JKS files. This can be accomplished using keytool command within Java, or a graphical tool like KeyStore Explorer .
We'll use keytool to import the certificates generated at Step 2 and create new JKS files to be used in PassPort.
The working directory is ../PassPort/conf/security

• Create the ssl_custom.jks based on MyOrg_USER_SSL.p12

keytool -v -importkeystore -srckeystore MyOrg_USER_SSL.p12 -srcstoretype PKCS12 -srcstorepass axway* -destkeystore ../PassPort/conf/security/ssl_custom.jks -deststoretype JKS -alias MyOrg_USER_SSL -storepass axway* -destalias passportsecured 

• Create the sso_custom.jks based on MyOrg_USER_SSO.p12

 keytool -v -importkeystore -srckeystore MyOrg_USER_SSO.p12 -srcstoretype PKCS12 -srcstorepass axway* -destkeystore ../PassPort/conf/security/sso_custom.jks -deststoretype JKS -alias MyOrg_USER_SSO -storepass axway* -destalias passportsso

• Create the truststore_custom.jks based on MyOrg_ROOT.crt

 keytool -v -import -alias passportca -file MyOrg_ROOT.crt -storetype JKS -storepass axway* -keystore ../PassPort/conf/security/truststore_custom.jks

Type yes when prompted to Trust this certificate.

Note:MyOrg_CA certificate will be imported in PassPort from the ssl.jks or sso.jks, where it has been imported in private chain format.
If MyORG_CA hasn't been imported import it within the "Intermediate CA Certificates", default password "intermediate" and ensure that is activated.

Note: to display content of a JKS file use:

keytool -list -v -keystore ssl_custom.jks -storepass axway*

It's important to not copy the truststore.jks into truststore_custom.jks

Step 4. Copy the SSO and Truststore JKS files in the Webapps root folder

Copy the following files in the ../PassPort/sso/webapps/ROOT/ folder:

cp sso_custom.jks ../PassPort/sso/webapps/ROOT/sso_custom.jks
cp truststore_custom.jks ../PassPort/sso/webapps/ROOT/truststore_custom.jks

Step 5. Configure PassPort to use your own, custom JKS files

In this guide we have used custom name for the JKS files (sso_custom.jks, ssl_custom.jks, truststore_custom.jks) , so they wouldn't be overwritten when applying future SPs.

Next we will need to adjust the PassPort configuration files and point towards your custom JKS

• Adjust the web.xml to use the new sso_custom.jks

Edit ../PassPort/sso/webapps/ROOT/WEB-INF/web.xml and adjust the keyStore and keyStorePwd

<context-param>
<param-name>keyStore</param-name>
<param-value>sso_custom.jks</param-value>
</context-param>
<context-param>
<param-name>keyStorePwd</param-name>
<param-value>axway*</param-value>
</context-param>

• Adjust the filereg.xml to use the new sso_custom.jks, ssl_custom.jks and truststore_custom.jks

Edit ../PassPort/conf/filereg.xml and adjust the following 3 parameters:

<File name="pki.sso.keystore" path="conf/security/sso_custom.jks"/>

<File name="pki.truststore" path="conf/security/truststore_custom.jks"/>

<File name="pki.ssl.keystore" path="conf/security/ssl_custom.jks"/>

• Adjust the truststore.jks to use the new truststore_custom.jks

Edit ../PassPort/sso/webapps/ROOT/WEB-INF/web.xml and adjust the trustStore value

<context-param>
<param-name>trustStore</param-name>
<param-value>truststore_custom.jks</param-value>
</context-param>

For changing the default password edit the file ../PassPort/conf/filereg.xml.

Step 6. Restart PassPort

Restart PassPort to take into account the modifications.

1. Keep the same alias name (passportsecured,passportsso and passportca) within ssl_custom.jks ,sso_custom.jks and truststore_custom.jks when adding the new certificates.It's important to not rename/copy the truststore.jks into truststore_custom.jks.
   truststore_custom.jks as outlined in step 3 has to be created from scratch.
2. For the SSO Agent user certificate you must have the Extended Key Usage: TLS Web Server Authentication and TLS Web Client Authentication.
3. The ssl_custom.jks contains the SSL certificate which will be presented by PassPort for incoming SSL connections (default HTTPS interfaces 6453,6900 ../PassPort/conf/passport.properties).
   The sso_custom.jks contains the SSO certificate of the SSO Agent.
   In truststore_custom.jks is present the trusted certificate chain which signed the SSL and SSO user certificates.
4. Only ifCAS SSO is used (be default it isn't) update the files ../PassPort/webapps/WEB-INF/ssofilter_custom.jks with the custom SSO certificate and in ../PassPort/webapps/WEB-INF/truststore_custom.jks with its correspondent ROOT.
   
   keytool -delete -alias passportssofilter -keystore ssofilter_custom.jks -storepass axway*
   keytool -v -importkeystore -srckeystore MyOrg_USER_CAS_SSO.p12 -srcstoretype PKCS12 -srcstorepass axway* -destkeystore ssofilter_custom.jks -deststoretype JKS -alias MyOrg_USER_CAS_SSO -storepass axway* -destalias passportssofilter
   
   keytool -v -import -alias passportca -file MyOrg_ROOT.crt -storetype JKS -storepass axway* -keystore truststore_custom.jks
   
   
5. If keytool is not found then you’ll have to set to the PATH environment variable like this:
   
   keytool binary file is present in the ../Java/linux-x86/jre8_u40_64/bin/ installation folder.You can add it to the PATH environment to be taken into account like this:
   • UNIX: export PATH=$PATH:/PATH_PASSPORT_INSTALL/Java/linux-x86/jre8_u40_64/bin/
   • WINDOWS: set PATH=%PATH%;C:\PATH_PASSPORT_INSTALL\Java\win-x64\ jre8_u40_64\bin\
   
   
6. To check the new certificate connect to the https interface and check in browser the presented certificate chain or use the following openssl command:
   openssl s_client -connect passport_host:6453 -showcerts
   

To update the certificates in the related products that are using PassPort AM or SSO we recommend to check https://support.axway.com/kb/180303/language/en