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 Error messages and warnings from archive:unpack.
- 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 that 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.
- Because v10 OAuth providers are first-class objects rather than APIs as in v5, the application authentication feature is not available to v10 OAuth providers migrated from v5.
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)
If you had configured native token revocation, then you would have configured Quota enforcement peering group objects on v5 to synchronize between gateway servers. When migrating to v5-compatible, a QES peering group can contain QES peers from both v5 Multi-Protocol Gateway Service (MPGW) and v10 DataPower Gateway, so the revocation information is retained.
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.
- Log into the graphical interface of the DataPower Gateway instance in the default domain.
- Cluster the v5 MPGW QES with the v10 DataPower Gateway QES.
- In DataPower Gateway, navigate to .
- 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.
- Enable Peer group mode.
- 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.
- 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.
- Apply and save the configuration.
- As a test, revoke a token on the v5 MPGW server.
Revocation data will replicate to v10 DataPower Gateway QES.
- Migrate the v5 APIs to the v10 DataPower Gateway QES.
- 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 DataPower API Gateway, QES is not used for native token management and revocation. Instead, you can migrate token revocation information from a v5 QES to a gateway-peering cache in v10 DataPower API Gateway. For information, see Migrating token revocation information to DataPower API Gateway.
- DataPower Gateway (v5-compatible)