Generating the JWT keystore and certificates

A JSON Web Token (JWT) is used to secure requests between IBM® Cúram Social Program Management and IBM Watson™ Assistant. The JWT is digitally signed by the Social Program Management application by using a public/private key pair, which is stored in a keystore.

The private key in the keystore must be accessible by the Social Program Management runtime code so the JWT can be generated and signed when an outbound request to Watson Assistant is made.

You must add the public key in two locations:

  • Watson Assistant needs the public key so that requests from Social Program Management to Watson Assistant are trusted.
  • The Social Program Management application server's truststore, so if Watson Assistant needs to make an API call back into Social Program Management to retrieve data in order to answer questions, the JWT that is passed along with the request is accepted. For more information about configuring the application server to allow authentication with JWT, see the Configuring application servers for JSON Web Tokens related link.

Self-signed certificates for development and test

For development and test environments, you can generate a keystore with a self-signed cert with Social Program Management Ant build scripts if needed.

For production environments, a keystore with a certificate that is signed by a Trusted Certificate Authority is recommended.

To generate and use a self-signed cert, use the configtest or configure Ant build scripts. These scripts generate a keystore and self-signed cert by using the properties that are specified in the /EJBServer/project/properties/JWTKeystore.properties file. Both the generated keystore and properties file are added to a JWTCryptoConfig.jar file, which is placed in the JAVA_HOME/jre/lib/ext directory. The public certificate is also exported to this directory, so it can be retrieved later and added to Watson Assistant. The configure build script also imports the public certificate into the application servers truststore.

The values that are used for the keystore and certificate are in the file /EJBServer/project/properties/JWTKeystore.properties as shown in this example.

KEYSTORE PROPERTIES 
jwt.keystore.filename=jwtkeystore.p12
jwt.keystore.location= (Leave empty when you use the generated self-signed certificate)
jwt.keystore.password=password
jwt.keystore.type=PKCS12

jwt.key.alias=jwtkeyalias (The alias name for the private key used for signing the JWT)
jwt.cert.alias=jwtcertalias (The alias name of the public cert in the truststore)
jwt.public.cert.filename=jwtcert.cer (The name of the file that will be created which contains the cert's public key)

CERTIFICATE PROPERTIES
(These are used to create a self-signed cert, if using the default generated keystore, at build time.
These properties are not required if using an existing keystore with existing certificate).
jwt.cert.common.name=JWT
jwt.cert.organisation.unit=
jwt.cert.organisation=
jwt.cert.locality=
jwt.cert.state=
jwt.cert.country=
jwt.cert.key.validity=1825
jwt.key.alg=RSA
jwt.key.size=2048

Use existing keystore and certificate

You can use an existing keystore and certificate instead of the default keystore and self-signed certificate by updating the appropriate properties in the /EJBServer/project/properties/JWTKeystore.properties file.

  1. If needed, customize the properties in the /EJBServer/project/properties/JWTKeystore.properties file. 

    jwt.keystore.filename= (The name of the keystore file)
jwt.keystore.location= (The absolute path to the keystore file)
jwt.keystore.password= (The password of the keystore)
jwt.keystore.type= (The type of the keystore)
jwt.key.alias= (The alias of the private key to use for signing the JWT)

  2. From EJBServer directory, run the configtest build target to generate the JWTCrypto.jar file and the public key jwtcert.cer in the $JAVA_HOME/jre/lib/ext/ directory.

Troubleshooting

Rerunning configtest build target and reimporting the JWT public certificate into the truststore

If you rerun the configtest build target after you followed the steps for importing the JWT certificate into the truststore, you must reimport the certificate again because the original certificate is no longer valid. Reimporting the certificate again applies only to applications deployed on WebSphere® or on WebSphere® Liberty.

For more information, see the Configuring application servers for JSON Web Tokens related link.
Starting the Watson Assistant chatbot
If you can’t start Watson Assistant chatbot, search for all files that start with ‘jwtcert’. Where there are multiple entries, delete the old files. Then, rerun the build configtest target.