Overview

There are multiple use cases that can demand us to modify the user registry that we set in the API Manager – the type of registry changed, or an LDAP registry already in use needs the Prefix or Suffix attributes to be updated.

Unfortunately, when at least a user is established for the existing registry, we will not be able to just add a new registry definition on the CMC User Registries menu and then to switch to it in the User Registries entry of the Settings menu. We would indeed slip into the error message “Cannot update user registry for API Manager because user(s) exist.”:

This will force us to reset the API Manager configuration and to start back with the default factory settings. But what if there are (lots of) APIs already published in Production? What if they were protected with Client ID and Client Secret? Will clients still able to consume the APIs after the API Manager reconfiguration, without having to switch to a new set of Client ID and Client Secret? And will we coherently be able to avoid distributing the new set of Client ID and Client Secret to all the developer organizations (the clients)?

This recipe allows API clients to consume seamlessly the APIs while the API Manager is reconfigured with the new user registry. It will be just required a short downtime to execute the switch-off, to let the new API Manager configuration to take over the existing one. Then, the APIs will still be there, protected with the original Client ID and Client Secret.

Configuration backup

Before resetting the API Manager configuration, the following objects must be backed-up:

• Current API Manager configuration
• Developer Portal sites
• Products and APIs

We will also need to take note of the definitions of all organizations (or provider organizations), catalogs, developer organization, apps, and subscriptions.

We are taking into account the case where the APIs are secured via credentials (Client Id and Client Secret), so it will be necessary to keep this information at hand.

The clue

Once an existing API Manager configuration is reset, the CMC console will highlight us that any of the previously existing Gateway services along with the related Gateway servers aren’t available:

 Despite this fact, the management domain defined by the API Manager on the API Gateway (DataPower) is still present – this can be easily verified from the DataPower console (we’re assuming we had only one management domain or Gateway service):

Most important, through this domain, the APIs previously published by the API Manager are still available and accessible with the original credentials (Client ID and Client Secret).

We can then plan a solution that allows developers to continue consuming the APIs with the known credentials, while in the background a new API Manager configuration is implemented, with the new user registry and a new domain (or Gateway service) on DataPower that is temporarily published on a different port with respect the original one. Subsequently, after completing the API Manager configuration, we will let the new published domain to take over the old one (switch-off).

Solution Overview

The solution described here requires cleaning the API Manager configuration for all the management components available, meaning all the Management servers belonging to the Management service in the API Connect cloud. Afterward, the API Manager is reconfigured from scratch. This solution can be applied both on single-server and in cluster topology. However, if a rollback should be needed to return to the original configuration, it would be necessary to restart from the backed up API Manager configuration, for each Management server.

Let us pick as a starting point the typical operational schema for the API publication both in single-server and cluster topology:

During the API Manager reconfiguration, the existing APIs will continue to be available without interruption (see API Old Config below). When configuring the new Gateway service, we will choose a publication port different from the default one for HTTPS communications (443), say port 444. This way, when the same APIs will be published in the new domain (or Gateway service), they will be available directly at the FQDN (or IP) of the individual Gateway server but on a different port (see API New Config, port 444 below). After restoring the developer organization, apps and subscriptions, these APIs will be protected by new credentials (Client Id and Client Secret). Subsequently, using the Developer Portal REST services, the original credentials to secure the APIs will be restored:

After successfully testing the invocation of the new published APIs, the switch-off between the new and the old Gateway service will take place:

The old Gateway service will be moved on a different port (see API Old Config, port 445). This operation will be executed using the DataPower web console, since that domain is no longer available on the API Manager CMC console. The new Gateway server will instead be moved on port 443 via the API Manager CMC console. Once verified that the solution is working properly, the old Gateway service can be deleted via the DataPower web console. We have now reproduced the original API Manager configuration, except for the user registry which has been updated according to our requirements.

Solution checklist (recipe)

The following checklist will describe the activities that implement the solution in the style of a recipe:

• API Manager configuration reset – requires the execution of the command system clean apiconfig on each Management server of the cloud.
• API Manager reconfiguration via CMC console – requires the execution of the following activities:
  • TLS profiles definition
  • New user registry definition
  • Email configuration
  • New user registry configuration
  • TLS profiles configuration
  • Developer Portal configuration (requires also trust with API Manager via SSH)
  • Restore Provider Organizations definition
  • Management service configuration
  • New Gateway service configuration
• API Manager reconfiguration via APIM console:
  • Restore Catalogs definition
  • Restore and publication of Products and APIs (can be also executed via APIC Toolkit)
  • Developer Portal site definition per each Catalog
  • Restore of Developer Organizations
