Scope management in API Gateway

[Chris Bertagnolli]

Looking at a broad use of OAuth access tokens for delegates API access. Still at kind of documentation/investigation stage with the API Gateway itself and a little concerned with scope management.

According to the documentation: "The scope is a space-separated list of values that apply to OAuth 2.0 clients only and limit access for OAuth tokens. A client is initially registered with a set of scope values."  

As I interpret that, I have to essentially hard code scope lists across multiple clients, am I reading that correct? If that is true, that makes using API Gateway far less attractive than other products.

Is there any better documentation of recommend best practices for scope management with the OAuth Toolkit? 

Logically I want to have application groups, assign that application XYZ scopes (w/ some description), register clients to that application and assign them certain scopes from the list. That doesn't appear to be doable here with the OTK management GUI and assertions (which also appear to rely on hard coded values).

[Zhijun He]

Hello Chris,
As per my understanding, the API is to access the resource, the scope means the scope of the resource, ie. what resource (api) the oauth client can access.
Therefore, if an API (resource) is open to everyone, you don't need to validate the scope, if the API/resource is for certain oauth client only, then you can validate the scope.
Setting the scope for an oauth client will define what API(resource) this oauth client can access.

You may find more details from oauth RFC documents, or other oauth documents. The gateway product document will not have those knowledges, same as the product document will not have knowledge about xml, http, etc.

Regards,
Mark

[Chris Bertagnolli]

Yes, I understand the use of scopes themselves and all the various RFCs associated with OAuth/OIDC. What I'm looking for specifically is how the API Gateway OTK - which is the Authorization Server - manages scopes across potentially hundreds of clients; this is application design specific and not within the realm of the OAuth framework RFCs.

As I read the documentation it appears it assigned a client scopes based on a space separated list (free form text???). That sounds like a client with a hard coded list of "scopes" which would not be maintainable. If I want to remove a scope from all clients my only recourse is to sort through every client that has this hard coded value and remove it from them; additionally I also then have to manually track which API Gateway security policies use that and update them as well. I should be able to go into a central repository of scopes assigned to a resource and simply delete it.

Hoping it's just a documentation verbiage / interpretation issue. I'll try to get some time to actually install the OTK and see first hand, but right now we're still just investigating high level which product options to consider. 

I'd prefer it to be the API Gateway :).

[Chris Bertagnolli]

An example using another popular product. Within the Authorization Server I can add scopes + descriptions centrally, then create an application group and define a Web API with X scopes. Then I add clients to this application groups, select the scopes (from the configured list), and now can easily manage them.

If I want to remove a scope completely, go to central location and delete it and it's now gone from every client. Or change the scope name/description.

But that product also has some drawbacks too.

Is that possible in the GW? Or can I rename a scope if needed and have it propagate to all clients?

I'm trying to get the best of both worlds within the API Gateway. The biggest hang up I have at the moment is how scopes are managed from resource defined scope -> assigning to client -> enforcing at API GW policy. Unless I'm really misunderstanding the documentation or there's some other recommendation from Broadcom on how to handle the concept of a resource -> defined scopes -> client assigned scoped it seemed like it was pretty manual?

[Zhijun He]

Dear Chris,
As per my understanding, here is how it works on gateway system.
1. on design stage,
 -- define what scopes will be accepted by an API  -- scopesA   
 -- define oauth clients and their scopes. -- scopesB
2. on implement stage,
-- register oauth clients on /oauth/manager with the scopes
-- in the API policy, validate the token and scope (with OTK Require OAuth 2.0 Token assertion) 
3. at run time,
the client authorises against OTK and retrieves the access token (associated to an oauth client and scopesB) and call the API with the token --> when executing API policy and validate the token/scope, if token is valid and scopesA is a sub set of scopesB, validation successful and continue, otherwise the API rejects the request and returns error.

To modify scopesB, you can do it on /oauth/manager.
To modify scopesA, you need to modify policy of API
( you're right scopesA and scopesB are kind of hard coded, but I think it's expected as you define the permission of this API, and the oauth client needs to be granted to the same permission to use this API, I don't think they're expected to be changed at run time.)


Regards,
Mark

[Chris Bertagnolli]

Thanks, and yes that's our understanding. But hard coding "lists" of scopes is not maintainable. That alone will almost sway at least my recommendation on which of the various products to use.

Will see how it goes but if the only way to do scope management is having to manually track them via like an Excel sheet or create a custom web application makes the overall cost of the API GW to continue to grow (which is already pretty high). It's not a great design that makes using API GW versus the various other products out there less attractive; especially since I could still easily enforce OAuth + scopes within the API GW just calling another Authorization Servers introspection endpoint or just validating a JWT within a simple policy fragment.

I'll install the OTK and play around with it. But honestly it's a tough sell. It would be good for Broadcom to spend some more time on the overall functional design here to allow better management of clients, scopes and applications.

[Zhijun He]

Well, we do have a tool which can do what you want, the Developer Portal,
https://techdocs.broadcom.com/content/broadcom/techdocs/us/en/ca-enterprise-software/layer7-api-management/api-developer-portal/4-4.html

Regards,
Mark

[Chris Bertagnolli]

As great as that looks, that's another added cost to already high cost of ownership. It's also much more involved than we'd require Day 1; I'd like to crawl before I try to walk and certainly before running.

Scope management is a basic functional requirement for an Authorization Server and should not require yet more cost to support. We're not talking about an overly complicated setup, just a basic centralized way to manage scopes across hundreds of clients with one place to manage API groups -> scope -> clients assigned the scopes. That should be a baseline for any product offering an Authorization Server - not using hard coded lists for a production service.

I'll add the Developer Portal to the list of associated costs and considerations if API GW is chosen. It's certainly going to be a detriment to the side-by-side comparison unfortunately ...I love my API GW and would definitely rather use it but also have to consider total cost of ownership compared to what is needed.