CA API Gateway 9.1

9.4 9.1

Configure GMU and Gateways for Migration

This topic describes how to configure the Gateway Migration Utility (GMU) and the gateway for a successful migration.
gateway92
This topic describes how to configure the Gateway Migration Utility (GMU) and the
CA API Gateway
 for a successful migration.
3
Configuration at a Glance
Configuring Gateways and GMU for migrations involves:
  • Publishing the REST Management service on Gateways
  • Establishing server trust and mutual authentication between GMU and Gateways through the migration Administrator
GMU_config_overview
GMU_config_overview
Configure GMU and Gateways for Migration
The following tasks require:
  • Administrator privileges 
  • Experience configuring a 
    API Gateway
GMUtest99
GMUtest99
Step 1: Configure Gateways for Migration
Publish the REST Management Service
Publishing the REST Management service is required for new implementations.
Republishing the REST Management service is highly recommended for existing implementations to take advantage of these features:
  • The new 
    restman.request.message.maxSize
     
    cluster property supports large migrations and controls the maximum request message size to the default REST Management Service. If you do not republish, migrations can fail using the existing
    io.xmlPartMaxBytes
     property, which is not adequate. (The cluster property
    io.xmlPartMaxBytes
     is a separate property and has no affect on the REST Management Service.)
  • Support for mutual authentication
  1. On the source 
    API Gateway
    , start Policy Manager.
  2. Select
    Tasks > Services and APIs > Publish Internal Service
    .
  3. Select 
    Gateway REST Management Service
     and accept the default (or enter the appropriate Routing URI).
    A wildcard is required at the end of a URI for example:
    /restman/<optionalServiceName>/*
  4. Click 
    Finish
     and verify that the service is published.
  5. Repeat steps 1-4 on target 
    API Gateway
    s.
  6. Access the REST Management API documentation:
    https://<
    GatewayHostName
    >:<
    port
    >/<
    GatewayRESTMANRoutingURI
    >/1.0/doc/home.html
    Wildcards are not supported in the URI.
Create Migration Administrator Users
The best practice is to create separate migration Administrator users. Because migration Administrators are authenticated using certificates, they could be locked out of the Policy Manager if the certificates are lost. Separating regular Administrator from migration Administrators ensures that you always have a user who can log in to Policy Manager. Although losing a certificate is recoverable, it requires help from CA Support. 
  1. On the source Gateway, log in to Policy Manager.
  2. Select
    Tasks > Users and Authentication >
    Create Internal User
     and enter information for your migration Administrator user. Be sure to select
    Define Additional Properties
    .
    The migration Administrators that you create in this step are mapped to certificates in a later step.
  3. In the user Properties dialog, select the 
    Roles
     tab and then click 
    Add
    .
  4. Select the
    Administrator
     role and then click 
    Add
    .
  5. Click
    OK
     to close the Properties dialog.
  6. Repeat steps 2-5 on any target Gateway that is involved in the migration.
Generate GMU Client Certificate and Private Key
The following instructions apply only to
CA API Gateway
s with a software keystore. For Gateways configured with a HSM (a hardware keystore), use OpenSSL.
To ensure the strongest security (mutual authentication), GMU should use a client certificate to authenticate itself to every 
API Gateway
 that is involved in migrations. GMU also supports these less secure methods:
  • Basic SSL authentication with encoded passwords
  • Basic SSL authentication with plaintext passwords (not recommended)
To generate a self-signed pkcs12 file using Policy Manager, follow these steps (or use openssl):
  1. On any Gateway with a default software keystore
    , log in to the Policy Manager.
  2. Go to: 
    Tasks
    > Certificates, Keys, and Secrets >
    Manage Private Keys
    .
  3. Click 
    Create
    .
  4. Enter an alias and click 
    Create
    .
    The alias must match the migration Administrator that you created in the previous step, "Create Migration Administrator Users".
  5. Double-click the private key in the list.
  6. Click 
    Export Key
    , optionally specify a password, and save the certificate and private key in the pkcs12 file.
  7. Move the pkcs12 file into a folder for use with GMU commands (for example, 
    --clientCert gmu.p12
    ).
  8. Click 
    View Certificate
    , click 
    Export
    , and save the certificate file. 
  9. Record the location of the certificate file (.pem format). (You need it in the next step to add the certificate to the Internal identity Providers.)
  10. (Optional). Delete the private key; it is not needed on the 
    API Gateway
    .
Map Migration Administrators to GMU Client Certificate
  1. On the source 
    API Gateway
    , log in to Policy Manager, click the 
    Identity Providers
     tab.
  2. Under 
    Identity Providers
    , right-click 
    Internal Identity Provider
     and select 
    Search Identity Provider
    .
  3. Double-click the migration Administrator.
  4. Select the 
    Certificate
     tab, click 
    Import
    .
  5. In the 
    Add Certificate
     Wizard, select 
    Import from a File
    , and import the certificate file (created in step 8 in the previous step). 
  6. Click 
    Browse
     to find your certificate and complete the wizard.
  7. Repeat steps 1-6 on target 
    API Gateway
    s.
Step 2: Configure GMU
Download GMU 
  1. Verify that the GMU computer meets requirements for operation.
  2. Log in to: CA Support.
  3. Select
    Download Management
     and search for "
    ca api gateway
    ".
  4. Select your Gateway product from the results that appear. A list of DVD images is displayed.
  5. Download the
    CA API Gateway Development Tools
     image and extract the image to a directory.
  6. Locate the file
    GatewayMigrationUtility-x.x.xx
     and extract its contents.
  7. Configure Java environment variables.
    Windows
    : Java SDK/JRE bin directory must be set on the PATH or JAVA_HOME environment variable, or specified using the --jdk argument.
    Linux/Unix
    : Java SDK/JRE bin directory must be set on the PATH, JAVA_HOME, or SSG_JAVA_HOME environment variable, or specified using the --jdk argument.
Establish Server Trust
GMU must establish trust with migration Gateways using certificates. Follow these steps to add the source and target Gateway certificates to the GMU JDK trust store. You can skip this step if the JDK trust store already has the Certificate Authority (CA) that signs these server certificates. 
Example: Linux
  1. On the source Gateway, log in to Policy Manager.
  2. Go to: 
    Tasks > Certificates, Keys, and Secrets > Manage Private Keys
    .
  3. Double-click the default 
    ssl
     private key ("S" in the last column).
  4. Click 
    View Certificate
    .
  5. On the 
    General
     tab, click 
    Export, 
    and save the file.
  6. On the computer running GMU, verify that JAVA_HOME is configured.
  7. Using the Java keytool, add the certificate to the JDK trust store.
    Example
    : 
    JAVA_HOME is configured
    $JAVA_HOME/bin/keytool -importcert -alias <
    ssgcert_alias
    > -file <
    path to certificate file
    > -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass <
    trust_store_password
    >
    Tip:
     If you see an error stating that a file or directory is not found, try removing "/jre" from the JAVA_HOME path shown above.
    The default password for <
    trust_store_password
    > is 'changeit'
  8. Repeat steps 1-7 on target Gateways.

Content feedback and comments