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.

[orubel]

It should be. At RestFest, I pointed this out as a shortcoming of the OpenAPI project and how it fails in a distributed architecture as a result because it can fall out of sync, escalate privileges, etc.

Allowing privileges to be set (even permitAll) allows for a framework for that data. Not even having a framework means their is a severe hole in OpenAPI in which data associated with endpoints is not being set.

Roles/Privileges are associated with endpoints; they are data as much as 'Get, Put, Post, Delete' or even the path (ie 'get/post'). But by not having this, you are not consolidating the I/O data that needs to be synchronized at the PROXY, MQ, API Server, etc.

Thus you are helping to create an architectural cross cutting concern.
https://developers.redhat.com/blog/2017/10/12/new-api-pattern/

[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.

[orubel]

It doesn't need to be standardized. It's just data. You merely pass the roles. This is something API Blueprint and RAML are already doing and have incorporated.

For example:
"show": {
"METHOD":"GET",
"DESCRIPTION":"Show Hooks",
"ROLES":["ROLE_ADMIN","ROLE_ARCH"],
"BATCH":["ROLE_ADMIN","ROLE_ARCH"],
"REQUEST": {
"permitAll":[]
"ROLE_ADMIN":["user_id"]
},
"RESPONSE": {
"permitAll":["id","version","user","name","url","format","service"]
}
},

The above example shows upon REQUEST, 'permitAll' states users do not need to send an ID (because it will use the id from their token) but 'ROLE_ADMIN' states those with that role need to send a user_id (even if it is their own) to do this lookup.

This way this one CACHED resource can be use different ways depending on the ROLE without changing the functionality.

And this data can be shared and synchronized in all services in the architecture thus avoiding the architectural cross cutting concern and guaranteeing 100% uptime.

[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.

[orubel]

No. The point is to have a single file in which all data can be SYNCHRONIZED for the endpoints. Data separate from function. In this, you are defining 'headers'. Headers do not always transfer (see 'redirect'). This data needs to be the same and synchronized across all services that share the I/O (request/response). If you send via the header, you can EASILY push bad data that doesn't synchronize with the 'central version of truth' which in this case is the API Server (where the request/response meet). The DATA associated with the endpoints may not sync with the data being pushing with the headers. You need ONE SINGLE version of truth that can be synchronized to all services. So if OpenAPI intends to be that DATA, it needs to act like it. Right now as is, it acts like a centralized architecture approach... not a distributed approach. Because it cannot be synchronized, it does not secure its endpoints... it still pushes the architectural cross cutting concern in the original API pattern rather than trying to separate DATA from FUNCTION.

…

_________________ The main problem is that you are basing your assumption on the fact that you can 'push through' the data linearly with the request. But the 'central version of truth' is at the endpoints in the API service. So if you attempt to 'push' bad headers/data from api gateway to api service to MQ, etc, they will either get rejected or possibly elevate privileges (depending on how the functionality works). EX You are pushing the Data like so: [API Gateway] >> [API Service] >> [MQ] This is the way the request and response works but NOT how we synchronize the data from the endpoints. We synchronize the data from the endpoints like we do neurons in a neural network EX [API Gateway] << [API Service] >> [MQ] Thus we synchronize from the point of truth and all data for the endpoints stay in sync every time they change. What you are proposing above continues to exacerbate the issue of the API Pattern as a Centralized Architecture Pattern being used in Distributed Architectures.

[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.

[orubel]

@webron My apologies. Thats right. I'm thinking xref and this is for frontend javascript usage.

Still, you wouldn't need a frontend specific designation since this wouldn't be checking ROLES on the frontend; frontend is final output once roles have been checked

Feel free to correct me if I am wrong again. ;)

[webron]

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

[orubel]

@webron Also keep in mind, just as you allow for one cached resource to be requested different ways through doifferent ROLES, you will also want to return it different ways via the ROLE as well

"REQUEST": {
"permitAll":[]
"ROLE_ADMIN":["user_id"]
},
"RESPONSE": {
"permitAll":["id","version","name","url","format","service"]
"ROLE_ADMIN":["user"]
}
},

Above implies everyone gets returned ["id","version","name","url","format","service"] but only ROLE_ADMIN gets returned 'user'

This allows for ONE OBJECT/RESOURCE to be requested/returned a variety of ways and to built functionality only ONE WAY (ie grab,cache, parse object). ROLE merely tells you:

• who has access
• what data to expect
• what data to return from cached object.

[orubel]

@webron The 'x-variable' specification is commonly used for passing variables in javascript is it not??? I have never seen this anywhere else. Isn't that a defined mime-type
https://www.npmjs.com/package/mime

[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.

[orubel]

@webron Ok well I've never had to use it until Node. Python, Ruby, Java, Perl, PHP don't need this

I would have to say, you are choosing the delivery mechanism for the end user rather than just defining data; if you want the platform to remain generic, don't do that. Let the end user choose the delivery mechanism.

A generic platform leaves the options open for people to implement.

[webron]

Again, no idea what you're referring to.

[orubel]

@webron I'm doing my best to explain, bear with me.
@handrews nice community you have here. Way to built it up

Above in your declaration, you are stating this has to be used as a mimetype and declared using the naming convention:

  x-roles, x-batch, x-request-permitAll, x-request-ROLE_ADMIN

Should there be overlap, they do not have options.
Should they not wish to use a mime-type, they do not have options.
Should they wish to transfer data using the default framework/language methodology, they don't have the option.

You are forcing the delivery mechanism for the data upon them.

Does that make more sense?

With the following:
"ROLES":["ROLE_ADMIN","ROLE_ARCH"],
"BATCH":["ROLE_ADMIN","ROLE_ARCH"],
"REQUEST": {
"permitAll":[]
"ROLE_ADMIN":["user_id"]
},

All thats being stated is:

• these are the declared role data
• this is the request data associated the the role data
• this is the response data associated with the role data

There is no formatting declared like you have. I don't declare JSON, XML or a MIME-TYPE; that is functionality/formatting... not data.