Configuring DataPower API Gateway

Configure the DataPower® API Gateway to prepare for registration with the API Connect Management server.

Before you begin

  • These instructions are for DataPower API Gateway deployments in a non-Kubernetes environment. Do not use these instructions if you installed API Connect on Kubernetes, with your DataPower API Gateway Service also in the Kubernetes environment. To review deployment scenarios, see Deploying DataPower Gateway virtual appliance.
  • Ensure you have installed a version of DataPower API Gateway that is compatible with the version of the API Connect Management server. See Installing DataPower Gateway.
  • A shared certificate and private key is used for securing the communication between the API Connect Management server and the gateway. See Generating keys and certificates in the appropriate version of the DataPower documentation for instructions on how to create them with the DataPower tools.
  • Ensure that the time zone for the DataPower API Gateway is set to UTC.

About this task

  • These instructions provide the basic steps for configuring a gateway service with a single gateway server. The lowest-level configuration objects are created first, then used in other configuration objects.
  • Adding gateways to configure a peering environment is similar to creating the first gateway, and is recommended for resiliency in a production environment. A minimum of three gateway servers in a gateway service is recommended for high availability. See Gateway peering in the DataPower documentation for more information about configuring additional gateways for peering. See Providing the gateway service to API Connect in the DataPower documentation for more details about the DataPower settings and procedures.

Procedure

To configure a DataPower API Gateway to communicate with API Connect, complete the following steps:

