Textkernel Search + Match: Portal Certificate Creation

Note: To take advantage of the features mentioned in this documentation, your Org needs to be using (Undefined variable: bh4SFVersions.Latest Package Version) or newer. See Release Notes for more details about which features were introduced in each release. If you would like to upgrade to the current release, contact Bullhorn for Salesforce Support.

Overview

Textkernel Search + Match is provided through the Textkernel Portal. This article details the certificate types, certificate validation, and certificate creation used in the Textkernel Portal Configuration. This article does not cover the process of signing a certificate. See Textkernel Search + Match: Setup and Configuration Guide for general configuration information.

Certificate Types

Each Textkernel Portal JSON Web Token (JWT) sent from a Salesforce Org to a portal environment contains 3 certificates:

  • Signing certificate: This is created in a Salesforce Org and used to sign the JWT. The common name (CN) is arbitrary.
  • Intermediate certificate: This is issued by Bullhorn ATS and used to sign the signing certificate. The common name is BH4Force Partner Services Intermediate CA.
  • Root certificate: This is issued by Bullhorn ATS and used to sign the intermediate certificate. It is stored in the portal in order to validate a certificate chain in JWT. The common name is BH4Force Partner Services Root CA. The key identifier is f52ce70c1948b6d0e0a91c0c8535a5dbd428f4ab.

Certificate Validation

When the Textkernel Portal authentication service receives a JWT, it validates the certificates it contains. The certificates must comply with these rules:

  • They represent a valid certificate chain, meaning the signing certificate must be signed with the intermediate certificate, which is signed with the root certificate.
  • The root certificate is one of root certificates stored in the portal.
  • The issuer (iss) JWT field contains the common names of the signing and intermediate certificates separated by a colon (:). For example, if the common name of the signing certificate is Textkernel Portal Certificate, then the iss value is Textkernel Portal Certificate:BH4Force Partner Services Intermediate CA.
  • The iss value provided in the JWT matches the issuer specified in the portal environment (account) configuration. The name of the portal account is specified in the Account Name field of the Textkernel Portal Configuration custom metadata type record.

Managing Certificates

Keep the following in mind when managing Textkernel Portal signing certificates:

  • Each Textkernel Portal account has only one issuer set in the configuration. It is not possible to use two different signing certificates with distinct common names in two different Orgs to log in to the same portal account.
  • The same signing certificate can be used in different Orgs to log in to the same portal account.
  • Different signing certificates can be used in different Orgs to log in to the same portal account as long as their common names are the same.
  • To use one signing certificate in several Orgs, create a certificate in one Org and then import it into the other Orgs via a JKS file.

Create a New Signing Certificate

Get the Previous Certificate Common Name

If the org this certificate is being created for has never been connected to a portal environment, skip this step.

Follow these steps to replace an existing signing certificate and reuse the common name of the existing certificate for the new one. To use a different common name in the new certificate, the new issuer (iss JWT field value) must be provided to Textkernel so the portal environment configuration can be updated otherwise the JWT authentication will fail.

  1. Log in to the Org where the certificate needs to be replaced.
  2. Go to Setup > Custom Metadata Types > Textkernel Portal Configuration.
  3. Click the Manage Textkernel Portal Configurations button.
  4. Open the Textkernel Portal Configuration record.
  5. Note the Signing Certificate Name field value.
  6. Go to Setup > Certificate and Key Management.
  7. Open the certificate where the Signing Certificate Name noted earlier matches the Unique Name field.
  8. Locate and copy the common name in the Certificate field:

Create a New Certificate

These steps assume the new signing certificate can be signed with the intermediate certificate. The process of signing a certificate is not covered in this document.

  1. Log in to the Org that needs a certificate created.
  2. Go to Setup > Certificate and Key Management.
  3. Click the Create CA-Signed Certificate button.
  4. Select the Exportable Private Key checkbox.
  5. Set the Key Size field to 2048.
  6. To replace the previous certificate, enter the common name of the previous certificate in the Common Name field. If the Org has never been connected to the portal, enter any value.
  7. Fill the remaining fields with any meaningful values. Values from the previous certificate can be used, if it exists.
  8. Click the Save button.
  9. Click the Download Certificate Signing Request button and save the CSR file to the computer.
  10. Sign the certificate with the intermediate certificate using the CSR file and save it to the computer. The process of signing a certificate is not covered in this document.
  11. Return to the Org and open the certificate that was just created.
  12. Click the Upload Signed Certificate button.
  13. Select the signed certificate in the file system and click the Save button.

