Allow Roles/Privileges

[orubel]

See issue #1411

So this has been brought up several times, this is now an #owasp #api #security #top10 issue, this was bropught up at DEFCON.

The issue is simple:

If Sally if COMPANYA has multiple ROLES, there has to be a way in OpenAPI to handle request/response data per endpoint by ROLE.

The token will send both ROLES and you will check based upon ROLE WITH HIGHEST PRIVILEGE to determine what to REQUEST and what to return in RESPONSE.

You have NO WAY TO DO THIS. Same with API DOCS in SWAGGER

SWAGGER will show one set of request/response data REGARDLESS OF ROLE.

This creates excessive traffic, shows people endpoints that they do not have access to and potentially the wrong data per their roles.

Their is an ARCHITECTURAL SOLUTION where you can through separate machines at each separate role but this is expensive and wasteful (processor/hr wise) especially when one can declare request/response data PER ROLE :

				"create": {
                                        ...,
					"REQUEST": {
						"permitAll":["firstName","oauthProvider","username","accountLocked","password","lastName","oauthId","avatarUrl","email"],
                                               "ROLE_ADMIN": ["passwordExpired","accountExpired","enabled"]
					},
					"RESPONSE": {
						"permitAll":["id"],
                                                "ROLE_ADMIN": ["version","passwordExpired","accountExpired","enabled"]
					}
				},

...with the 'permitAll concatenated upon everything in 'ROLE' but being a catchall for non-listed roles.

I do this currently and this allows me to 👍

• synchronize on-the-fly between all services (using webhooks from central server)
• have apidocs and apis all be based upon users roles at all times.
• have data be accurate per request/response and in compliance with the OWASP security

[earth2marsh]

The specification does not have any opinion on whether the viewer of the OpenAPI document has rights to use the service. It only describes the interface for interacting with that service.

You might be able to leverage specification extensions to describe a permissions model on top of the interface's functional description, but that would be outside the scope of the specification. Such an approach would then require tooling to render an OpenAPI document (for example a well-known URL such as api.example.com/openapi.yaml) that reflected an apparent interface description that was specific to a role of the caller. The authorization accompanying that request could then return an OpenAPI document that reflected the access rights that were specific to the authorized caller and no more.

I'm not aware of any open source tools that provide such utility, but I'm interested in hearing of any examples.

[orubel]

Beapi currently does this. Wanted to use OpenAPI (and still do) but OpenAPI doesn't meet the needs of providing a default 'anonymous role' (or non-role) and user roles so data can be assigned per role.

We ended up having to create a custom schema so that we could synchronize across all services

You can see example schema here

I'm not aware of any open source tools that provide such utility...

This is not something that is covered by any plugin or extension for OpenAPI.

[LikeLakers2]

Hi! Not a contributor here, but I want to offer my thoughts on this.

It seems like you're misunderstanding what OpenAPI is. OpenAPI isn't a piece of software like BeAPI is -- it's a specification. It's an agreement on how several pieces of data should be organized with each other. OpenAPI, in particular, is a specification that can be used to document the layout of a API -- that is, what endpoints there are, what parameters they need, and so on -- for end users (and sometimes even yourself) to consume and make a library out of. OpenAPI by itself is not a means to make an API; however, it is entirely possible to make your own program that will take in an OpenAPI document, and spit out code for your API.

That said, if you still want to use OpenAPI to document your API, and you still want it to describe which roles can access which endpoints/endpoint parameters, I would suggest using Specification Extensions. These would allow you to define additional pieces of data -- in the format of your choosing -- that can then be parsed by your API and API users to determine which endpoints can be access by which users.

[orubel]

OpenAPI is state. It is used at the API gateway to describe the endpoint in order to route based on security protocols since the gateway handles security. Wherein do you believe I am getting 'confused'?

The OpenAPI doc is generated by the API app (AFTER a reboot of the app) wherein the endpoint definitions EXIST and said doc is then used by API Gateway and other services to share this state. This is by no means synchronization and the API Gateway (which is supposed to handle security) is not checking the roles against the endpoints using the OpenApi document.

These either calls for a duplication of security in the API App (at which point gateways are redundant) or for OpenApi to fix the doc.

Also 'specification Extensions' are a secondary definition. These are not part of the primary definition but a tacked on afterthought. Security should be primary and a primary part of STATE.

If Openapi is being supplied for API Gateways where they want securty to be handled, then they need to integrate security ROLES as part of data checking (see above).

Either that or directly state that they are not intended to be used as part of the gateway for checking endpoints.

You cant have your cake and eat it to: you either need to supply a way or state that OpenApi isn't intended for security at the gateway

[orubel]

If you want to think of it from the perspective of SWAGGER and API DOC generation, imagine Sally has a ROLE_USER in her token when requesting the apidocs (or even anonymous... both work). Should the docs generated for her be the EXACT SAME AS FOR ROLE_ADMIN??? Of course not... but they are in Swagger and OpenAPI because they are not checking ROLES and to show the different request/response data or even if they have rights to request those endpoints.