• API Manager reconfiguration via Developer Portal web console:
  • Restore Apps
  • Restore Subscriptions
• API Manager reconfiguration via Developer Portal REST services:
  • Recover original credentials (Client ID/Client Secret) for the Apps
• Test APIs invocation in the new publication domain (or Gateway service)
• API Gateway reconfiguration (switch-off) via DataPower web console:
  • Change the old publication domain (old Gateway service) port to 445
• API Manager reconfiguration via CMC console:
  • Change the new Gateway service publication port to 443
• Test the solution
• API Gateway reconfiguration via DataPower web console:
  • Delete the old API publication domain (old Gateway service).

Restoring Developer Portal sites?

Once a Developer Portal site is established for a Catalog, the link from the API Manager and the Developer Portal site cannot be subsequently recovered if the API Manager configuration is reset and rebuilt. Indeed, if we clean and reconfigure the API Manager and redefine an existing Catalog, if we try to set for that Catalog the existing Developer Portal site, we get the following error message:

There is no other chance than to delete the original Developer Portal sites and to redefine them back by the APIM console from the given Catalog menu. This means that customization already applied to the existing Developer Portal sites will be lost.

Recovering the original credentials (Client ID and Client Secret) for the Applications

API Connect makes available a set of Developer Portal REST services suited to operate on Users, Products, APIs, Applications, etc. This is the related link to the Knowledge Center: https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.apirest.doc/dev_portal_apis.html

We are interested in the Application management REST service credentials:
 https://www.ibm.com/support/knowledgecenter/en/SSMNED_5.0.0/com.ibm.apic.apirest.doc/apirest_reference_topics/rest_op_portal_orgs__orgID__apps__appID__credentialsPUT.html

When invoked with PUT method, this service allows updating the credentials (Client ID and Client Secret) of a given Application. This REST service uses ids as input parameters, so it will be necessary to invoke the following sequence of REST services to reach the objective:

1. v1/portal/orgs, to get the desired Developer Organization identifier <developer-organization-id>
2. v1/portal/orgs/<developer-organization-id>/apps, to get the Application identifier <app-id> related to the desired Application, available from the Application list related to the Developer Organization specified by the identifier <developer-organization-id>
3. v1/portal/orgs/<developer-organization-id>/apps/<app-id>/credentials, to update the credentials (Client ID and Client Secret) for the Application specified by <app-id> and the Developer Organization specified by <developer-organization-id>.

These REST services require also the following information sent as http request headers:

• Context, in terms of Provider Organization and Catalog, using the header X-IBM-APIManagement-Context, in the form: X-IBM-APIManagement-Context:<provider-organization-name>.<catalog-name>
• Response format, using the header Content-Type, in the form: Content-Type:application/json
• Developer Organization Owner’s credentials, using the header Authorization with the credentials set to base64 as with Basic authentication, in the canonical form: Authorization:Basic aVHtNMZ6cm4yC3NjaGU=.

As an example, let us assume to work with the Provider Organization myOrg, Catalog myCatalog, Developer Organization myDevOrg, and Application myApp.

After connecting via SSH to the Developer Portal, let’s invoke the first mentioned REST service v1/portal/orgs. A possible output follows:

admin@s-developerportal:~$ curl -k -H “X-IBM-APIManagement-Context:myOrg.myCatalog” -H “Content-Type:application/json” -H “Authorization:Basic aWJtN5U6gm8dM3NjaGU=” https://apimanager.mycompany.com/v1/portal/orgs

