Migrating OAuth Providers and OAuth secured APIs

You can migrate v5 OAuth Providers and OAuth secured APIs to your v10 API Connect deployment.

In v5 OAuth Providers are a specialized type of API that are published within products. In v10 OAuth Providers are first class objects that are directly published in the provider organization. This is applicable for both DataPower Gateway (v5-compatible) and DataPower API Gateway.

Also, v10 adds tight coupling between the API using OAuth and the OAuth provider object. Hence an API using OAuth security must link to the corresponding OAuth Provider object. For a review of how API Connect v10 uses OAuth Providers, see OAuth Provider overview.

The API Connect Migration Utility (AMU) migrates all OAuth Provider APIs from v5 to the first-class OAuth provider objects on both DataPower Gateway (v5-compatible) and DataPower API Gateway.

In addition, the AMU uses logic to determine which OAuth provider is used by a given API and populates it in the newly added field x-ibm-configuration of API security definitions. If the AMU is unable to find a match between an API using OAuth and the OAuth provider, it prints out error messages. See Common errors with OAuth Providers.

  • To ensure that APIs that use OAuth security definitions are mapped to the corresponding OAuth Provider APIs in v10, make sure that either the Authorization URL or the Token URL defined in OAuth Security Definitions of APIs that use OAuth correctly point to the base path of the OAuth Provider API. Note that the AMU uses logic to map Consumer APIs to Provider APIs, and adds x-ibm-oauth-provider in the OAuth Security Definition of the consumer API.
  • To verify whether OAuth Provider APIs are migrated correctly, ensure that all the APIs that use OAuth Security Definition have the new field x-ibm-oauth-provider added. Check the value of that field and make sure it points to a correct OAuth Provider resource object that was created and configured in the catalog to which the API is published.
  • As mentioned earlier, in v5 OAuth Providers are a specialized type of API that are published within products. In v10 OAuth Providers are instead first class objects that are directly published in the provider organization, and are not APIs that are published within products. Because of this, it is possible that you may have some v5 products that only contained OAuth Provider APIs. Since these products do not contain any Open API definitions in v10, they will not be published as all products in v10 must contain at least one Open API definition.
Note: Conflicting OAuth provider names or base paths are not migrated. If the migration utility encounters conflicting names or base paths for OAuth providers, the provider is not migrated.

Migrating OAuth token revocation information

In v5, token revocation could be enabled either using native token management system (TMS) or using external TMS. For migration to v10:

  • Native TMS migration
    • DataPower Gateway (v5-compatible)

      After setting up a v10 DataPower Gateway instance, follow these steps to configure the v10 DataPower Gateway quota enforcement server (QES) to use the same QES on both v5 and v5-compatible. You must configure the QES and verify that it is enabled and functional before migrating from v5 to v10. For more details about configuring the QES, see the DataPower Gateway documentation topic Configuring the quota enforcement server.

      1. Log into the graphical interface of the DataPower Gateway instance in the default domain.
      2. Cluster the v5 MPGW QES with the v10 DataPower Gateway QES.
        1. In DataPower Gateway, navigate to Objects > System Settings > Quota Enforcement Server.
        2. Specify the password alias, data storage location, and the server and monitor port numbers.

          If your v10 DataPower Gateway is a Docker instance, configure the QES to store data in memory. For more information about RAID and Docker, see the DataPower Gateway documentation topic RAID and a DataPower Docker image.

        3. Enable Peer group mode.
        4. Specify the IP address of the DataPower Gateway.

          The IP address can be the IP address on any interface of the current appliance and must be accessible by other peers in the peer group.

        5. Specify the IP addresses of the v5-compatible gateways to add them as peers.

          The appliance connects to each peer in the order in which the peers are added in the list.

        6. Apply and save the configuration.
      3. As a test, revoke a token on the v5 MPGW server.

        Revocation data will replicate to v10 DataPower Gateway QES.

      4. Migrate the v5 APIs to the v10 DataPower Gateway QES.
      5. Send a request to the v10 DataPower Gateway QES with previously revoked token, which should fail as expected.

        The expected failure indicates that the APIs were migrated and revocation data was replicated.

    • DataPower API Gateway

      When migrating to API Gateway, QES is not used for native token management and revocation. A new set of objects called Gateway Peering objects are created on API Gateway. This means that any existing revocation information on QES is not available for API Gateway.