Migrating token revocation information to DataPower API Gateway

You can use the Token Migration Utility (TMU) to migrate token revocation information from a v5 quota enforcement server (QES) to a gateway-peering cache in v10 DataPower® API Gateway.

Before you begin

Download the TMU from IBM Fix Central. The TMU includes a container image and a separate configuration file.

The TMU requires the following versions of DataPower Gateway on the source and destination servers.
System Required DataPower Gateway versions
Source

v10.5.0.0 or higher

v10.0.4.0sr1 or higher

v10.0.1.4 or higher

v2018.4.1.16 or higher

Destination

v10.5.0.4 or higher

About this task

You can use the TMU to migrate revoked access tokens, revoked refresh tokens, resource owner consent, and, optionally, revoked resource owner consent.

Token migration consists of the following stages:
  • Export QES data to a JSON file in the local directory.
  • Import QES data into v10 DataPower Gateway from the JSON file.
  • Configure a deny list in the v10 token cache.
The TMU transforms the data from QES to v10 format. It uses the DataPower Gateway REST management interface to expose the data and import it to the gateway-peering instance. When TLS is enabled in the gateway-peering instance, the TMU creates a TLS proxy and a TLS client profile to import the QES data. When TLS is not enabled, the TMU creates a TCP proxy to import the data.
Attention: Verify that the following requirements are met before you run the TMU.
  • Ensure that the DataPower Gateway REST management interface is enabled. For information about enabling the REST management interface and configuring gateway peering for DataPower API Gateway, see Configuring DataPower API Gateway.
  • Gateway peering requirements
    • The v10 gateway peering password must be defined.
    • The gateway-peering instance in DataPower Gateway for the internal token store requires that data persists across a restart to prevent data loss. Ensure that this instance is not configured to store data in memory.
  • v5 QES configuration requirements
    • Peer group mode must be disabled.
    • The listening server port must use the default value 127.0.0.1:16379.
    • The v5 QES password must be defined.
Tip:
  • The ./tmu command uses the argument --stage or -s to indicate the stage of migration to perform.
  • Use the --help argument to get information about any of the token migration stages.

Procedure

  1. Define the following fields in the config.json file. All fields must be present and defined unless otherwise noted.
    Table 1. Token migration configuration options
    Field Description
    v5-gateway-address v5 DataPower Gateway address
    v5-gateway-username v5 DataPower Gateway username
    v5-gateway-password v5 DataPower Gateway password
    v5-qes-password v5 QES password
    v5-cache-proxy-port The user-defined port on which to expose the v5 QES proxy. Ensure that this port is not in use.
    v5-cache-container-port If DataPower Gateway is deployed in Docker, the port that is exposed on the container that maps to the port defined in v5-cache-proxy-port. If DataPower Gateway is not deployed in Docker, this field can be undefined.

    When the cache container port is defined, the TMU attempts to connect to these ports, assuming that DataPower Gateway is hosted in a container. When it is not defined, the TMU connects to the cache proxy port.

    v5-rest-management-interface-port REST management interface port. If DataPower Gateway is deployed in Docker, enter the container port.
    v10-gateway-address v10 DataPower Gateway address
    v10-gateway-username v10 DataPower Gateway username
    v10-gateway-password v10 DataPower Gateway password
    v10-gwp-password v10 gateway-peering password
    v10-cache-gateway-peering-name Gateway-peering object name that is mapped to the v10 token cache. If peer group mode is enabled, ensure that the specified gateway-peering object is the primary member, not a replica.
    v10-cache-proxy-port The user-defined port on which to expose the v10 token cache proxy. Ensure that this port is not in use.
    v10-cache-container-port If DataPower Gateway is deployed in Docker, the port that is exposed on the container that maps to the port defined in v10-cache-proxy-port. If DataPower Gateway is not deployed in Docker, this field can be undefined.

    When the cache container port is defined, the TMU attempts to connect to these ports, assuming that DataPower Gateway is hosted in a container. When it is not defined, the TMU connects to the cache proxy port.

    v10-rest-management-interface-port REST management interface port. If DataPower Gateway is deployed in Docker, enter the container port.
    export-file-name File name for extracted v5 data.
    log-file-name Log file name. After any of the TMU commands are run, a log file is generated in a logs subdirectory of the TMU directory. Log files are named according to the format DATE-TIME_%log-file-name%.
    log-level Log level to filter logged messages by severity. Valid values are debug, error, or info.
    import-revoked-consent Whether to import consent revocation entries. Valid values are true or false.
  2. Start the TMU container.
  3. Copy the edited config.json file into the /home/tmu/ibm directory of the TMU container.
  4. Run the following command to export QES data to a JSON file in the local directory.
    ./tmu --stage v5-export
    The QES data is exported to a JSON file in the same directory as the TMU. The name of the exported file is specified in the export-file-name configuration field.
    Each exported entry in the file has the following fields.
    timeExport
    Unix epoch timestamp.
    value
    String value to the key in the QES.
    ttl
    Time to live of the entry in seconds.
    Important: Do not modify the entries in the export file.
  5. Run the following command to import QES data from the exported JSON file into v10 DataPower Gateway.
    ./tmu --stage v10-import
  6. Run the following command to configure a deny list in the gateway-peering instance.
    ./tmu --stage token-cache-mode-set-deny
    Attention: When the gateway-peering token cache mode is set to deny-based caching, it cannot be reset to allow-based caching.
  7. Optional: Run the following command at any time to view the cache mode configuration in the v10 token cache.
    ./tmu --stage token-cache-mode-view

What to do next

Check the log file in the logs subdirectory for errors. For information about common errors and troubleshooting steps, see Token migration errors.