Problem

• Client Application Registry (CAR) has been depreciated from API Management [7.7 Feb 2024] and later versions.
• You are using API Gateway as an OAuth 2.0 server, but not using API Manager.
• How to upgrade CAR OAuth server to API Manager.

Context

Prior to the introduction of API Manager, when API Gateway was used as an OAuth 2.0 server, the provided UI to manage the OAuth client_id and client applications was called Client Application Registry (CAR). The functionality needed for OAuth 2.0 also exists in the later API Manager UI.

Resolution

Conversion from Client Application Registry (CAR) to API Manager can be done before your upgrade to a version of API Gateway where the CAR has been deprecated.

Testing in a lower environment first is recommended, as is a full backup.

The general steps to upgrade from using CAR to using API Manager include the following:

Preparation

• Review CAR and API Manager documentation to familiarize yourself with both features.
• Confirm your license file at apigateway/conf/licenses has the "apiportal=1" flag. If not, please request an updated license that includes the API Manager feature, due to the CAR deprecation.
• Snapshot or back up your current API Gateway and Cassandra using your regular process. (One that you have tested the restore process for and are confident in.)
• Back up your current Policy Studio project and the <install location>/samples/oauth/templates, or elsewhere, if you have customized the HTML presented for CAR login / resource owner authorization.
• Verify if your current implementation has customized the policies:
  • Client App Registry Protection Policy, or
  • Polices > OAuth > Authorization Service > Login
  • or, whether you changed the port or paths at Env. Config. > Listeners > OAuth 2.0 Services
• The default user login for the CAR feature was likely 'regadmin' (from the built-in user store at Policy Studio > Env. Config. > Users and Groups > Users). If you have added additional users, or customized the user store used for the login, those users must be added to API Manager after the upgrade.
• If either the login page or process, or the user store has been customized, these changes must be understood and potentially modified or merged back into the API Manager analogue after update. (Contact Axway support if you need help).
• Review one of your Apps and associated OAuth client_id's, and take note of these to be used later.
• If your token lifetimes are long enough to make this feasible, use your application to issue a new token and then access the resource using the token.
  • After the upgrade from CAR to APIM is complete, you will access the resource using the same token as a test.
• If using a Cassandra cluster, it is very important that your Cassandra replication factors and read and write consistency settings are correct for your current setup. For example, Replication 3 and Quorum for single DC, or NetworkTopologyStrategy 3 and Local_Quorum for multi DC, and so on. (Contact Axway support if you need help).
• Because new tables will be created, the Policy Studio > Server Settings > Cassandra > Keyspace > Initial replication and Initial replication strategy fields will be read and used at first deploy for the new tables. If they are not set correctly at the first deployment, then manual update via cqlsh will be needed.

Upgrade

• Open your current CAR project in Policy Studio, go to File > 'Configure API Manager...' and select it.
  • Note, 'Configure API Manager...' should be available and 'Configure OAuth' should be greyed out.
• Follow through the options. The Cassandra hosts should already be set, so, click Next. The defaults for API Manager setting should be appropriate, but ensure to chose your starting 'apiadmin' password, then click Finish.
• If using a Cassandra single cluster or multi-DC, then KPS collections (API Server, OAuth, and API Portal) need to be set to Quorum or Local_Quorum for read and write consistency.
  • For example, in the Policy Studio tree, select Environment Configuration > Key Property Stores > API Server > Data Sources [tab] > Cassandra Storage, and click Edit.
  • Repeat this step for each KPS collection using Cassandra (for example, Key Property Stores > OAuth and then Key Property Stores > API Portal).
• Save and close your project. Deploy when ready.
• After your project is deployed to your CAR API Gateway group, the API Manager Cassandra tables will be created, and the new API Manager UI will be enabled, the old CAR UI will no longer be available. Then, you must use the 'apiadmin' user instead of 'regadmin' user.

Attention! While you are deploying your project, ensure to save off and review each instance trace log for errors with this process.

Post upgrade

• Stop and start the instance. If using multiple API Gateways in the API Manager group, perform a rolling restart.
  • Note that the token issued prior to the upgrade might not work just after the upgrade deployment. If this happens, restart the instance.
• Log into API Manager UI and go to Settings > General settings, and enable the 'Enable application scopes' option.
• View one of your Apps and OAuth client_id, and confirm that all looks correct. Note that the OAuth credentials are now on Authentication tab and not on the main App page.
• Using your application flows, test one of your prior tokens; then, issue a new token and test that.