HTTP adapter should support Bearer token authentication scheme

[sophokles73]

Devices might already be in possession of a token acquired by means of any of the OAuth workflows. It would be great if the HTTP adapter could support authentication of devices presenting such a token as defined in RFC 6750.

The adapter should be able to validate signed Json Web Tokens based on a (configurable) list of trusted identity providers (i.e. issuers of such tokens).

[Alfusainey]

@sophokles73 do you think it make sense to assign this issue to yourself or me in order to avoid another contributor concurrently working on it?

[sophokles73]

@Alfusainey does this mean that you (or your student) are now working on this?

[Alfusainey]

he (the student) has not started the implementation yet. he is currently doing a lot of background work. if he opts out or is not longer interested, then i will work on it myself. i think this issue is due for the 0.9 release (i.e February 25th, 2019), so we should be fine.

[sophokles73]

I can only assign issues to committers, so for the time being, I will assign it to myself (pro forma) ...

[sophokles73]

The token will be used to authenticate the device. As part of the authentication process, we determine the device identity from the tuple (tenant, credentials type, auth-id). Based on this, we should probably expect to find both the tenant as well as the device ID encoded in claims of the JWT. One possible way of doing so would be:

{
  "iss": "https://hono.eclipse.org",
  "sub": "4711@PETERS_TENANT"
}

In the example above the iss (issuer) claim identifies the system that has created (issued) the token. The sub (subject) claim contains the device's ID and tenant which are (required to be) unique within the scope of the issuer.

However, using this approach would probably require us to define a certain pattern for the issuer and subject claim values. It would be easier to determine the tenant and device ID based on explicit claims, e.g. tenant and device. That would put less constraints on the implementation of token issuing applications. An example of such a token would be

{
  "iss": "https://home-appliances.org/",
  "sub": "Peter Piper's refrigerator",
  "tenant": "PETERS_TENANT",
  "device": "4711"
}

This token contains more data but also makes the semantics of the data more explicit and easier to extract (no parsing of values required).

Validation of the token works by validating the token's signature using the key registered for the token's issuer in the tenant. Note that the issuer and tenant can be read from the token during validation because the token is not encrypted but signed only.

[jbman]

I like the idea of accepting a token with dedicated hono specific claims:

{
  "iss": "https://home-appliances.org/",
  "sub": "Peter Piper's refrigerator",
  "tenant": "PETERS_TENANT",
  "device": "4711"
}

It is probably easier to achieve this format with a an authorization server than the custom format at the sub claim. In addition I'd like to propose to have hono specific claims prefixed with "hono_". This avoids collisions with other information which could be placed into the token. With this approach, an authorization server could produce tokens which are accepted by multiple services and which could be forwarded from one (micro-)service to an other.

Example: { "iss": "https://home-appliances.org/", "sub": "Peter Piper's refrigerator", "hono_tenant": "PETERS_TENANT", "hono_device": "4711", "webconsole_role: "developer", "report_tenant": "PETERS_TENANT_AT_REPORT_SERVICE" } In this example, we assume there is a webconsole application which gets role information through he token. At the same time, the webconsole application can use the token to send device test messages and access an additional report service.

[sophokles73]

@jbman thanks for the input. I think it's a great idea to use a prefix indicating the scope of the claims. Is it a common pattern to use an underscore for separating the prefix from the claim name? Otherwise I'd prefer to use a colon, e.g. hono:tenant and report:tenant, which would more resemble the approach taken in URNs.

[jbman]

@sophokles73 the colon is also fine. I don't think there is a general rule.

Sometimes URIs are used as namespace to avoid collision of token claims, but if you want to have many info in the token you also want to keep the keys small. I found that SaaS provider Auth0 only supports adding URI-prefixed claims (see Custom Claims.

So the extended proposal is the following.

• Make the claim namespace configurable (Accepted claims look like namespace + "tenant")
• Default claim namespace is "hono:", if nothing custom is configured.

Example for custom configuration: namespace = http://mydomain.com/uris/hono/

"http://mydomain.com/uris/hono/tenant": "PETERS_TENANT",
"http://mydomain.com/uris/hono/device": "4711",

Of cause a "make it configurable" feature could be another issue and is not necessary from the start.

[sophokles73]

That makes sense to me. So, for Hono we could then use something like

"https://eclipse.org/hono/tenant": "PETERS_TENANT",
"https://eclipse.org/hono/device": "4711"