This post targets to explain the changes happened in communication flows, with decoupling the KeyManager. If you have any confusions on why certain configurations are done differently from 1.9.0 onwards, this post may also help you to clear out those doubts.
Changes in Renewing Tokens
Before 1.9.0 when renewing access tokens what happened was, Store would call renewAccessToken operation in KeyManager , which would call /revoke and /token APIs respectively to revoke the existing token and to obtain a new one. Locations of the token and revoke endpoint are defined in APIKeyManager section. Revoke endpoint location has an element for itself. But the token endpoint location is constructed by taking the ServerUrl of APIKeyManager section and removing services part and then, appending /oauth2/token (or the value specified in TokenEndPointName ). This is why when creating a distributed setup, RevokeAPIURL in KM profile should be pointed to GW profile. You might wonder why KM has to call GW, because what the revoke API in GW does is routing the request back to KM, so why the extra hop. That’s because when the revoke request goes through the RevokeAPI, it performs certain checks and removes the revoked token from the cache.
From 1.9.0 onwards instead of Store invoking a Service hosted on KM profile, directly calls Revoke and Token APIs. So in the new releases,RevokeAPIURL should be correctly configured in Store profile.
Before KM decoupling
After KM decoupling
One drastic change you might notice in configs while going from 1.8.0 to 1.9.0 would be the addition of a new config section called, APIKeyValidator. What is this and why has this been introduced. If you are not going to use a Third Party KeyManager then you don’t need to worry about this, you can think of it as a renaming of APIKeyManager section. KeyValidator is not an entirely new thing that came up with the Key Manager decoupling. It was there from the beginning, but then because APIM was tightly bound to one component which performed all token related activities, there wasn’t a need to make a distinction between the KeyManager and the KeyValidator. But now a new term is needed to avoid confusions, hence the name APIKeyValidator.
Conceptually a KeyManager is responsible for Managing OAuth Clients, issuing/managing tokens, responding to validity inquiries of tokens etc. It’s purely involved in performing token related tasks. But API Manager needs more than a pure KeyManager to authorize an invocation. Since the APIs are grouped under Applications and there’s a notion of subscriptions, apart from the validity of a token (whether a token is active or not), validity of a subscription (whether the application to which token is issued is subscribed to the API being invoked) too needs to be assessed. But determining the validity of a subscription is something specific to API Manager. To do that certain tables of API Manager should be accessed. Even the token/OAuth Client managing part can be delegated to a different server, validating subscriptions cannot be. That’s why a different server profile is needed to perform API Manager specific validations. APIKeyValidator’s responsibilities would be to Check if the Application is Subscribed to the API, check the authorization level of the token against that of the resource (e.g. whether token is of type Application and security level of the resource is Application or lower), validating the scopes of the resource and generating the JWT.
During an API Invocation Gateway only talks with KeyValidator. It gives all details about the invocation and asks about its the validity from KeyValidator. KeyValidator would talk to KeyManager (which can be either the in built one or a third party one) to determine the validity of the token and to get the consumer key of the OAuth Client. Once the KeyValidator gets the consumer key, it will perform all other API Manager specific validations.
So if you are using a different Key Manager (OAuth Provider), while distributing the components, it would be sufficient if you correctly configure APIKeyValidator section in the Gateway. KeyValidator has to talk to KeyManager so that’s why you have to uncomment and configure APIKeyManager section in KeyValidator.
Another node that needs to talk to KeyManager is the Store node. While creating OAuth clients, Store would directly consume APIs exposed by KeyManager. If ResourceRegistration is to be used, then Publisher too would have to know the location of KeyManager.
Before KeyManager decoupling
After KeyManager decoupling
Does KeyValidator need to run on it’s own node/JVM?
No it doesn’t. Often you don’t need to worry about the existence of a KeyValidator. When you don’t use a third party KeyManager (OAuth Provider), the in built KeyManager would perform the tasks of a KeyValidator.
Even when you are using a different KeyManager, you can get the Gateway to do KeyValidator’s tasks, if Gateway accessing the DBs is not a concern. While doing a deployment, certain organisation policies may require you to Deploy GW in a highly secured NW from where DBs can’t be accessed. Only a such a scenario would require KeyValidator to run on a separate node/JVM. In such a deployment, KeyValidator would sit inside a secured NW which is permitted to access DBs and the Gateway would make a service call to KeyValidator when needed to authorize a call.