OpenAPI is responsible for telling the gateway these rules and THIS is a BIG ONE!

Especially since ALOT of people handle their security at the gateway. If you are only using OpenAPI to check the endpoints but not specifying the data per endpoint by each role, you are stating one one of tweo things:

• either all ROLES request/return the data the EXACT SAME WAY (highly unlikely that admins and users do this)
• or it is a free for all and no data checking is occurring as the OpenAPI document CANNOT PROVIDE IT!

This bug/issue is asking OpenAPI to start providing it so as to be in compliance with what gateqways are doing, what owasp api security has listed as security risks as is a basic need of all production api's in existence.

[LikeLakers2]

OpenAPI is responsible for telling the gateway these rules and THIS is a BIG ONE!

It's not, though. OpenAPI was never meant to be a means to configure a API. OpenAPI is only meant to be used to describe the API's routes to the user -- this was already mentioned within the first reply in this issue:

It only describes the interface for interacting with that service.

I'm really not sure where you're getting this idea that OpenAPI is for configuring a gateway/API service.

My suggestions to you would be these:

1. Continue using BeAPI, since it appears to be working for you as you want.
   or
2. Use Specification Extensions for this purpose

[orubel]

Hmmm... where do I get these ideas, probably from YOUR DOCUMENTATION and MEMBERS of the OpenAPI Initiative ...

• https://app.swaggerhub.com/help/integrations/amazon-api-gateway
• https://app.swaggerhub.com/help/integrations/azure-api-management
• https://docs.apigee.com/api-platform/tutorials/create-api-proxy-openapi-spec
• https://blogs.mulesoft.com/dev/api-dev/open-api-raml-better-together/
• https://support.mashery.com/blog/read/New_Feature_Import_Swagger_specification

And they are not using heavily modified versions of OpenApi (ie specification extensions)

Openapi actually PROMOTES it for these purposes! So if it isn't meant for it, why does Smartbear and the OpenApi initiative promote it for these purposes?? Why is there documentation for it?? Why do member sites have it?

Is Smartbears and the OpenAPI foundation now officially stating that OpenAPI is not supposed to be used with gateways???

[orubel]

Excuse me for being blunt but this is coming across as a 'cake and eat it too' response.

• you have members (who give you revenue) who are using it in their api gateways and you even have it in your documentation
• but you are not supplying a secure solution for using it in api gateways (as I pointed out)

So you either have to say (as you did above) :

• that all your members are wrong for using it in their api gateways
• OR there is an underlying security issue with using it in api gateways?

Do you see the issue now? (have only been trying to get your team to resolve this for 3 years now)

[LikeLakers2]

First off, I feel the need to clarify that I'm not a member of the OAI. I'm just some dude who watches this repository because I like seeing what changes. Please don't take my responses as word-of-god -- I'm just trying to figure out what's being said, and maybe help you understand.

Openapi actually PROMOTES it for these purposes! So if it isn't meant for it, why does Smartbear and the OpenApi initiative promote it for these purposes?? Why is there documentation for it?? Why do member sites have it?

I couldn't tell you why member sites have it (maybe they want to seem hip and innovative or the like?), but I wouldn't personally pin the blame on OAI for something a member site has done. What they do with the OpenAPI specification is their own doing, in my opinion.

However, I'm curious -- I've never seen OAI promote it for those purposes. Where do they promote it for this?

[orubel]

I'm just trying to figure out what's being said, and maybe help you understand.

Well thank you. As someone who rewrote the API Pattern for distributed architecture and created the API chaining pattern, its always nice to have someone who just lurks explain architectural call flow and complex security to me. Maybe we can avoid talk DOWN to each other???

If you want to know why too, mark the ticket up. This is an issue that has been ignored since 2017 (#1411), was brought up by DEFCON this year and is now being pointed out by the OWASP API SECURITY TOP10.

So hopefully, we will see traction.

As for who you are, you are hiding behind a pseudonym but I suspect I already know who you are. You wouldn't happen to be related to Darrel would you Mike? ;)

[darrelmiller]

@LikeLakers2 Apologies for you getting dragged into this. Unfortunately I learned several years ago that I am unsuccessful at having a constructive conversation with Owen. Hence why I haven't tried to engage.

• Users of OpenAPI descriptions can choose to use to them to drive infrastructure if they wish. Most API gateways I am aware of simply use OpenAPI descriptions to assist in performing internal configuration. I have yet to find an API gateway that is limited in functionality to what OpenAPI descriptions provide.

• OpenAPI allows attaching roles/scopes to operations. This is the same security capability offered by OAuth2 and Bearer tokens https://tools.ietf.org/html/rfc6750

• Users are free to place OpenAPI descriptions behind authorization mechanisms that do security trimming.

• Users are free to define extensions to correlate roles/scopes with schema elements. This is not a feature that has had significant community support to consider standardizing. This lack of support for this feature does not create a security vulnerability.

I believe this addresses the technical issues in this thread and so I am closing this issue before it deteriorates any further.