Wot-thing-description: [question] How to describe Philips Hue security scheme

[egekorkan]

I have a Philips Hue system where the Hue bridge creates a key/token for the users that should be appended to URLs while sending requests. Below is an example request (from their documentation with the token 1028d66426293e821ecfd9ef1a0731df to read the state of the light number 1:

GET https://<bridge ip address>/api/1028d66426293e821ecfd9ef1a0731df/lights/1

This can be modeled as a property in a TD like:

{
    "title": "Hue Light 1",
    "securityDefinitions": {
        "nosec_sc": {
            "scheme": "nosec"
        }
    },
    "security": "nosec_sc",
    "properties": {
        "lightState": {
            "forms": {
                "href": "https://192.168.0.1/api/1028d66426293e821ecfd9ef1a0731df/lights/1"
            }
        }
    }
}

I would imagine that I should be able to define a security scheme and not put the token in the href, which is visible to anyone who gets the TD. Following is using myScheme security scheme.

{
    "title": "Hue Light 1",
    "securityDefinitions": {
        "mysec_sc": {
            "scheme": "myScheme",
                        "in":"uri",
                        "name":"mytoken"
        }
    },
    "security": "mysec_sc",
    "properties": {
        "lightState": {
            "forms": {
                "href": "https://192.168.0.1/api/{{mytoken}}/lights/1"
            }
        }
    }
}

@mjkoster @mmccool any ideas?

This is also related to https://github.com/w3c/wot-thing-description/issues/897 but this information needs to be displayed somehow in an actual TD and not a TDT.

[relu91]

I want to add that also oAuth2.0 has some variability on how to construct code and token requests. For example OAuth2.0 simplified explains that the protocols parameters can be passed using a POST request (here) while the rfc makes the same example using a GET request with URI query parameters (here).

For oAuth we might even introduce Form elements inside the SecuritySchemaDefinition like the following:

"securityDefinitions": {
        "oauth2_sc": {
            "scheme": "oauth2",
            ...
            "flow": "code",
            "authorization": {
                 "href": "https://example.com/code?response_type=token&client_id={{client}}&state={{state}}&redirect_uri={{redirect}}",
                "htv:method": "GET"
            },
            "token": "https://example.com/token",
            "scopes": ["limited", "special"]
        }
    }

Of course, we can discuss this further after we fully analyze each flow usecase inside WoT. However, this is another example where the current specs cannot fully describe the security protocol.

[egekorkan]

Nice to have more need to choose a templating mechanism for TDs! I think for the case above, our uriVariables can be used inside the securityDefinitions. For the Philips Hue, the URI itself changes before coming to the query parameters.

[takuki]

I want to add that also oAuth2.0 has some variability on how to construct code and token requests. For example OAuth2.0 simplified explains that the protocols parameters can be passed using a POST request (here) while the rfc makes the same example using a GET request with URI query parameters (here).

Looking at Microsoft identity platform's use of OAuth 2.0 authorization code flow, it also uses variables in the form:

• Authotization
  https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?client_id=6731de76-14a6-49ae-97bc-6eba6914391e ()
• Token request
  POST /{tenant}/oauth2/v2.0/token HTTP/1.1
  Host: https://login.microsoftonline.com

[mmccool]

Thanks for pointing these out. I think what we should do is extend the apikey and oauth2 security schemes respectively to support URI templates rather than defining new schemes. For apikey, we can define a new "in" value, say "template", and then allow a uriVariables field to give the name (although I suggest that we could also give this a default value, like "apikey", to avoid verbosity, since there will rarely be a conflict...). For oauth2 we want to do something similar. The oauth scheme does not currently have an "in" option but we could add it, with I guess the options "body" (for post), and "query" (for in the URI as query parameters). Do we have to worry about dealing with this differently in the authorization and token servers? That would be a nuisance...

[mmccool]

The Microsoft example shows that, indeed, a single system might use different approaches when talking to the different servers, so a single "in" option won't work. So we might need separate location fields for each like authorization-in and token-in, and refresh-in. We might also need URI templates. For each of these. And maybe even the "template" option... we'll discuss this in the next security call.

[egekorkan]

For apikey, we can define a new "in" value, say "template", and then allow a uriVariables field to give the name (although I suggest that we could also give this a default value, like "apikey", to avoid verbosity, since there will rarely be a conflict...)

I agree with this direction, however, there the apiKey is not a uriVariable. Also, we would need to define how this key would look like in the href of the forms.

[mmccool]

We probably should create a separate issue for the oAuth variability issue...

[egekorkan]

@mmccool is there any progress on this?

[egekorkan]

@mmccool is there any progress on this?

[mmccool]

So as it happens when discussing https://github.com/w3c/wot-thing-description/issues/998 I came up with the same idea (a new "template" mechanism for defining where API keys appear) and it seems this is also applicable to OAuth2. I think we should probably proceed with a PR for this. However, I do have one concern: there might be systems that have more than one parameter for "API Key" schemes (for example, a client ID and a key). In this case the proposed "template" scheme, which can only identify one parameter, would not be sufficient. It's not clear to me if the above Microsoft scheme is an example of this.

[egekorkan]

I would imagine something where the keys defined in the securityDefinitions are referenced in the URI values of hrefs in different forms. An example:

{
    "title": "Hue Light 1",
    "securityDefinitions": {
        "mysec_sc": {
            "scheme": "myScheme",
                        "in":"uri",
                        "variables":{
                          "mytoken":{ "description": "lorem ipsum"},
                          "myid":{ "description": "lorem ipsum"},
                         }
        }
    },
    "security": "mysec_sc",
    "properties": {
        "lightState": {
            "forms": {
                "href": "https://192.168.0.1/api/{{$securityDefinitions/variables/mytoken}}/lights/1{{$securityDefinitions/variables/myid}}"
            }
        }
    }
}

I am almost satisfied but it is a bit too verbose maybe?

[egekorkan]

Also see https://swagger.io/docs/specification/authentication/api-keys/

[sebastiankb]

From today's TD call:

• @mmccool will propose a new scheme which is similar to Ege's approach
• the new scheme will be discussed in the next security meeting
• PR will provided by @mmccool