Security metadata strawman

[mmccool]

This is a strawman for how to specify security metadata in a TD.
Right now the details of individual mechanisms are not given, just an overall example.

[mkovatsc]

Please see #73 for my input.

I would recommend:

• basic for username/password in general
• bearer and pop instead of oauth2 (would fit in line with apikey)

Maybe @id would be a good placeholder for now? It serves as ID and does not occupy id for security only.

[mmccool]

There is some related discussion here: w3c/wot-scripting-api#91

[ereshetova]

One comment with regards to using array of security elements from example:

"form": [
{
"href": "coaps://mylamp.example.com:5683/toggle",
"mediaType": "application/json"
"security": ["acl","key"]
},

So, I guess in the same way we should be able to specify the credentials required for example to access some intermediate proxy and end device's method or action? Like in the example we had before if we have a device that specifies some access control on its toggle interface (for example bearer token) and that device is behind a proxy that requires some other authentication method and credential?

[mmccool]

@mkovatsc Thanks for the suggestions. I was mimicing the OpenAPI spec but upon reviewing HTTP authentication I realized OAuth2.0 is handled by bearer tokens in HTTP so your suggestion has merit. There is a whole set of vocabulary we can develop here, and we indeed probably will end up reusing common terms like "bearer", "token", "basic", "key", etc. in multiple schemes.

Regarding id vs @id, I need guidance from someone who knows JSON-LD better than I do. How can I name something and refer to it from somewhere else in the same file? Note though this is optional. It's redundant but you could just restate the configuration in each form. That would get verbose and error-prone quickly, though.

[ereshetova]

TODO: We may want "read" access (eg the "GET" method) on a property to have different
(for example, weaker) security than "write" access (eg the "POST" and "PUT" methods).

I think this is important to address since one would imagine it to be pretty important for many use cases.
Or does it mean that they should be define as separate properties? As "lightStatus" (only gives you read) and "lightToggle" allows changing the status.

[mmccool]

@ereshetova I haven't thought about proxies much but they do show up in http authentication for instance, where there are specific header options and challenges/responses for endpoint vs proxy authentication. I think maybe a flag in the security configuration saying it is for the proxy and not the endpoint would work. Then you could just declare and use both configs in one form; one applies to the endpoint, one to the proxy. As you say, it is another justification for using an array here.

I'll add an example...

[mmccool]

@ereshetova I think the "read vs write" security can be handled by having multiple forms, one with "method": "http:get" and one with "method": "http:post" or whatever. I need to go look at the protocol binding spec again to see if that is permitted and if so I will try to come up with an example.

[mmccool]

Also @mkovatsc, yes, I need to incorporate what you did in the link you mentioned. I should have started there but was working backwards from OpenAPI and OCF. I'll thrash this out tomorrow...

[ereshetova]

+- "bearer": bearer token (to discuss: stand-alone possible?)

I think stand-alone (not as part of OAuth 2.0) is also possible at least in OpenAPI 3.0: https://swagger.io/docs/specification/authentication/bearer-authentication/

[ereshetova]

+- "jwt": JSON Web Token (to discuss: also under HTTP, but... what about CoAP, etc?)

To me JWT is a format to represent authentication token, not authentication method. For example bearer token can be in a form of JWT. It is confusing if it is listed as one of "security types"

[ereshetova]

Another note: do we want to allow "OR"-style access control? For example saying that you can access a Thing's method either using API key or authenticated using OAuth? It might be useful for some scenarios and gives flexibility.

Actually it seems this has pretty advanced OR/AND controls (see Using Multiple Authentication Types):

https://swagger.io/docs/specification/authentication/

Not sure if we need it to be so advanced, but at least this is an example on how it can be done.

[ereshetova]

Also, I found the concept of "Scopes" from here useful, might be smth to think about if we support OAuth & OpenID: https://swagger.io/docs/specification/authentication/

[ereshetova]

Overall I would leave OpenID out for now and until anyone has a good use cases to support it in WoT. I think it would be more relevant to define basic methods first.

[ereshetova]

With regards to these:

"http": HTTP Authentication
"proxy": HTTP Proxy authentication (note: to be combined with other authentication mechanisms for the actual endpoint)

Do we really need to separate these two into two distinct types from a TD perspective? They are going to have exactly the same structure, and it should not matter for client where this http authentication is needed: end point or proxy. Just if we have a proxy case, we will likely specify another mandatory authentication method for endpoint (or maybe not, if endpoint doesn't happen to require any).

[ereshetova]

+What about other versions of OAuth? What about versions in general?

When it comes to OAuth, I think we should only support OAuth 2.0 unless we are under any legacy compliance requirements. So in that sense, having security type explicitly specifying "oauth2" as in https://swagger.io/docs/specification/authentication/ is a good idea IMO.

When it comes to "in general", I think for other security types, that we are considering now, we should be probably agnostic to versions: http, api key, bearer, ocf (not sure what ocf plans are with regards to versioning through).