Creating a keystore

Create a keystore instance for your keystore file, which contains the keys and certificates that are used, for example, to support Web Services Security and outbound email security.

When you provide a reference to URL, if the required HTTPS certificate is not in the cacerts keystore or an equivalent application server-level truststore configured, the "Failed to get JWK Keys" error is displayed. To fix the error, import the certificate into the cacerts keystore or equivalent application server-level truststore, and restart the server.

1. In the header of Designer Studio, click +Create > Security > Keystore.

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

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

4. Click Create and open.

5. In the Keystore location list, 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: C:\keystores\JWTKeys.jks.

     2. In the Keystore type field, select the keystore file type.

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

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

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

        • 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.

        • If you selected Function, in the Function field, enter the rule utility function to be invoked to get the password. The function must comply with the following syntax: @(RuleSetName:RuleUtilityLibraryName).RuleUtilityFunctionName, for example: @(myApp:PasswordUtil).getPassword().

     4. Optional: To disable caching of the keystore file, click Reload once per interaction.

     5. Optional: To change the default setting, in the Refresh strategy area, select Reload once per interaction to make Pega Platform reference the keystore file for every interaction, with no caching.

        By default the Cache keystore is selected to cache the keystore keys, with the 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. Optional: To change the default setting, in the Refresh strategy area, select Reload once per interaction to make Pega Platform reference the keystore file for every interaction, with no caching.

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

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

     1. Optional: Create a data page that contains keystore data, if one does not exist.

        1. Click Add.

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

        3. In the 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. Optional: Create an activity with a Java code step, that creates and populates the keystore data page, if such activity does not exist.

            1. Click Add.

            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: keystore_activity_JKS.

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

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

               • 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 = pega.getKeyStoreUtils();

                 keystoreUtils.loadKeystore(file);

                 }catch(Exception ex){

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

                 }

               • 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 = pega.getKeyStoreUtils();

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

                 }catch(Exception ex){

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

                 }

            6. Click Save.

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

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

        14. Click Save.

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

     3. In the Keystore type field, select the keystore file type.

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

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

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

        • 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.

        • 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).RuleUtilityFunctionName, for example: @(myApp:PasswordUtil).getPassword().

   • Amazon Key Management Service (KMS) - Click to reference the encryption key stored in the Amazon Web Services Key Management Service (AWS KMS).

     1. Create or log in to your Amazon Web Services account. In the Identity and Access Management create a Customer Master Key and access key.
        • For information about how to create a Customer Master Key, see the AWS Developer Guide topic about Creating Keys.
        • The access key provides the access key ID and secret access key that you need to enter in the keystore form. For more information, see Managing Access Keys for IAM Users.
        • When you create the encryption key, select the same geographic region for your key that your application is deployed in. Selecting the same geographic region gives your application the best network performance.
     2. In the Access key ID field, enter the access key ID created in AWS KMS.
     3. In the Secret access key field, enter the secret access key created in AWS KMS.
     4. In the Customer master key ID field, enter the Amazon Resource Name (ARN) of the customer master key created in AWS KMS.
     5. In the Customer data key rotation in days field, enter the number of days after which the key should rotate.

        The recommended (default) value is 90 days. You can set the minimum number of days to 30 and the maximum number of days to 365.

     6. Click Test connectivity to verify that all fields are filled out correctly and that Pega Platform is able to connect to AWS KMS.

6. Click Save.

Open topic with navigation