Skip to main content
Version: v3.4.x LTS

Certificate configuration scenarios

Last updated
:  |
... min read
|
Edit this page
Print
Open doc issue

Certificate configuration scenarios

After you have completed the Zowe certificates configuration questionnaire and chosen a certificate configuration scenario, follow the scenario-specific documentation and zowe.yaml examples in this article.

Required roles: system programmer, security administrator

Zowe servers require both a keystore to store the certificates and a truststore to validate certificates.

Zowe's assisted certificate setup begins with customizing certificate scenario YAML files found in the files/examples/setup/certificate sub-directory within your Zowe installation directory. Zowe will then use these scenario configurations and complete certificate setup via the zwe init certificate command.

note

Reminder: Zowe assisted generation of certificates is an option, but is not required. If you already have certificates and a key ring or keystore / truststore combination you created on your own, you can instead go to Finalize certificate configuration.

What is a valid certificate in Zowe?​

A valid certificate for use in Zowe conforms to one of the following two options:

  • The certificate does not contain the Extended Key Usage section.
  • The certificate does contain the Extended Key Usage section, and also includes the Server and Client authentication fields.

Scenario overview​

Each scenario described in this article provides the configuration details via code snippets which you can use to edit your Zowe YAML configuration within the zowe.setup.certificate section.

note

Ensure that all certificate alias values for all scenarios use only lower-case.

Running a scenario file​

Zowe supplies 5 certificate scenario YAML files in the files/examples/setup/certificate sub-directory within your Zowe installation directory. The scenario section below describes what each scenario will accomplish, and how to complete customization of the respective scenario YAML files. Once you have selected and finished configuring one of these scenarios, follow the below instructions to execute the scenario.

Run scenario YAML with configmgr

  1. Identify the fully-qualified path to your selected scenario YAML configuration file. In this example, we will use /path/to/files/examples/setup/certificate/scenario-1.yaml.

  2. Identify the fully-qualified path to your main zowe.yaml configuration file. In this example, we will use /path/to/zowe.yaml.

  3. Create the following configuration parameter, replacing our example paths with your real ones:

    FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)

  4. Navigate to your Zowe installation root directory.

  5. Submit ./bin/zwe init certificate using the configuration parameter from Step 3. Note the quotation marks surrounding the configuration parameter! If you are running Scenario 3, 4, or 5, you can add --dry-run to the command and review the JCL used to create the keyring before submission.

    ./bin/zwe init certificate --update-config -c "FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)" 

    # If you are using scenarios 3, 4, or 5, this will print JCL to the console for review
    ./bin/zwe init certificate --dry-run --update-config -c "FILE(/path/to/files/examples/setup/certificate/scenario-1.yaml):FILE(/path/to/zowe.yaml)"
tip

If you encounter issues when configuring your certificate, see Troubleshooting the certificate configuration, to find resolution of errors.

Scenario 1: Use a file-based (PKCS12) keystore with Zowe generated certificates​

Follow this procedure and configure scenario-1.yaml within the files/examples/setup/certificate directory to enable Zowe to use newly generated PKCS12 certificates stored in a USS directory. These certificates will be signed by a newly created, self-signed Certificate Authority. As such, this is not recommended for production environments.

Click here for details.

In your scenario-1.yaml configuration file:

  1. Customize the keystore directory in the following format: 
    directory: /var/zowe/keystore
  2. Customize the certificate alias name. The default value is localhost.
  3. Set the keystore password. The default value is password.
  4. (Optional) Uncomment the lock field, which locks the keystore directory so it is accessible only to the Zowe runtime user and group: 
    lock: true
  5. (Optional) Set the alias name of certificate authority. The default value is local_ca. 
    caAlias: local_ca
  6. (Optional) Set the password of the keystore stored certificate authority. The default value is local_ca_password. 
    caPassword: local_ca_password
  7. Set the validity in days for the Zowe generated certificates 
    validity: 3650
  8. (Optional) Specify the distinguished name for Zowe generated certificates. If you do not want to customize this, you can leave it commented out. 
    dname:
      caCommonName: ""
      commonName: ""
      orgUnit: ""
      org: ""
      locality: ""
      state: ""
      country: ""
  9. (Optional) Set the domain names and IPs specified in nested subsection SAN. If this field is not defined, the zwe init command uses the value zowe.externalDomains, which are found in your main zowe.yaml file. 
    san:
        # sample domain name
        - dvipa.my-company.com
        # sample IP address
        - 12.34.56.78