Update the Signing Certificate in the Portal Configuration

These steps make the JWT portal authentication use the new signing certificate. If the Org has never been connected to the portal, values for other fields (like Login URL and Account Name) will also need to be provided, which is not covered in this document.

  1. Go to Setup > Custom Metadata Types > Textkernel Portal Configuration.
  2. Click the Manage Textkernel Portal Configurations button.
  3. Open an existing Textkernel Portal Configuration record by clicking the Edit button, otherwise click the New button.
  4. Enter the Unique Name value from the certificate into the Signing Certificate Name field. The Unique Name can be found by going to Setup > Certificate and Key Management.
  5. Enter the Common Names of the signing and intermediate certificates separated by a colon into the JWT Issuer field. For example, if the common name of the signing certificate is TextKernelClosed A BH4SF partner. One of the Search and Match / Resume Parsin services providers integrated with BH4SF Portal Certificate and the intermediate certificate is BH4Force Partner Services Intermediate CA then TextKernel Portal Certificate:BH4Force Partner Services Intermediate CA would be entered in the JWT Issuer field.

    If the new JWT Issuer value differs from the previous one, the new value must be provided to Textkernel so the portal account configuration can be updated.

  6. If the signing certificate is not already downloaded to the computer, open it in the Org by going to Setup > Certificate and Key Management, then click the Download Certificate button to save it to the computer.
  7. Open the certificate using a text editor (ex: Notepad++). It will look like this:
  8. Copy and paste the text content of the certificate to another tab (or window) of the text editor.
  9. Remove the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.
  10. Remove all line breaks to transform the text content into a single line. The result should look like this:
  11. Copy and paste the text content into the Signing Certificate of the Textkernel Portal Configuration record.
  12. If the Org has never been connected to the portal before, provide values for other fields.
  13. Click the Save button.

Share a Certificate with Other Orgs

Use these steps if a signing certificate was created in another Org. The portal configuration in the Org will need to be updated after these steps, see the Update the Signing Certificate in the Portal Configuration section for instructions.

Create a .jks File (Windows)

If a JKS file containing just the needed certificate already exists, skip this section.

  1. Log in to an Org that contains the certificate.
  2. Go to Setup > Certificate and Key Management.
  3. Open the certificate and note the Unique Name field value.
  4. Go back to the Certificate and Key Management page.
  5. Click the Export to Keystore button. This will create a JKS file containing all the certificates listed on the Certificate and Key Management page.
  6. Create a password for the new JKS file and click Save.
  7. Find the folder on the computer where the Java KeyTool (keytool.exe) is located. It’s provided as a part of the Java Development Kit (JDK). If keytool.exe isn’t on the computer, download and install the latest JDK version.
  8. Copy the JKS file into that folder.
  9. Run CMD as an administrator.
  10. Use the cd command to navigate to the keytool folder.
  11. Run the following command and replace keystore.jks with the name of the JKS file before running the command:
    • keytool -list -keystore keystore.jks
  12. Enter the keystore password.
  13. Locate certificate aliases in the output. The aliases in the output are lowercase Unique Name field values of certificates in the org. All certificates except for the one being moved to a new Org need to be removed from the JKS file otherwise all of them will be imported to the target Org.
  14. Run the following command and replace keystore.jks with the name of the JKS file and selfsignedcert_28jan2021_153812 with the alias of the certificate to delete before running the command:
    • keytool -delete -alias selfsignedcert_28jan2021_153812 -keystore keystore.jks
  15. Repeat the previous steps to delete extra certificates until only the correct certificate is left in the JKS file.

Import the Certificate into an Org

  1. Log in to the Org the certificate should be imported to.
  2. Go to Setup > Certificate and Key Management.
  3. Click the Import from Keystore button.
  4. Select the JKS file in the file system and enter the password.
  5. Click the Save button.
  6. The new certificate is now displayed on the Certificate and Key Management page. Follow the steps in the Update the Signing Certificate in the Portal Configuration section.

    If this error is displayed in a developer or test Org use these steps to resolve it.

    1. Go to Setup > Identity Provider.
    2. Click the Enable Identity Provider button. If nothing happens, do it several times.
    3. Click the Save button. A new self-signed certificate will appear on the Certificate and Key Management page.
    4. Repeat steps 2-6 above to import the certificate.