Register with Central Governance

Transfer CFTs 3.1.3 or higher can register with Central Governance in one of two ways:

Additional tasks:

Automatically activate connectivity

UNIX/Windows

The automatic activation is only available on UNIX and Windows platforms, and can be done during the installation. Please refer to the OS specific Transfer CFT Installation Guide > Customize the initiliaze.properties file > Central Governance section.

Manually activate connectivity

All OS

This section describes how to manually modify the Transfer CFT configuration to enable Central Governance connectivity in command line if you did not do so during installation.

All commands in this section are performed using CFTUTIL unless stated otherwise.

Prerequisites

  • You have the Central Governance shared secret that was generated by the Central Governance administrator.
  • Transfer CFT and Copilot services are stopped.

On Transfer CFT z/OS

Use compliant characters for the z/OS shared secret

When setting the Central Governance "shared secret" during a Transfer CFT z/OS installation, translation issues may occur if you use certain characters. For example, if you enter !SECRET (using code page IBM-1147) the shared secret is translated to §SECRET during the Central Governance registration. Therefore, you must use compliant characters in the shared secret value when working in a z/OS environment.

Verify the UCONF setting

Prior to the registration, you must ensure that the JCL CFTMON (copilot.misc.cftstart.enable = Yes) is configured to match the jobname or the STC name used to launch Transfer CFT.

Procedure

All commands in this section are performed using CFTUTIL unless stated otherwise. For details on the UCONF parameters referenced in this section, please see UCONF: Central Governance options.

Disable previously used connectors

Enabling Central Governance connectivity if you have performed an upgrade replaces any standalone connectors. Therefore, prior to connecting to Central Governance you must deactivate all previously activated connectors, for example PassPort AM, PassPort PS, and Sentinel.

Unset the UCONF parameters:

uconfunset id=am.type

uconfunset id=sentinel.xfb.enable

uconfset id=pki.type, value=cft

Note When running in a z/OS environment you must additionally set the am.passport.superuser with the user that will start the Copilot server.

Define UCONF parameters used for Transfer CFT instance identification

Set the parameters used to identify a Transfer CFT instance. Follow these guidelines, otherwise the registration will fail:

  • The length of the cft.instance_id value is limited to 24 characters.
  • The address set in cft.full_hostname must be reachable from Central Governance.

uconfset id=cft.instance_id, value=<cft_id>

uconfset id=cft.instance_group, value=<cft_instance_group>

uconfset id=cft.full_hostname, value=<cft_address>

Additionally, if running in a multi-host/multi-node environment, you must set the load balancer address(FQDN or IP address) and port that Central Governance uses to reach the Transfer CFT (copilot.general.ssl_serverport):

uconfset id=cft.multi_node.load_balancer.host, value=<load_balancer_address>

uconfset id=cft.multi_node.load_balancer.port,value=<load_balancer_port>

Optionally define a proxy server for Central Governance to Transfer CFT communication

If you opt to use a proxy server for Central Governance to connect to Transfer CFT, set the following parameters.

uconfset id=cg.proxy.in.host, value= <proxy_address>

uconfset id=cg.proxy.in.port,value= <proxy_port>

uconfset id=cg.proxy.in.login, value= <proxy_login>

uconfset id=cg.proxy.in.password, value= <proxy_login_password>

Optionally define a proxy server for Transfer CFT to Central Governance communication

If you opt to use a proxy server for Transfer CFT to connect to Central Governance, set the following parameters.

uconfset id=cg.proxy.out.host, value= <proxy_address>

uconfset id=cg.proxy.out.port,value= <proxy_port>

uconfset id=cg.proxy.out.login, value= <proxy_login>

uconfset id=cg.proxy.out.password, value= <proxy_login_password>

Import the root certificate for the Governance CA 

  1. Download the root Governance CA, which is used to authenticate Central Governance.
  2. Import this root CA into the PKI database using the PKIUTIL PKICER command.
  3. Set the iname to the root CA path.
  4. PKIUTIL pkicer  id = 'CG_CA',

            iform    = 'PEM',

            iname    = '<directory>/<root_certificate>.pem',

            itype    = 'ROOT',

            state    = 'ACT',

            mode     = 'CREATE'

  5. Define the UCONF variable cg.ca_cert_id, which must correspond with the value you set in the previous step. It is required so that Transfer CFT knows which certificate to use to authenticate Central Governance. Using CFTUTIL:
  6. uconfset id=cg.ca_cert_id, value=<CG_CA_Alias>

Define the parameters used for the Central Governance connection

Set  the following parameters that are used to connect to Central Governance.

uconfset id=cg.host, value=<cg_host_address>

uconfset id=cg.port, value=<cg_port>

Set the shared secret that the Central Governance administrator generated and provided.

uconfset id=cg.shared_secret, value=<shared_secret>

Optionally define the configuration policy for registration

You may want to automatically assign an existing Central Governance configuration policy during the Transfer CFT registration. To do so, set the UCONF parameter cg.configuration_policy to the name of the desired policy.

uconfset id=cg.configuration_policy, value=<name_of_policy>

Optionally customize the SSL certificate Distinguished Name (DN)

To override the business certificate's Distinguished Name (DN), which is generated during the Central Governance registration or certificate renewal, set the UCONF parameter cg.certificate.business.csr_dn to the custom value. The default is O=Axway,OU=MFT,CN=%uconf:cft.full_hostname%. Remember to separate tokens by a comma.

uconfset id=cg.certificate.business.csr_dn, value='O=MyCompany,OU=MFT,CN=%uconf:cft.full_hostname%'

A best practice is to customize the certificate DN prior to registration. However, if you are customizing the certificate DN after the Transfer CFT registration, you can force an immediate renewal or wait for the automatic renewal as described in SSL certificate renewal.

Optionally customize the certificates' key length

By default, Transfer CFT generates a key length of 2048 bits for its Governance and Business certificates. Optionally you can modify these values to 4096 bits.

  • uconfset id=cg.certificate.governance.key_len, value=4096

    uconfset id=cg.certificate.business.key_len, value=4096

  • Enable Central Governance

    To enable connectivity, enter:

    uconfset id=cg.enable, value=yes

    Perform the check command to validate parameters

    Use the CFTUTIL CHECK command to validate the coherence of parameters, partners, and the Transfer CFT PKI database.

    CHECK CONTENT=BRIEF|FULL, FOUT=FileName

    Check the list in the output for errors and correct all errors before attempting registration. See also, Use the check command.

    Register or re-register

    Ensure that cft_registration_id is reset to -1. Otherwise, reset it as follows:

    CFTUTIL uconfunset id=cg.registration_id

    Start the Transfer CFT Copilot to automatically trigger registration with Central Governance. From the Central GovernanceUI, check the Product List to confirm that the registration was successful.

    For troubleshooting issues refer to Troubleshooting: Installation and registration.

    Related Links