[{“roles”:[“5cb59c810cf2ee801253c6ea”],”id”:”5cb59c800cf2ee801253c6e9″,”name”:”myDevOrg”, “url”:”https://apimanager.mycompany.com/v1/portal/orgs/5cb59c800cf2ee801253c6e9”,”owner”:true}]

Subsequently we invoke the second REST service, v1/portal/orgs/<developer-organization-id>/apps, using the result of the preceding service invocation. A possible output follows:

admin@s-developerportal:~$ curl -k -H “X-IBM-APIManagement-Context:myOrg.myCatalog” -H “Content-Type:application/json” -H “Authorization:Basic aWJtN5U6gm8dM3NjaGU=” https://apimanager.mycompany.com/v1/portal/orgs/5cb59c800cf2ee801253c6e9/apps

[{“type”:”PRODUCTION”,”promoteTo”:null,”id”:”5cb59e420cf2ee801253c6f3″,”name”:”myApp”, “orgID”:”5cb59c800cf2ee801253c6e9″,”public”:false,”description”:””, “credentials”:{“clientID”:”af4095a2-a069-438f-bb62-3b4715de6cb9″,”clientSecret”:”********************************************”,”description”:”Default”, “url”:”https://apimanager.mycompany.com/v1/portal/orgs/5cb59c800cf2ee801253c6e9/apps/ 5cb59e420cf2ee801253c6f3/credentials”},”appCredentials”:[{“id”:”5cb59e420cf2ee801253c6f4″,”description”:”Default”, “url”:”https://apimanager.mycompany.com/v1/portal/orgs/5cb59c800cf2ee801253c6e9/apps/ 5cb59e420cf2ee801253c6f3/credentials/5cb59e420cf2ee801253c6f4″,”clientID”:”af4095a2-a069-438f-bb62-3b4715de6cb9″,”clientSecret”:”********************************************”}], “enabled”:true,”state”:”ACTIVE”,”imageURL”:null, “appImageURL”:”https://developerportal.mycompany.com/myOrg/myCatalog/sites/all/modules/ibm_apim/images/icons/ app/app_14.png”,”oauthRedirectURI”:””,”certificate”:null,”createdAt”:”2019-04-16T09:20:02.237+0000″,”updatedAt”:”2019-04-16T09:20:02.237+0000″, “url”:”https://apimanager.mycompany.com/v1/portal/orgs/5cb59c800cf2ee801253c6e9/apps/ 5cb59e420cf2ee801253c6f3”}]

We can now invoke the third REST service, v1/portal/orgs/<developer-organization-id>/apps/<app-id>/credentials, using the results obtained from the preceding services. However, in addition, it is required to input the Client Secret with SHA256 base64 hash format.

Assuming the textual form of the Client Secret to be: jM2kG1eI5aF4aQ4qW1hH7wT4hK5sG3oB6sL2pV0rW8aR4rG8bT, executing the SHA256 base64 hash conversion can be accomplished via the following Linux command:

admin@s-developerportal:~$ printf “jM2kG1eI5aF4aQ4qW1hH7wT4hK5sG3oB6sL2pV0rW8aR4rG8bT” | shasum -a 256 | cut -d ” ” -f 1 | xxd -r -p | base64

ZFGcgrXetduo6x41snstOV4HBITAej8gXODfGkJPaoE=

Now we can invoke the third REST service:

admin@s-developerportal:~$ curl -k -i -H “X-IBM-APIManagement-Context:myOrg.myCatalog” -H “Content-Type:application/json” -H “Authorization:Basic aWJtN5U6gm8dM3NjaGU=” -d ‘{“clientID”: “0ec9010b-11d5-4459-8e9f-2695459c9ed5”, “clientSecret”: “ZFGcgrXetduo6x41snstOV4HBITAej8gXODfGkJPaoE=”, “description”: “The original ClientSecret”}’ -X PUT https://apimanager.mycompany.com/v1/portal/orgs/5cb59c800cf2ee801253c6e9/apps/5cb59e420cf2ee801253c6f3/credentials

HTTP/1.1 200 Connection established

HTTP/1.1 200 OK

Date: Tue, 16 Apr 2019 15:31:33 GMT

Server: Apache

Strict-Transport-Security: max-age=31536000; includeSubdomains;

Access-Control-Allow-Origin: *

Access-Control-Allow-Credentials: true

Pragma: No-cache

Cache-Control: no-cache

Expires: Thu, 01 Jan 1970 00:00:00 UTC

Content-Location: https://s-apimanager.mycompany.com/v1/portal/orgs/5cb59c800cf2ee801253c6e9/apps/5cb59e420cf2ee801253c6f3/credentials

Content-Type: application/json

X-Content-Type-Options: nosniff

X-XSS-Protection: 1; mode=block

X-Processed-By: 99cf3d9a68baac5182f507e677f9f800a87c9470

Vary: Accept-Encoding

Transfer-Encoding: chunked

{“clientID”:”0ec9010b-11d5-4459-8e9f-2695459c9ed5″,”clientSecret”:”********************************************”,”description”:”The original ClientSecret”,”url”:”https://s-apimanager.mycompany.com/v1/portal/orgs/5cb59c800cf2ee801253c6e9/apps/5cb59e420cf2ee801253c6f3/credentials”}

The application myApp has now the desired credentials.

We are hence able to assign to an Application, which was redefined after an API Manager reconfiguration, the same credentials it had in the initial API Manager configuration. As the outcome, clients can continue to invoke the APIs included in the plans subscribed by that Application using the original credentials.

Co-author of this recipe

Marco Zobbi (marco_zobbi@it.ibm.com) is a Hybrid Cloud Solution Architect and the co-author of this recipe.