BearerSecurityScheme

[RRebekka]

Hi,

I have a question regarding the Bearer Security Scheme. I have a thing that needs an Bearer token in the Authorization header for its endpoints. I want to use a Thing Description with the following security scheme:

{
  "@context": [
    "https://www.w3.org/2019/wot/td/v1",
    {
      "@language": "en"
    }
  ],
  "title": "My Protected Thing",
  "securityDefinitions": {
    "bearer_sc": {
      "scheme": "bearer",
      "in": "header",
      "name": "Authorization",
      "format": "jwt",
      "description": "JWT token obtained from authorization server"
    }
  },
  "security": ["bearer_sc"],
  "properties": {
    "status": {
      "type": "string",
      "forms": [{
        "href": "https://example/api/status",
        "op": "readproperty"
      }]
    }
  }
}

My question is know, how do I describe the process of getting this access token from the thing in a WoT-comaptible way that can be interpreted by any client. I know that there is this authorization parameter, but I cannot specify how the request and response look like, right?

I was thinking about using an action for a login endpoint like the following:

{
  "securityDefinitions": {
    "bearer_sc": {
      "scheme": "bearer",
      "in": "header",
      "name": "Authorization",
      "format": "jwt"
    },
    "nosec_sc": {
      "scheme": "nosec"
    }
  },
  "security": ["bearer_sc"],
  "actions": {
    "login": {
      "description": "Authenticate and obtain bearer token",
      "security": ["nosec_sc"],
      "input": {
        "type": "object",
        "properties": {
          "username": {"type": "string"},
          "password": {"type": "string"}
        },
        "required": ["username", "password"]
      },
      "output": {
        "type": "object",
        "properties": {
          "token": {"type": "string"}
        }
      },
      "forms": [{
        "href": "https://example/api/token",
        "htv:methodName": "POST",
        "contentType": "application/json"
      }]
    }
  }
}

However, this implies that the client needs to know, that the login endpoint has to be used before any other affordances can be used, which is implicit knowledge about the thing. Is there any other, better way for describing this use case?

Best regards,
Rebekka

[relu91]

How do you obtain the token? Is it coming from an OAuth flow? Have you looked into https://www.w3.org/TR/wot-thing-description11/#oauth2securityscheme ? From your TD, it looks like client flow might be appropriate.

I know that there is this authorization parameter, but I cannot specify what the request and response look like, right?

Sadly, no.. you can't.

[RRebekka]

No, I do not have a full OAuth flow. There are endpoints where I can get the token from, either using a POST request with username, password, relam in body or use a endpoint with Basic Authentication for getting the token.

An ordering for multiple security schemes is also not possible right?

[egekorkan]

@RRebekka thank you for the question and that is out of scope, thus out of band information for a WoT Consumer. Same for OpenAPI: https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/

You can use multiple schemes though: https://www.w3.org/TR/2023/REC-wot-thing-description11-20231205/#combosecurityscheme and https://www.w3.org/TR/2023/REC-wot-thing-description11-20231205/#security-comboSecurityScheme

[egekorkan]

@RRebekka also see point two at #2153 (comment)

[egekorkan]

TD Call: This is not about the common definitions but a bigger architectural security bootstrapping issue. It is same as getting username password.

We will close it as it is out of scope. Feel free to reopen though :)

[RRebekka]

Hi @egekorkan and @relu91 , sorry for the late reply. I'm still wodnering how I can use the BearerSecurityScheme correctly without having any implicit knowledge in the client implementation and without the oauth2 functions. Especially, I'm wondering how I can use the "authorization" parameter in the scheme. On client side I can read this URI, however the client cannot know how to use this URI exactly. Meaning, how a request to this endpoint should be desgined (allowed method, path or query parameters, body, content type...) Of course, I could add the endpoint as an action for example in the thing description, but I do not know how to then make it clear for the client that the specific action is linked to the value givne in the authorization parameter. Do you have any suggestions for that?

Best regards,
Rebekka

[egekorkan]

@RRebekka firstly I would not recommend adding an action for credentials since that is also implicit knowledge. I wanted to make sure so checked with a colleague and you generally (for all APIs, including WoT and OpenAPI), you do not want to put onboarding related information. In your example, we can start asking how to get the username and password. Then start putting another interaction with href of mailto:sales@acmecorp.com and so on. Sometimes you also need text to explain the process to humans etc.

So my suggestion here is to NOT describe this process in your TD and accept that this part of the description is out of band in your documentation.

Note: there is a chance that this kind of activity can be picked up under the general "onboarding" topic but we don't have a champion/driver for that and it is not a high priority topic at the moment.