Allow Roles/Privileges

[orubel]

endpoints need to have ROLES and Privileges associated with them. Since tokens and security are always part of the architecture and will be included at all points of the architecture (proxy, MQ, API server), they will also need to be checked at all places the Open Api is checked.

You need to provide something similar to 'I/O State that can be shared and syncronized:

        "URI": {
            "list":{
             	"METHOD":"GET",
            	"DESCRIPTION":"List Hook",
            	"ROLES":["ROLE_ADMIN","ROLE_ARCH"],
            	"BATCH":["ROLE_ADMIN","ROLE_ARCH"],
                "REQUEST": {
                    "permitAll":[]
                },
                "RESPONSE": {
                	"permitAll":["id","version","user","name","url","format","service"]
                }
            },

[darrelmiller]

Operations that are secured using OAuth2 can have scopes assigned to them. This is similar to privileges, if I understand your model correctly. Having pre-defined roles might be something that is useful for services to define but I'm not sure it is in scope of the OpenAPI spec.

[darrelmiller]

Luckily there is an extension mechanism in OpenAPI that allows you to add on whatever metadata you wish in order to support your choice of framework for building distributed applications.

And you are correct that roles/privileges are data just like HTTP methods. The difference is that roles and privileges are not standardized in the HTTP specification. We are not in the business of creating a meta data description for a generalized distributed application framework. We are in the business of describing HTTP APIs using the semantics described by the HTTP specification and those related to it.

You have our encouragement and support to build a better distributed computing framework and use OpenAPI and extensions to drive it. If in the future it becomes a ubiquitous standard, as HTTP is, then we will be happy to update the core spec to follow it.

[darrelmiller]

So, does this work for you?

openapi: 3.0.0
paths:
  /show:
    get:
      description: Show hooks
      x-roles: ["ROLE_ADMIN","ROLE_ARCH"]
      x-batch: ["ROLE_ADMIN","ROLE_ARCH"]
      x-request-permitAll: []
      x-request-ROLE_ADMIN: ["user_id"]
      responses:
        200:
          description: List of hooks
          x-permitAll: ["id","version","user","name","url","format","service"]

Perhaps you can show how this is represented in Blueprint or RAML because to be honest, I really don't understand the semantics of the example you are giving.

[webron]

Those are not header definitions, those are Specification Extensions as defined by the spec. @darrelmiller simply translated your example to something that can be represented with OAS3.

[webron]

Not really sure how we got to talk about frontend now.

[webron]

No, it's just a way to extend a specification. It can be used by the front end, back end, nothing at all, everything. It's just extra metadata that's not directly supported by the specification. We've seen various examples of those out there.

As for what you're suggesting, that won't get in before we solve the issue of filtering fields from models in general. It also seems that you're trying to describe a very specific implementation and this is not a general solution used across by various API producers out there (unlike known authorization schemes). As @darrelmiller mentioned before, this does not make it a good candidate to be incorporated directly into the specification.

[webron]

Again, no idea what you're referring to.

[nelz9999]

@orubel Thank you for making this community an unsafe place for people.

I've been amazed at how level-headed the team has been trying to work with you, and now you've opted to be just plain insulting.

I understand that it is frequently challenging to make oneself understood, I have that problem often. But the onus is on you to be understandable when proposing enhancements.

[handrews]

Since when is someone upvoting 'Again, no idea what you're referring to' level headed. That's upvoting passive aggression.

I am the one who upvoted that (I just checked to make sure no one else had). I did so because I am also confused and wanted to indicate that more people who are reading this thread may be confused. I did not have anything worth saying on the actual thread so I did not say anything. And my name is on it either way, so I am accountable whether I post a comment or not.

And in that vein, if such an upvote was against community standards or preferences, then I apologize for not considering that beforehand. I'm leaving it there so the conversation continues to make sense, but I am also happy to remove it or address any problems in whatever way is preferred by the project. Also, I am fine with the admins deleting this comment if they wish as it does not contribute to the primary discussion.

However, since my upvote was called out, I felt that I should explain my intent, even if it did not land as intended.

[darrelmiller]

@handrews Your upvote of a comment declaring a failure to understand is perfectly acceptable response in my opinion. In an online world it is never easy to convey sentiment, therefore we must "assume the best" when interpreting every comment.

@orubel We've had this conversation before. I am convinced you have a lot to contribute to this community, but you need to find a way to communicate your ideas in language that your target audience can grok. I have repeatedly tried to parse what you are saying and I have failed. That may be completely my fault, but we both lose if you cannot convey your ideas successfully.

What is not acceptable is making belittling comments such as "This may be a bit over your head". Everyone in this community is held to a higher standard than that.

I'm going to close this issue so that this whole thread can be relegated to the past. If you wish to start a fresh one about how you feel an authorization framework could be layered on top of OpenAPI, you are welcome to do so. However, before you do so, could you spend a bit more time familiarizing yourself with how OpenAPI works, as your comments on the x- extensions seem to indicate that you have misunderstood what they are.

[webron]

I stepped away from the computer for a while, and got back to this.

@handrews while may seem biased, there's nothing wrong with your upvote nor your comment. I do wish you didn't have to write the comment, but completely understand why you felt the need to do so.

There's something to be said about code of conduct and how people treat each other in a community. In fact, we're working on formalizing and adding a code of conduct to this projects to set some basic expectations.

As a community, we all make mistakes, some more severe than others. I'd be the first to admit of making such mistakes and will probably make them again.

@orubel - you were jumping to conclusions with regard to what was suggested to you. You assumed you understand what we're talking about, and went to completely wrong directions. So yes, when we're talking about the ability to declare model field filtering inside the spec, and you jump to talk about specific development languages (even though the spec is language-agnostic), you should expect people to not follow. My question wasn't passive-aggressive. Given that you repeatedly jumped between things, I thought it was pretty clear that it's difficult to follow.

You obviously also didn't take time to read the spec and see what it offers. This is based on your suggestions and reactions to our suggestions. Now, you can claim that we didn't take the time to read the ideas you provided in the link that you provided. You'd be right, except it is you who are trying to introduce something new to this spec, and not the other way around. As such, if you bring up an idea, which we very much appreciate, it is on you to explain it. Sure, I'd go and read the link at some point, but maybe I don't have time to do that right now (and I don't). You want to continue the discussion? That's fine. Take the time to make sure your message is clear.

You are not doing us a favor by suggesting new features. If you want to help the community, then do it. Our (the TSC's) job is to go through feature suggestions, read feedback from users, try to make proposals ourselves and decide whether it fits and makes sense to put into the spec based on some criteria. It is not our job to be experts in all-things-API.

Now, as much as I'd rather we all be nice, I don't see that as a requirement. I don't mind when people provide terse responses that may seem rude. I don't mind when people challenge my opinions/suggestions (and yes, I've been wrong numerous times). However, there are lines that should not be crossed. and you crossed it. I'm sorry if you don't see, but it's obvious that others on this thread did. This is not because your comment was directed at me (because, let's face it, you don't even know me to be able to make such a comment). I would have closed the ticket just like @darrelmiller did, if it were directed to anyone else.

I had a hard time deciding whether to write this at all or let it go. However, I believe there's room to take a clear stance on these things. All of us who work here, whether the TSC or the community itself, do so voluntarily and there's absolutely no reason to accept such interactions.

I'm going to do something I generally avoid doing, and lock this thread. I do encourage people to think about these things, and fully accept not everyone is going to agree with what was said, by either side. However, further active discussion here may lead to more toxicity which should be avoided.

If anyone wants to bring up the same issue at the original post and have a productive discussion, please file a new ticket and we can start over.