Multiple OAuth 2.0 flows in security definitions

[farshidtz]

This is relevant to issue #901 and can be resolved to an extent with the support for applying security schemes in an OR fashion.

It is very common to have things with endpoints that perform authorization based on one or more OAuth 2.0 flows. Other OAuth 2.0 flows are being added to the specs, and all relevant forms in a TD will have to be repeated to specify the support for each flow (e.g. code, client, or device). Note that for some OAuth 2.0 flows, the server (thing) only receives and validates a token from the user, regardless of the flow which was followed to obtain that token from the authentication server.

Consider the following, a TD with one form and three OAuth 2.0 flows:

{
    "securityDefinitions": {
        "oauth2_code": {
            "scheme": "oauth2",
            "flow": "code",
            "authorization": "https://example.com/authorization",
            "token": "https://example.com/token",
            ...
        },
        "oauth2_client": {
            "scheme": "oauth2",
            "flow": "client",
            "authorization": "https://example.com/authorization",
            "token": "https://example.com/token",
            ...
        },
        "oauth2_device": {
            "scheme": "oauth2",
            "flow": "device",
            "authorization": "https://example.com/authorization",
            "token": "https://example.com/token",
            ...
        }
    },
    "security": ["oauth2_code"],
    "properties": {
        "status": {
            "forms": [{
                "href": "https://scopes.example.com/status"
            },{
                "href": "https://scopes.example.com/status",
                "security": ["oauth2_client"]
            },{
                "href": "https://scopes.example.com/status",
                "security": ["oauth2_device"]
            }]
        }
    },
    ...
}

A large part of TD is dedicated to describe something that the authentication server provides, rather than the thing.

If the type of flow attribute is extended from string to string or Array of string. The above TD can be reduced to:

{
    "securityDefinitions": {
        "oauth2_sc": {
            "scheme": "oauth2",
            "flow": ["code", "client", "device"], // proposed Array of string OR introduce new flows field.
            "authorization": "https://example.com/authorization",
            "token": "https://example.com/token",
            ...
        }
    },
    "security": ["oauth2_sc"],
    "properties": {
        "status": {
            "forms": [{
                "href": "https://scopes.example.com/status"
            }]
        }
    },
    ...
}

OpenAPI's OAuth 2.0 spec have a different structure, but it still allows definition of array of flows, even though the security schemes are applied as OR.

[farshidtz]

One issue with this proposal is that there will be no way of picking a subset of flows or overriding the default set in a form. For example, a management endpoint may just support code flow. In this case, the TD should define another securityDefinition with just one flow and associate it with the management endpoint.

[mmccool]

So I like the idea of having an array of flows in the definition. And if you have to specify a specific flow in a form then you can just use separate security definitions. This also (unlike changing AND to OR) would not break backward compatibility.

[farshidtz]

Similar feature is not provided using the combo security scheme:
https://www.w3.org/TR/wot-thing-description11/#combosecurityscheme

#944