tip

To get the san IP address, run ping dvipa.my-company.com in your terminal.

Example scenario-1 yaml file:

zowe:
  setup:
    certificate:
      type: PKCS12
      pkcs12:
        directory: /global/zowe/keystore
        lock: true
        name: localhost      # Optional, default value is localhost.
        password: password   # Optional, default value is password.
        caAlias: local_ca    # Optional, default value is local_ca.
        caPassword: local_ca_password  # Optional, default value is local_ca_password.
      dname:                # Distinguished name for Zowe generated certificates. All optional.
        caCommonName: ""
        commonName: ""
        orgUnit: ""
        org: ""
        locality: ""
        state: ""
        country: ""
      validity: 3650
      san:
        - dvipa.my-company.com
        - 12.34.56.78

Your yaml file is now configured to enable Zowe to use generated PKCS12 certificates. You can now go to Running a scenario file.

The following command output shows the generation of a PKCS12 keystore using the default values, and has the following associated artifacts. (Note that some detailed output messages have been omitted.)

  • The CA is created.
  • The keystore is created and the CA is added to the keystore.
  • The certificate is created and is added to the keystore.
  • The truststore is created.
  • Directory permissions are changed to restrict access to the private key.

Command output:

#>zwe init certificate -c <path-to-your-zowe-configuration-yaml> --update-config
-------------------------------------------------------------------------------
>> Creating certificate authority "local_ca"
>> Certificate authority local_ca is created successfully.
-------------------------------------------------------------------------------
>> Export keystore /global/zowe/keystore/local_ca/local_ca.keystore.p12
>> Keystore /global/zowe/keystore/local_ca/local_ca.keystore.p12 is exported successfully.
-------------------------------------------------------------------------------
>> Creating certificate "localhost"
>> Certificate localhost is created successfully.
-------------------------------------------------------------------------------
>> Export keystore /global/zowe/keystore/localhost/localhost.keystore.p12
>> Keystore /global/zowe/keystore/localhost/localhost.keystore.p12 is exported successfully.
-------------------------------------------------------------------------------
>> Export keystore /global/zowe/keystore/localhost/localhost.truststore.p12
>> Keystore /global/zowe/keystore/localhost/localhost.truststore.p12 is exported successfully.
-------------------------------------------------------------------------------
>> Lock keystore directory /global/zowe/keystore
>> Keystore directory /global/zowe/keystore is locked.
-------------------------------------------------------------------------------
>> Update certificate configuration to <path-to-your-zowe-configuration-yaml>

- update "zowe.certificate.keystore.type" with value: PKCS12
...
- update "zowe.certificate.pem.certificateAuthorities" with value: /global/zowe/keystore/local_ca/local_ca.cer

>> Zowe configuration is updated successfully.

#>

You are ready to Finalize your Zowe Certificate Configuration.

For more information about using a file-based PKCS12 certificate in Zowe services, see the video tutorials on YouTube. More information about this certificate configuration scenario is also available in this Medium blog post. Both of these resources target an older release of Zowe and modify zowe.yaml directly, so you'll need to adapt some of their configuration to your scenario-1.yaml configuration file instead. ::

Scenario 2: Use a file-based (PKCS12) keystore and import a certificate generated by another CA​

Follow this procedure and configure scenario-2.yaml within the files/examples/setup/certificate directory to enable Zowe to use previously generated certificates with a PKCS12 keystore stored in a USS directory.