Note: Use these instructions only for DataPower API Gateway . If you are configuring DataPower Gateway (v5 compatible) see Configuring DataPower Gateway (v5 compatible).

  1. Open the DataPower WebGUI interface.
    Most of the configuration procedure is done in the DataPower WebGUI interface, not in the Blueprint Console.
  2. Optional: Enable the XML management interface in the default domain.

    The XML management interface is optional for DataPower API Gateway. If enabled, this interface allows you to send status and configuration requests to the DataPower appliance through a standard SOAP interface, using SOAP messages.

    1. Search for XML management interface in the navigation search bar, and select it.
    2. Set the Administrative state to enabled.
    3. You can specify a different port number if you do not want to use the default of 5550.
    4. Select Apply to make the changes
    5. Save changes to the default domain by selecting Save Configuration.
  3. Optional: Enable the REST management interface in the default domain.

    The REST management interface is required if you want to enable to the Trace feature in the assembly Test tab in the API Manager.

    1. Search for REST management interface in the navigation search bar, and select it.
    2. Set the Administrative state to enabled.
    3. You can specify a different port number if you do not want to use the default of 5554.
    4. Select Apply to make the changes
    5. Save changes to the default domain by selecting Save Configuration.
  4. Create an application domain.
    This domain receives your traffic. The name of the DataPower domain where you configure the API Connect Gateway Service must be the same on each DataPower Gateway.
    1. Search for Application domain in the navigation search bar, and select it.
    2. Select Add to create the application domain.
    3. Enter a unique name for your domain.
    4. Ensure that enabled is selected for the Administrative state.
    5. Ensure that the default domain is listed in the Visible application domain list.
    6. Select Apply.
    7. Change to your new application domain by selecting Domain in the menu bar, and selecting the domain that you created.
    8. Select Save changes and switch domains.
      All of the remaining steps on the DataPower gateway must be done in the application domain that you created.
    9. Save changes to the domain by selecting Save Configuration.
  5. Ensure that your deployment includes an NTP server to synchronize time between each of the DataPower Gateways.
    See Managing the NTP service in the DataPower documentation.
  6. Ensure that you have set a unique System Identifier for each v10 DataPower gateway. See Initializing the DataPower Gateway in the DataPower documentation.
  7. Create a self-signed certificate and private key to be used to protect the traffic between the management server and the API gateway service process. You can generate a certificate and private key using DataPower or by using other tools, such as OpenSSL. See Generating keys and certificates in the appropriate version of the DataPower documentation for instructions on how to create a crypto key with the DataPower tools.
  8. Upload your private crypto key file to the domain.
    1. Search for Crypto key in the navigation search bar, and select it.
    2. Select Add to create a key object.
    3. Create a unique name for the key object in the Name field.
    4. Select Upload....
    5. Browse for the key file (which must be a .pem or .p12 file) and select it.
    6. If you want to rename it, enter a new name for the file.
    7. Select Upload to move it to the server in the cert:// folder.
    8. Select Apply to save the changes.
  9. Upload your crypto certificate file to the domain.
    Note: If your certificate is signed by an Intermediate CA, you must include the entire chain in a single key file (either .pem or .p12) for uploading.
    1. Search for Crypto certificate in the navigation search bar, and select it.
    2. Select Add to create a certificate object.
    3. Create a unique name for the certificate object in the Name field.
    4. Select Upload....
    5. Browse for the key file (which must be a .pem or .p12 file) and select it.
    6. If you want to rename it, enter a new name for the file.
    7. Select Upload to move it to the server in the cert:// folder.
    8. Select Apply to save the changes.
  10. Associate the Crypto key with the Crypto certificate by setting the Identification credential.
    1. Search for Crypto Identification Credentials in the navigation search bar, and select it.
    2. Select Add.
    3. Enter a name for your credential.
    4. Ensure that the Administrative state has a value of enabled.
    5. In the Crypto Key field, select the name of the key object that you created from the drop-down menu.
    6. In the Certificate object field, select the name of the certificate object that you created from the drop-down menu.
    7. Select Apply to commit your changes.
  11. Create your TLS Client profile.
    1. Search for TLS Client profile in the navigation search bar, and select it.
    2. Select Add to create a client profile.
    3. Create a unique name for the profile in the Name field.
    4. Select your Identification credential from the drop-down list.
    5. Ensure that the value of Validate server certificate is set to off.
    6. Ensure that the value of Use SNI is set to on.
    7. Select Apply to save the changes.
  12. Create your TLS Server profile.
    1. Search for TLS Server Profile in the navigation search bar, and select it.
    2. Select Add to create a server profile.
    3. Create a unique name for the profile in the Name field.
    4. Select your Identification credential from the drop-down list.
    5. Ensure that the value of Request client authentication is set to off.

      Disabling the request for client authentication for the TLS client profile and the validation of server certificates for the TLS server profile disables security for the ease of configuring the gateway. To enable the secure communication using mutual TLS between IBM API Connect and Gateway, see Binding a TLS server profile to a gateway service.

      If mTLS is disabled it is recommended to use JWT application layer security instead. See Enable JWT instead of mTLS.

    6. Select Apply to save the changes.
  13. Define a configuration sequence.

    The configuration sequence specifies how DataPower implements the APIs that are defined in API Connect.

    1. Search for Configuration sequence in the navigation search bar, and select it.
    2. Select Add.
    3. Enter a name for your configuration sequence.

      The name apic-config is not allowed because it is already used internally.

    4. Ensure that the Administrative state has a value of enabled.
    5. Ensure that the value in the Location profiles field is set to local:///
      This is the default value, so you might not need to change it.
    6. Select the Access profile.

      For instructions on creating access profiles, see Configuring the access profile for a configuration sequence in the appropriate version of the DataPower documentation.

    7. Change the value of the Configuration execution interval field to 3000.
      The other fields can retain their default settings.
    8. Select Apply to commit your changes.
  14. Configure your gateway peering object for the API Connect Gateway Service.
    This step is required when you set up a peer group of gateways, even if there is only a single gateway server in the gateway service.
    1. Search for Gateway peering in the navigation search bar, and select it.
    2. Select Add.
    3. Enter a unique name for your gateway peering object.
    4. Ensure that the Administrative state has a value of enabled.
    5. Select a local address for the communications among the members of the peer group.
    6. Select a local port for the communication.
      You can use the default value of 16380.
    7. Select a monitor port for the communication.
      You can use the default value of 26380.
    8. Because this procedure uses only one gateway, ensure that Peer group mode is not selected.
    9. Clear the Enable TLS check box. TLS is not needed for a single peer.
    10. Set the Persistence location value to Memory for either physical DataPower appliance or virtual DataPower appliance.
    11. Select Apply to commit your changes.
  15. Configure your gateway peering object for rate limit information.
    1. Search for Gateway peering in the navigation search bar, and select it.
    2. Select Add.
    3. Enter a unique name for your gateway peering object.
    4. Ensure that the Administrative state has a value of enabled.
    5. Select a local address for the communications among the members of the peer group.
    6. Select a local port for the communication.
      Use a unique port, different than the ports used for communication by other gateway peering objects.
    7. Select a monitor port for the communication.
      Use a unique port, different than the ports used for monitoring by other gateway peering objects.
    8. Because this procedure uses only one gateway, ensure that Peer group mode is not selected.
    9. Clear the Enable TLS check box. TLS is not needed for a single peer.
    10. Set the Persistence location value to Memory for either physical DataPower appliance or virtual DataPower appliance.
    11. Select Apply to commit your changes.
  16. Optional: If you are using the ratelimit module described in the DataPower documentation, configure your gateway peering object for GatewayScript rate limiting information.
    1. Search for Gateway peering in the navigation search bar, and select it.
    2. Select Add.
    3. Enter a unique name for your gateway peering object.
    4. Ensure that the Administrative state has a value of enabled.
    5. Select a local address for the communications among the members of the peer group.
    6. Select a local port for the communication.
      Use a unique port, different than the ports used for communication by other gateway peering objects.
    7. Select a monitor port for the communication.
      Use a unique port, different than the ports used for monitoring by other gateway peering objects.
    8. Because this procedure uses only one gateway, ensure that Peer group mode is not selected.
    9. Clear the Enable TLS check box. TLS is not needed for a single peer.
    10. Set the Persistence location value to Memory for either physical DataPower appliance or virtual DataPower appliance.
    11. Select Apply to commit your changes.
  17. Configure your gateway peering object for subscription information.
    1. Search for Gateway peering in the navigation search bar, and select it.
    2. Select Add.
    3. Enter a unique name for your gateway peering object.
    4. Ensure that the Administrative state has a value of enabled.
    5. Select a local address for the communications among the members of the peer group.
    6. Select a local port for the communication.
      Use a unique port, different than the ports used for communication by other gateway peering objects.
    7. Select a monitor port for the communication.
      Use a unique port, different than the ports used for monitoring by other gateway peering objects.
    8. Because this procedure uses only one gateway, ensure that Peer group mode is not selected.
    9. Clear the Enable TLS check box. TLS is not needed for a single peer.
    10. Set the Persistence location value to Memory for either physical DataPower appliance or virtual DataPower appliance.
    11. Select Apply to commit your changes.
  18. Configure the gateway peering object for the API probe.

    In order for API Connect to receive trace data in the Test tab's debugger, the DataPower API Gateway must be configured to support the API probe.

    1. Search for Gateway peering in the navigation search bar, and select it.
    2. Select Add.
    3. Enter a unique name for your gateway peering object.
    4. Ensure that the Administrative state has a value of enabled.
    5. Select a local address for the communications among the members of the peer group.
    6. Select a local port for the communication.
      Use a unique port, different than the ports used for communication by other gateway peering objects.
    7. Select a monitor port for the communication.
      Use a unique port, different than the ports used for monitoring by other gateway peering objects.
    8. Because this procedure uses only one gateway, ensure that Peer group mode is not selected.
    9. Clear the Enable TLS check box. TLS is not needed for a single peer.
    10. Set the Persistence location value to Memory for either physical DataPower appliance or virtual DataPower appliance.
    11. Select Apply to commit your changes.
  19. Configure the gateway peering manager.
    1. Search for Gateway Peering Manager in the navigation search bar, and select it.
    2. Set the Administrative state to enabled.
    3. In the pull-down menu next to API Connect Gateway Service, select the gateway peering object configured in Step 14 for the API Connect Gateway Service.
    4. In the pull-down menu next to Rate Limit, select the gateway peering object configured in Step 15 for rate limit information.
    5. In the pull-down menu next to Subscription, select the gateway peering object configured in Step 17 for subscription.
    6. In the pull-down menu next to API Probe, select the gateway peering object that you configured in Step 18 for the API probe.
    7. If you are using the ratelimit module described in the DataPower documentation, then for Gateway rate limiting, select the gateway peering object that you configured in Step 16 for rate limit information.
    8. Select Apply to commit your changes.
  20. Configure the API probe settings object.
    1. Search for API probe settings in the navigation search bar, and select it.
    2. Set the Administrative state to enabled.
    3. Set the maximum number of records to 1000.
    4. Set the expiration to 60 minutes.
    5. In the pull-down menu next to Gateway Peering, select the gateway peering object that you configured in Step 18 for the API probe.
    6. Select Apply to commit your changes.
  21. Set the API Connect Gateway service to define the communication interface with the API Connect Management server and for API transactions.
    1. Search for API Connect Gateway service in the navigation search bar, and select it.
    2. Ensure that the Administrative state is set to enabled.
    3. In the Local address field, enter the IP address of the DataPower gateway to which you want the traffic from the API Connect Management server to be sent.
    4. Specify a value for Local port. You can use the default value of 3000, or specify a different port value.
      Note: The Local port specifies the port through which API Connect connects to manage the API Connect Gateway Service. Use this port when you configure a Gateway Service on API Connect. Beyond this port, the gateway service uses two additional consecutive ports after the defined local port to bind to a loopback address. Therefore, you must ensure that there are no conflicts on all three consecutive ports that start from the defined local port.
    5. In the TLS client field drop-down list, select the name of the TLS client profile that you created.
    6. In the TLS server field drop-down list, select the name of the TLS server profile that you created.
    7. In the API gateway address field, enter the IP address for the DataPower gateway to which you want the API traffic sent.
    8. Use the default port value of 9443 for the API gateway port.
      If the port is not being used by another service, you can also change it to port 443 if you want API transactions to be sent to the default port for HTTPS.
    9. For DataPower API Gateway, set the Gateway Peering to (none).
      When no gateway peering object is configured for the DataPower API Gateway, the peering configuration defined in the Gateway Peering Manager configuration is used.
    10. Select whether you want the DataPower Gateway (v5 compatible) or the DataPower API Gateway.
      When the option is selected, it enables the registration of a DataPower Gateway (v5 compatible) gateway. Clear it to enable a DataPower API Gateway.
  22. Optional: Enable JWT security instead of mTLS for communication from management to gateway. JWT security provides application layer security and can be used instead of mTLS when load-balancers are located between subsystems that require TLS termination. For more information about JWT security, see Enable JWT instead of mTLS.
    To enable JWT and disable mTLS on the gateway appliance, see Configuring the API Connect gateway service in the DataPower documentation. The JWKS URL required to enable JWT security can be found in the management subsystem settings:
    apicup subsys get <management subsystem>
    
    ...
    jwks-url     https://appliance1.apic.acme.com/api/cloud/oauth2/certs  JWKS URL for Portal and Analytics subsystems to validate JWT -- this is unsettable and is generated based on the platform-api endpoint 
    ...
  23. Register the gateway service in the API Connect Cloud Manager console:
    1. Open the API Connect Cloud Manager console.
    2. Navigate to Configure Topology.
    3. Select Register Service.
    4. Select DataPower API Gateway for the DataPower API Gateway.
    5. Add a title, name, and summary for the gateway connection.
    6. Optional: Configure the OAuth Shared Secret.
      This setting allows OAuth tokens to be shared across multiple gateway services.
    7. Enter one of the following values in the API Invocation Endpoint field:
      • IP address of the load balancer for the API transactions
      • IP address or host name of one of the gateways
      For example:https://192.0.2.0:9443/
    8. Enter the one of the following values in the Management Endpoint field:
      • IP address of the load balancer for the management server traffic set to port 3000
      • IP address or hostname of one of the gateways
      For example:https://192.0.2.0:3000/
  24. Select the default TLS Client Profile
  25. Optional: Configure Server Name Indication (SNI) profiles.
    SNI profiles allow different TLS certificates to be used for API transaction requests from different host names.
  26. Enable logging for the gateway.
    1. Use the CLI to configure the following log target in the API Connect application domain:
      switch domain <apiconnect_domain>
      configure terminal
      logging target gwd-log
      type file
      format text
      timestamp zulu
      size 50000
      local-file logtemp:///gwd-log.log
      event apic-gw-service debug
      exit
      apic-gw-service;admin-state disabled;exit
      apic-gw-service;admin-state enabled;exit
      write mem
      exit
    2. Repeat this set for every gateway server in the cluster.