Remote access and JWT Tokens / IAM

[philchillbill]

The Wiki page at https://www.domoticz.com/wiki/Security mentions that Domoticz has an IAM server (as one of its 3 component parts) and that it's possible to "Retrieve an 'Access Token' (JWT Token) from the IAM server and provide this Bearer token with each request". Sounds like the Long Lived Access Token concept that Home Assistant has, great!

Except that there is no further info on HOW TO DO THIS and the referenced docs at https://github.com/domoticz/domoticz/bl ... Y_SETUP.md read more like an essay/wishlist/vision of the future for Domoticz than a summary of what already exists and how to use it.

Does anybody know how to actually use this Domoticz functionality? I need remote access to the Domoticz JSON API from my Alexa skills and that's broken since the new security was introduced. I know basic-auth is still an option but I'd like to switch to Bearer tokens if I need to make changes anyway. I've written my own oauth servers so I'm not a noob on the topic, it's just that the current docs/WiKi are sadly lacking real content.

[brucemiranda]

The new "security" version of Domoticz broke my previously running version too. The issue was that the new version doesn't play nicely if you have a db created from an older version. The result is that you simply cannot log in. The admin and default password don't work, the -nopasswd option doesn't work. So my new installation became very secure I.e. even I couldn't log into it. This is where I too ran into the issue of the lack of documentation. In the end, I had to start again! and then everything started. New features are only as good as documentation.....even for us nerds.

[kiddigital]

Agreed that the documentation can/should be improved.

If/when you are familiar with OAuth2 and OpenID Connect, start with querying the OpenID discovery end-point at

`https://<yourIP:port>/.well-known/openid-configuration` to find the URI’s to use for getting an access-token and Bearer token. And which methods and encryptions are supported.

Make sure you add an ‘Application’ (under setup/more) first. Preferably with its own public/private keypair.
And add a 'User' you want to use (do not use the default admin).

The ‘SECURITY_SETUP.md’ contains more details.

Let me know if you get stuck… or succeed

[philchillbill]

"Using the password flow, one can get an access_token without the need to first obtain an authorization_code by just provider (sic) the username/password of a user."

And where do we "just provide" this? Do we need to POST or PUT the request to the relevant endpoint? What should the body parameters be called? I'm afraid there's still not enough to go on in in this result:

Code: Select all

{
	"authorization_endpoint" : "http://domoticz.local:8080/oauth2/v1/authorize",
	"code_challenge_methods_supported" : 
	[
		"S256"
	],
	"grant_types_supported" : 
	[
		"authorization_code",
		"password",
		"refresh_token"
	],
	"issuer" : "http://domoticz.local:8080/",
	"response_types_supported" : 
	[
		"code"
	],
	"token_endpoint" : "http://domoticz.local:8080/oauth2/v1/token",
	"token_endpoint_auth_methods_supported" : 
	[
		"client_secret_basic"
	],
	"token_endpoint_auth_signing_alg_values_supported" : 
	[
		"PS256",
		"RS256",
		"HS256",
		"HS384",
		"HS512"
	]
}

In HA, if you visit your profile in the UI there's a button at the very bottom of the page to generate a token. No need for endpoints or constructing https requests in order to get a simple Bearer token. I wonder why the Domoticz approach is so complicated?

[kiddigital]

HA has support for OAuth2 as well and works in the same way.

Difference is that Domoticz does NOT support 'Long Lived Access Tokens' as it is considered unsafe practice.

'Easiest' (but not recommended, especially from external sources) is to use the 'password' grant_type:

Code: Select all

POST https://{{hostname:portnumber}}/oauth2/v1/token?client_id=<myapplication>

With the request the 'Authorization' header need to sent containing a 'Basic Authentication' string containing the Username and Password for a valid domoticz user.

The recommended approach is using the 'authorization_code' grant_type:

Code: Select all

GET https://{{hostname:portnumber}}/oauth2/v1/authorize?response_type=code&client_id=<myapplication>&state=somestate&redirect_uri=https://{{hostname:portnumber}}/<myreturnuri>

You will be asked to enter user credentials (in case 2FA is enabled, also for the 2FA code) and receive a temporary 'access_token'.

Now you can exchange the access_token for a Bearer token AND receive a Refresh token as well.

Some more information can also be found in the original Pull Request #4872

Hopefully this helps (and yes, documentation still has to be improved...)

[brucemiranda]

Why is the Long Lived Token any more or less secure than a User ID and password. Surely if the Domoticz owner is in control of the Long Lived Token, then its almost as secure, but less likely to be brute forced.