Click here for details.

  1. Set the type of the certificate storage to PKCS12.

  2. Customize the keystore directory in the following format:

    directory: /var/zowe/keystore

  3. Lock the keystore directory so it is accessible only to the Zowe runtime user and group:

    lock: true

  4. Set keystore password. The default value is password.

  5. Set the existing PKCS12 keystore which holds the certificate issued by an external CA.

    keystore: "<your-keystore-value>"

  6. Set the password of the keystore set in step 5.

    password: "<your-password-value>"

  7. Specify the alias of the certificate to be imported.

    alias: "<your-alias-value>"

  8. Set the path to the certificate authority that signed the certificate to be imported. PEM-formatted certificate authorities can be imported.

    importCertificateAuthorities:
      - "<empty-or-/path/to/your/ca.cer>"
note

PEM format certificate authorities can be imported and trusted.

Example zowe yaml for scenario 2 (PKCS12):

certificate:
  type: PKCS12
  pkcs12:
    directory: /var/zowe/keystore
    lock: true
    name: localhost
    password: password
    import:
      keystore: /certs/system.keystore.p12
      password: password
      alias: server
  importCertificateAuthorities:
    - /certs/extca.1.cer
    - /certs/extca.2.cer
note

Due to the limitation of the RACDCERT command, the importCertificateAuthorities field can contain a maximum of two entries.

Your yaml file is now configured to enable Zowe to use a file-based PKCS12 keystore to import a certificate generated by another CA. You can now go to Running a scenario file.

Scenario 3: Use a z/OS keyring-based keystore with Zowe generated certificates​

Follow this procedure and configure scenario-3.yaml within the files/examples/setup/certificate directory to enable Zowe to use newly generated certificates with a z/OS keyring-based keystore.

Click here for details.

  1. Set the type of the certificate storage to one of the following keyring types:

    • JCERACFKS (default)
    • JCEKS
    • JCECCAKS
    • JCECCARACFKS
    • JCEHYBRIDRACFKS

  2. Under the nested subsection keyring:, specify the following keyring values:

    • keyring name 
      name: ZoweKeyring
    • Label of Zowe certificate. The default value is localhost. 
      label: localhost
    • Label of Zowe CA certificate. The default value is localca. 
      caLabel: localca
    • (Optional) The distinguished name for Zowe generated certificates. 
      dname:
          caCommonName: ""
          commonName: ""
          orgUnit: ""
          org: ""
          locality: ""
          state: ""
          country: ""

  3. (Optional) Set the validity in days for the Zowe generated certificates. Defaults to 3650 days.

    validity: 3650

  4. (Optional, Recommended) Set the domain names and IPs specified in the certificate SAN. If this field is not defined, the zwe init command uses the value zowe.externalDomains.

    san:
      - dvipa.my-company.com
      - 12.34.56.78
note

Due to the limitation of the RACDCERT command, this field should contain exactly two entries with the domain name and IP address.

Example zowe yaml for scenario 3:

certificate:
  type: JCERACFKS
  keyring:
    name: ZoweKeyring
    label: localhost
    caLabel: localca
  dname:
    caCommonName: "Zowe Instances CA"
    commonName: "Zowe Service"
    org: "My Company"
    locality: "Prague"
    state: "Prague"
    country: "CZ"
  validity: 3650
  san:
    - system.my-company.com
    - 12.34.56.78

Your yaml file is now configured to enable Zowe to use a z/OS keyring-based keystore with Zowe generated certificates. You can now go to Running a scenario file.

The following command output shows the generation of a JCERACFKS certificate using the default values. Note that some detailed output messages have been omitted.

Command output:

#>zwe init certificate -c <path-to-your-zowe-configuration-yaml> --update-config
-------------------------------------------------------------------------------
>> Generate Zowe certificate in keyring

>>>> Modify ZWEKRING
    - IBMUSER.ZWEV3.CUST.JCLLIB(ZW101431) is prepared
>>>> Submit IBMUSER.ZWEV3.CUST.JCLLIB(ZW101431)
    - Job ZWEKRING(JOB03054) ends with code 0 (COMPLETED).
>> Certificate is generated in keyring successfully.

