Proxy to support both Api Key and OAuth2/OIDC authentication

Hi,

We have an existing proxy which has ApiKey authentication rule however, recently we introduced OAuth2/OIDC to our existing proxy as authentication and planning to deprecate ApiKey over the period of time.

The question here is what's the best way to migrate the proxy clients to new route?

Option 1 :

Add the new authentication (OAuth2/OIDC) via a new version such as */v2/* so, whomever the client is calling the new proxy will go with new auth.

Option 2:

Modify the existing proxy and add the condition to validate with ApiKey is header has the ApiKey element , if header has the Authorization then verify with OAuth/OIDC. This will be done with condition in PreFlow step.

We are thinking of below options, please let me know if there is any possible best way available apart from the above two.

Solved Solved
1 3 608
1 ACCEPTED SOLUTION

Option 1 seems the cleanest way to go. Easy to document, easy to implement. Then you will have to monitor the analytics to see which clients are migrating to the /v2 and which clients remain on v1. I predict that persuading developers to build new code to support the OAuth flow will be a challenge. Just human nature. They will reason: it works now, why would I invest more time to change it? Unless you have a firm, clearly communicated deprecation schedule, they'll be unmotivated. Even with a "hard deadline" approach, in which you tell developers that the APIKey verification will cease to work on a specific date, you will cause some churn with developers. Some will just not update their apps, and the apps will stop working.

One thing you could do, to add some additional gradually-increasing incentive is to use a Delay step (https://github.com/DinoChiesa/ApigeeEdge-Java-Delay) in the old /v1 proxy, so that any call handled by the v1 (with APIKey verification) will exhibit slower response time. And you could increase the delay time, week by week. This week , the proxy might introduce a delay of 100ms, next week 125ms, and the following week 150ms. As time goes on this will become very noticeable. IT will get people's attention. Users will complain, and developers will have to respond.

Option 2 is also a possibility, and it means that developers do not need to modify the URL paths. But I think the condition as you described it would be too simple to accomplish your aims.

With the condition as you described it, either APIKey or Token is fine, and there's no preference.

But as I understand it, you want to encourage developers to migrate from APIKey to Token verification. And certainly you don't want new devs, and new apps, to be able to use the older "deprecated" API Key verification. Therefore you will need to insert some validation conditions in the proxy. For example, check to see if there is an APIKey header, if so execute VerifyApiKey, and if that succeeds, then examine the custom attributes on the client app to determine if the app is permitted to use VerifyApiKey. If not, then RaiseFault.

And again you'll need some additional incentive to move developers along. Maybe you could use the delay again here.

I think it's easier to explain option 1 to developers, and for that reason I like it better.

View solution in original post

3 REPLIES 3

Option 1 seems the cleanest way to go. Easy to document, easy to implement. Then you will have to monitor the analytics to see which clients are migrating to the /v2 and which clients remain on v1. I predict that persuading developers to build new code to support the OAuth flow will be a challenge. Just human nature. They will reason: it works now, why would I invest more time to change it? Unless you have a firm, clearly communicated deprecation schedule, they'll be unmotivated. Even with a "hard deadline" approach, in which you tell developers that the APIKey verification will cease to work on a specific date, you will cause some churn with developers. Some will just not update their apps, and the apps will stop working.

One thing you could do, to add some additional gradually-increasing incentive is to use a Delay step (https://github.com/DinoChiesa/ApigeeEdge-Java-Delay) in the old /v1 proxy, so that any call handled by the v1 (with APIKey verification) will exhibit slower response time. And you could increase the delay time, week by week. This week , the proxy might introduce a delay of 100ms, next week 125ms, and the following week 150ms. As time goes on this will become very noticeable. IT will get people's attention. Users will complain, and developers will have to respond.

Option 2 is also a possibility, and it means that developers do not need to modify the URL paths. But I think the condition as you described it would be too simple to accomplish your aims.

With the condition as you described it, either APIKey or Token is fine, and there's no preference.

But as I understand it, you want to encourage developers to migrate from APIKey to Token verification. And certainly you don't want new devs, and new apps, to be able to use the older "deprecated" API Key verification. Therefore you will need to insert some validation conditions in the proxy. For example, check to see if there is an APIKey header, if so execute VerifyApiKey, and if that succeeds, then examine the custom attributes on the client app to determine if the app is permitted to use VerifyApiKey. If not, then RaiseFault.

And again you'll need some additional incentive to move developers along. Maybe you could use the delay again here.

I think it's easier to explain option 1 to developers, and for that reason I like it better.

Thanks Dino for the detailed explanation. I agreed that Option 1 to be as well a cleaner solution. I missed to explain one point regarding Option 1 is that we will make the changes in proxy layer and not in the target application because there is no changes in the API contract apart from the token authentication. I believe this approach is fine, Do you this have any comments on this approach?

Yes, that sounds right to me.

If you have OpenAPI Specs that describe the interface exposed by the proxy (or its containing product) then you will need to update the security element in those specifications, to convert from APIKey security to token security. But I guess you knew that.