[kiddigital]

Why is the Long Lived Token any more or less secure than a User ID and password. Surely if the Domoticz owner is in control of the Long Lived Token, then its almost as secure, but less likely to be brute forced.

It is not any more or less secure as UserID/Password. If one is happy with a UserID/Password to be sufficient as protection, than a Long Lived Token can be considered as the same.

But using only 'Username/Password' is not considered sufficient anymore nowadays. That's why for example Multi-Factor Authentication is being used almost everywhere and domoticz (beta) has this option now as well. And that is also why Long-Lived Tokens are not implemented/available.

[brucemiranda]

Is it too difficult to implement a Long Lived Token in Domoticz, especially as other lesser secure methods are also available any way I.e. user ID and password? That way the user gets choice of what to use.

[philchillbill]

So Domoticz is capable of handling a regular oauth "give me a one-off token, I'll swap that for an access_token/refresh_token pair, and from now on I'll use the access_token, except when it expires I'll request a new one using the refresh_token" flow

The thing is, this is all about remote access to Domoticz since we know there's no need for oauth on my home network. However, Domoticz' native oauth server is not accessible from outside my network until I have made Domoticz remotely accessible, so I see a chicken and egg problem here. How can my remote service request keys to access Domoticz if the oauth server is Domoticz itself which is not accessible? There's no 'local' application on my LAN asking Domoticz for these keys.

Take my EvoControl Alexa skill that uses oauth to access the Honeywell cloud to control people's Evohome thermostats. During setup, I direct a user to login to a Honeywell server in the cloud with their personal credentials. That cloud server hits my (also cloud) endpoint with the one-off token which I then exchange for usable tokens. From now on, I can use those tokens to do the magic and access the Honeywell cloud on behalf of each user.

The thing is, the Honeywell oauth server is accessible for me to query it. Now imagine Domoticz is the oauth token issuer. I cannot ever reach it in order to request tokens to, er, reach it...

[kiddigital]

Is it too difficult to implement a Long Lived Token in Domoticz, especially as other lesser secure methods are also available any way I.e. user ID and password? That way the user gets choice of what to use.

Probably not, but why do that if safer alternatives are already available?

[kiddigital]

So Domoticz is capable of handling a regular oauth "give me a one-off token, I'll swap that for an access_token/refresh_token pair, and from now on I'll use the access_token, except when it expires I'll request a new one using the refresh_token" flow

Yep

The thing is, this is all about remote access to Domoticz since we know there's no need for oauth on my home network.

Hm.. I would advice to setup security anyway even for an internal network. You never know where a breach might come from and then you are all exposed. Especially nowadays with so many 'connected devices' even in your 'local' network... But agree, the major use-case for the IAM service is to support access from the outside and do that better than just a basic session-cookie and/or simple User/Pass parameters.

However, Domoticz' native oauth server is not accessible from outside my network until I have made Domoticz remotely accessible, so I see a chicken and egg problem here. How can my remote service request keys to access Domoticz if the oauth server is Domoticz itself which is not accessible? There's no 'local' application on my LAN asking Domoticz for these keys.

Take my EvoControl Alexa skill that uses oauth to access the Honeywell cloud to control people's Evohome thermostats. During setup, I direct a user to login to a Honeywell server in the cloud with their personal credentials. That cloud server hits my (also cloud) endpoint with the one-off token which I then exchange for usable tokens. From now on, I can use those tokens to do the magic and access the Honeywell cloud on behalf of each user.

The thing is, the Honeywell oauth server is accessible for me to query it. Now imagine Domoticz is the oauth token issuer. I cannot ever reach it in order to request tokens to, er, reach it...

Maybe a dumb question from my end (not having researched Alexa skills) but say that a valid token has been acquired somehow, how can the Alexa skill access domoticz if domoticz is not accessible from the outside? Does the skill run locally somehow?

And yes if domoticz (and therefor its build-in IAM service) is not accessible from the outside, network connection wise and independent if valid authentication and authorization has been done, nothing is accessible. So opening up (either forwarding or using a Proxy) to the outside world is a prerequisite anyway.

How did the Alexa skill work before the security changes?

[brucemiranda]

Hence why a Long Lived Token makes sense. You can provide that and be reasonably assured that it's a valid request made, because you generated the token. Much better than a User/Password that could be a result of a brute force or passphrase attack..So sits in between User ID/Password and 2FA.

[philchillbill]

