Creating and updating the SP signing certificate for SAML authentication

If you are planning to use any of the advanced SAML authentication functions described in Configuring advanced functions for SAML authentication, you must create the service provider (SP) signing certificate because it is not provided out of the box.

You create a new file or update the SP certificate if it has expired.

Related topics

Configuring SAML 2.0 authentication

To create an SP signing certificate

To generate a keystore file containing the key pair for SAML SP signing request, run the following command:

keytool -keystore <keystorefile> -genkey -alias <aliasname> -keyalg RSA -sigalg SHA256withRSA -keysize 2048 -validity 730

Example:

keytool -keystore cot.jks -genkey -alias sp-signing -keyalg RSA -sigalg SHA256withRSA -keysize 2048 -validity 730

A cot.jks keystore file is created. The file contains a keypair with the alias as sp-signing.

Save the generated file on the file system (for example, the conf directory in Tomcat) of a machine where the BMC Helix Single Sign-On server is installed.

Reconfigure the Tomcat server.xml file by adding a new connector port, for example, x443 for TLS connection.

Example:

<Connector port="9443" protocol="HTTP/1.1"  SSLEnabled="true" maxThreads="300" scheme="https" secure="true"
maxHttpHeaderSize="32768" clientAuth="false" sslProtocol="TLS" keystoreFile="C:\Program Files\Apache Software Foundation\Tomcat _RSSO\conf\keystore.jks" keystorePass="changeit" />

Restart the Tomcat server.
(HA mode) Save the keystore file on each BMC Helix SSO server node in a cluster on the same file directory and make sure you restart the Tomcat server.

To update the SP certificate on the BMC Helix SSO server

If your SP signing certificate has expired, perform the following tasks to update the certificate on the BMC Helix SSO server and at the identity provider side:

To update the java keystore cot.jks file

Important

The paths specified in the following procedures are for Windows OS.
The file name of the java keystore is cot.jks.

To update the java keystore cot.jks file

Perform the following steps on the system where the BMC Helix SSO server is installed.

Navigate to the <tomcat>\rsso\WEB-INF\classes directory.
Locate the cot.jks file and create a backup of the file.
To delete the alias 'sp-signing’ from the existing cot.jks file, run the following command:
```
keytool -delete -alias test2 -keystore cot.jks
```

To create a new keypair with alias ‘test2’ in the existing cot.jks file, run the following command:

keytool -keystore cot.jks -genkey -alias test2 -keyalg RSA -sigalg SHA256withRSA -keysize 2048 -validity 730

To export ‘test2’ certificate in the PEM format, run the following command:
```
keytool -export -keystore cot.jks -alias test2 -file test2.pem –rfc
```
The system creates a test2.pem file.
Take a backup of the updated cot.jks file.
(HA mode) If you have BMC Helix SSO server in a cluster, replace the cot.jks file in the <tomcat>\rsso\WEB-INF\classes folder with the updated cot.jks file.

To update the signing certificate in BMC Helix SSO Admin Console
To update the SP metadata at the IdP side

To update the signing certificate in BMC Helix SSO Admin Console

Log in to the BMC Helix SSO Admin Console.
Navigate to General > Advanced tab.
Enter the following details:
- Keystore File with the full path
- Keystore Password
- Signing Key Alias
Click Save.
Navigate to Realm, and select a realm configured for SAML authentication.
On the Authentication tab, click View Metadata and verify whether the SP metadata is updated with the new signing certificate.

To update the SP metadata at the IdP side

Export the SP metadata and save it to a local file.
Share the exported SP metadata and the new signing certificate with the IdP team.
If you have Active Directory Federation Services (AD FS) configured as the IdP, perform the following steps to add the new signing certificate:
1. Open the context menu for the relying party trust and select the Update from Federation Metadata check box.
2. Open the Properties dialog of the relying party for BMC Helix SSO .
3. Navigate to the Signature tab, and click Add.
4. Select the new signing certificate file, and click OK.

To update the SP certificate in an HA environment

If you have BMC Helix SSO deployed in a high availability mode, and AD FS configured as the IdP, to achieve a zero-down time when you update the signing certificate, perform the following steps:

Shut down one BMC Helix SSO server instance and update the java keystore cot.jks file on it.
Update the signing certificate in BMC Helix SSO Admin Console.
Update the SP metadata at the IdP side.
Important

You must not delete the old signing certificate.
Make BMC Helix SSO server instance up again.
Repeat step 1 to step 4 for all BMC Helix SSO server instances.
After the keystore cot.jks is updated on all BMC Helix SSO server instances, remove the old signing certificate on BMC Helix SSO relying party at the AD FS side.