-------------------------------------------------------------------------------
>> Update certificate configuration to <path-to-your-zowe-configuration-yaml>
>> Zowe configuration is updated successfully.

#>
tip

As shown in the example, the job ends with code 0. There may, however, be failures in the individual steps. It is advised to check the job output. The security manager commands in the job are generated based on the value of zowe.security.product. Job steps for each product can be determined by the security manager.

Scenario 4: Use a z/OS keyring-based keystore and connect to an existing certificate​

Follow this procedure and configure scenario-4.yaml within the files/examples/setup/certificate directory to enable Zowe to connect existing certificates with a z/OS keyring-based keystore.

Click here for details.

  1. Set the type of the certificate storage to one of the following keyring types:

    • JCERACFKS (default)
    • JCEKS
    • JCECCAKS
    • JCECCARACFKS
    • JCEHYBRIDRACFKS

  2. Under keyring, specify the keyring name:

    name: ZoweKeyring

  3. Under the nested subsection connect, specify the following parameters:

    • The current owner of the existing certificate. Possible values can be SITE or a user ID. 
      user: IBMUSER
    • The label of the existing certificate to be connected to the Zowe keyring. 
      label: ""
    • All certificate authorities you want to be trusted in the Zowe keyring. 
      importCertificateAuthorities:
        - ""
note

Due to the limitation of RACDCERT command, this field should contain a maximum of 2 entries.

Example zowe yaml for scenario 4:

zowe:
  setup:
    certificate:
      type: JCERACFKS
      keyring:
        name: ZoweKeyring
        connect:
          user: IBMUSER
          label: ""
      importCertificateAuthorities:
        - "zOSMFCA"

Your yaml file is now configured to enable Zowe to use a z/OS keyring-based keystore with Zowe generated certificates. You can now go to Running a scenario file.

The following example uses an existing JCERACFKS certificate for Zowe's z/OS components. For more information about configuration in this scenario, see this Medium blog post, or the video tutorials in this YouTube playlist.

Example: Alt text

Note: In this example, the command zwe init certificate -c ./zowe.yaml --security-dry-run allows the JCL to be inspected before submission, as well as handed off to a security administrator who has privileges to submit the JCL under their user ID. By default, the JCL id submitted immediately.

If you would like to use this example in your Zowe configuration YAML file, replace the following four fields with your own values:

  • Replace ZoweKeyringZOSMF with the your own key ring name.
  • Replace IZUSVR with the user name who is the owner of the existing certificate.
  • Replace DefaultzOSMFCert.IZUDFLT with the label of the existing certificate you are connecting to (which is owned by the previously referenced user ID).
  • Replace zOSMFCA with the certificate authority that is used to sign the certificate.

Scenario 5: Use a z/OS keyring-based keystore and import a certificate stored in a data set​

Follow this procedure and configure scenario-5.yaml within the files/examples/setup/certificate directory to enable Zowe to import existing certificates from a dataset into a z/OS keyring-based keystore.

Click here for details.

  1. Set the type of the certificate storage to one of the following keyring types:

    • JCERACFKS (default)
    • JCEKS
    • JCECCAKS
    • JCECCARACFKS
    • JCEHYBRIDRACFKS

  2. Under keyring, specify the following keyring values:

    • keyring name 
      name: ZoweKeyring
    • Label of Zowe certificate. The default value is localhost. 
      label: localhost

  3. Under the nested subsection import, specify the following parameters:

    • The name of the data set that holds the certificate issued by another CA. This data set should be in PKCS12 format and contain private key. 
      dsName: "<YOUR.CERT.DS>"
    • The password for the PKCS12 data set. 
      password: "<your-pkcs12-password>"

Example zowe yaml for scenario 5:

zowe:
  setup:
    certificate:
      type: JCERACFKS
      keyring:
        name: ZoweKeyring
        label: localhost  # Optional, default value is localhost.
      import:
        dsName: ""
        password: ""

Your yaml file is now configured to use a z/OS keyring-based keystore and import a certificate stored in a data set. You can now go to Running a scenario file.

On this page