Before the changes, it was just https + basic-auth access from the cloud. I expect a user to have set up a proxy like apache/nginx (if opening ports), or ngrok if not. The skill (which runs in an AWS Lambda container in the cloud) can access the Honeywell servers via oauth, and also talk to Domoticz via a https URL that the user specifies (with their basic-auth credentials) on a web-form I provide. When a Domoticz user has a so-called HGI-80 hardware device connected to their system, it exposes more info than the Honeywell API gives me about the overall setup. So while the skill works just fine without the Domoticz (or HA) connector, it can do even more with the extra connectivity available.

With the 'new' setup, the user has to flick the "allow basic-auth" switch in Domoticz and also create a Domoticz user with the same username and password that they are using for the proxy. After the auth details in the https header pass through the proxy they propagate onwards to Domoticz and are re-used as the auth to access Domoticz itself. That works just fine, but I had hoped that something like a Bearer token in the 'new' setup would make life easier with no need to set up a specific user in Domoticz to match the proxy.

The thing about basic-auth over https is that the auth goes in the headers and not the query string and is therefore SSL-encrypted, so it's quite safe. Same with any Bearer token going in the header and similarly being encrypted. One big difference though is that I might guess or brute-force a username/password combo because they tend to be human-readable and reasonably short. A big long token though will never be brute-forceable and nobody looking over your shoulder will ever be able to watch you type it. So I'd argue that any form of Bearer token (whether it has minutes or years of validity) is better than basic-auth just because of the sheer size. If I need to open up Domoticz to the outside world, I'd prefer to have a big long token protecting me than even a strong username/password combo. That's all.

[brucemiranda]

What he said

[philchillbill]

Interesting find: I just setup an ngrok tunnel to http://localhost:8080 with no username/password and tried the

Code: Select all

/oauth2/v1/authorize?response_type=code&client_id=myapplication>&state=somestate&redirect_uri=https://{{hostname:portnumber}}/<myreturnuri>

http GET request using the 'external' https URL — my Domoticz oauth server did respond. So it looks like user credentials are not needed to reach the oauth server, just an internet-exposed Domoticz URL (which is obviously a minimum requirement). Sorry for my misunderstanding but that was not clear from the discussion thus far, nor from the docs. This negates my earlier chicken-and-egg comment for sure...

[kiddigital]

The IAM service, and a few more API calls like ‘getversion’, can be accessed without the need to present valid credentials first.

Otherwise there would be indeed a chicken-egg problem

Let us know if everything works… (or not)

[PierreT]

The new "security" version of Domoticz broke my previously running version too. The issue was that the new version doesn't play nicely if you have a db created from an older version. The result is that you simply cannot log in. The admin and default password don't work, the -nopasswd option doesn't work. So my new installation became very secure I.e. even I couldn't log into it. This is where I too ran into the issue of the lack of documentation. In the end, I had to start again! and then everything started. New features are only as good as documentation.....even for us nerds.

You probably created some user account in the past. I did so too and as this was a read-only account aimed to expose some info to the internet the introduction of this over the top security model caused me to get locked out completely. The documentation on disabling the security is wrong btw, the correct command line parameter to do this is `-nowwwpwd` however this doesn't really work as expected too because it takes the grants that were given to that already existing user. Luckily this does not block you from entering the settings menu and change those grants to get full access again.

[PierreT]

The thing about basic-auth over https is that the auth goes in the headers and not the query string and is therefore SSL-encrypted, so it's quite safe. Same with any Bearer token going in the header and similarly being encrypted. One big difference though is that I might guess or brute-force a username/password combo because they tend to be human-readable and reasonably short. A big long token though will never be brute-forceable and nobody looking over your shoulder will ever be able to watch you type it. So I'd argue that any form of Bearer token (whether it has minutes or years of validity) is better than basic-auth just because of the sheer size. If I need to open up Domoticz to the outside world, I'd prefer to have a big long token protecting me than even a strong username/password combo. That's all.

Not to belittle the threat that hackers form, but if someone set out to guess your case insensitive forum name using brute force method it would take them 190 years before even reaching 'p' in the first position (assuming a 50ms round trip time) and you wouldn't even need a password if the hacker cannot access the list of valid users. Similar, to try every possible combination of a mixed character password of size 8 would take 1.1 million years! Of course there is always the luck factor which greatly enhances if the password is based on a dictionary word, so there is definitely an added value to long tokens and ciphers but in my view security would enhance a lot if people stopped making such a fuzz about it and actually encourage people to choose weak passwords that are easy to remember until at least such a time that they can store the enforced new password in a vault.