Creating a Keystore data instance

Create a Keystore data instance for your keystore file, which contains keys and certificates used, for example, to support Web Services Security and outbound email security. You can source a keystore from a data page, a URL, or an external file in one of the following standard formats: JKS, JWK, PKCS12, KEYTAB, or KEY. Keystore data instances can be referenced in the Keystore and Truststore fields for record types such as WS Security Profile data instances and REST connectors.

Note: When providing a reference to URL, if the required HTTPS certificate is not present in the cacerts keystore, the "Failed to get JWK Keys" error is thrown. To fix the error, import the certificate into the cacerts keystore and restart the server.

1. In Designer Studio, click Records > Security > Keystore.

2. Click Create.

3. In the Short description field, enter a name for the keystore.

4. In Keystore field, enter an ID for the keystore.

5. Click Create and open.

6. In the Keystore location field, choose one of the following options to select the source of the keystore:

   • Upload file - Click to upload the keystore file, such as a Java KeyStore (JKS) file.

     1. Click Upload file.

     2. Click Choose file, browse to the keystore file and select it.

     3. Click Upload file.

     4. In the Keystore type field, enter the keystore file type.

     5. In the Keystore password field, enter the password to the keystore file.

   • Reference to file - Click to reference the keystore file from a file location.

     1. In the Keystore file path field, enter the path to the keystore file, for example: file://JWTKeys.jks.

        Note: The file must be located in a Pega Platform server’s working directory.

     2. In the Keystore type field, select one of the following values to set the keystore file type: JKS, JWK, PKCS12.

     3. In the Keystore password field, enter the password to the keystore file.

        Note: If you are using a Global Resource Setting password, select Provide password by reference in clear text.

     4. In the Refresh strategy area, if you want to change the default setting, select Reload once per interaction to make Pega Platform reference the keystore file for every interaction, with no caching.

        Note: By default Cache keystore is selected to cache the keystore keys, with caching time set to 3600 seconds.

   • Reference to URL - Click to reference the keystore file that contains public keys from a URL address.

     1. In the Keystore url field, enter the URL address of the keystore file, for example: https://www.pegasystems.com/prweb/PRRestService/keys/v1/jwt/JWTGenerationProfile.

     2. In the Keystore type field, select the following value to set the keystore file type: JSON Web Key (JWK).

     3. In the Refresh strategy area, if you want to change the default setting, select Reload once per interaction to make Pega Platform reference the keystore file for every interaction, with no caching.

        Note: By default Cache keystore is selected to cache the keystore keys, with caching time set to 3600 seconds.

   • Reference to data page - Click to reference the keystore stored in the data page.

     1. In the Source data page field, enter the name of the data page that contains keystore data, for example: D_KeystoreJKS.

     2. If the data page does not exist:

        1. Click the Add icon.

        2. In the Label field, enter a title of the data page record.

        3. In Identifier field, enter an ID of the data page record, for example: D_KeystoreJKS.

        4. Define the context of the data page and the data page record and click Create and open.

        5. In the Structure field, select Page from the drop-down list.

        6. In the Object type field, enter Data-Admin-Security-Keystore.

        7. In the Edit mode field, select Read Only from the drop-down list.

        8. In the Scope field, select Node from the drop-down list.

        9. In the Data sources area, select Activity from the Source drop-down list.

        10. Next to the Activity name field, click Parameters and select the Pass current parameter page option.

        11. In the Activity name field, enter a name of the activity that creates and populates the keystore data page, for example: keystore_activity_JKS

        12. If the activity does not exist, click the Add icon to create an activity with a Java code step:

            1. In the Label field, enter a title of the data page record.

            2. In Identifier field, enter an ID of the data page record, for example: keystore_activity_JKS.

            3. Define the context of the data page and the data page record and click Create and open.

            4. In the Method field, enter java to create a Java method.

            5. If you intend to load a JKS type keystore into cache, in the Method Parameters area, the Java Source field, enter a code snippet similar to the following one:
               

               try{

               java.io.FileInputStream file = new java.io.FileInputStream("JKS_keystore_file_with_complete_path");

               KeyStoreUtils keystoreUtils = ((PegaAPI)tools).getKeyStoreUtils();

               keystoreUtils.loadKeystore(file);

               }catch(Exception ex){

               oLog.error("Failed to load keystore into cache "+ex);

               }

            6. If you intend to load a JWK type keystore into the cache, in the Method Parameters area, the Java Source field, enter a code snippet similar to the following one:
               

               try{

               java.net.URL url = new java.net.URL("JWK_keystore_URL_location");

               KeyStoreUtils keystoreUtils = ((PegaAPI)tools).getKeyStoreUtils();

               keystoreUtils.loadKeystore(url.openConnection().getInputStream());

               }catch(Exception ex){

               oLog.error("Failed to load keystore into cache "+ex);

               }

            7. Click Save.

        13. Optional: In the Load Management tab, Refresh strategy area, specify how long you want the keystore to be present in cache.

        14. Click Save.

     3. In the Keystore type field, select one of the following values to set the keystore file type: Java Key Store (JKS), Public Key Cryptography Standards (PKCS12), JSON Web Key (JWK).

     4. In the Password source field, select how you want to provide a password to the keystore.

     5. If you select Fixed password, in the Keystore password field, enter the password to the keystore file.

        Note: If you are using a Global Resource Setting password, select Provide password by reference in clear text.

     6. If you selected Clipboard property, in the Clipboard password property field, enter the name of the clipboard property that you want to get the password from, for example: operatorID.pyPassword.
        

     7. If you selected Function, in the Function field, enter the rule utility function to be invoked to get the password.
        The function must comply to the following syntax: @(RuleSetName:RuleUtilityLibraryName).RuleUtilityLibraryName, for example: @(Pega-RULES:String).getPassword().

7. Click Save.

Open topic with navigation