[Need help] Use additional http headers to authenticate against Cloudflare SSO. (Or other SSO)

[Meister1977]

Summary

Added option to define 2 additional http headers to use Cloudflare Zero Trust with service token. (Or other SSO systems).
#2650

Screenshots

Link to pull request in Documentation repository

Any other notes

Please feel free to decline the pull request, I am not a kotlin developer, just added this feature, because I needed. If you can use any part of this commit to add this feature in a better way, just do it.

[home-assistant]

Hello @Meister1977,

When attempting to inspect the commits of your pull request for CLA signature status among all authors we encountered commit(s) which were not linked to a GitHub account, thus not allowing us to determine their status(es).

The commits that are missing a linked GitHub account are the following:

Unfortunately, we are unable to accept this pull request until this situation is corrected.

Here are your options:

1. If you had an email address set for the commit that simply wasn't linked to your GitHub account you can link that email now and it will retroactively apply to your commits. The simplest way to do this is to click the link to one of the above commits and look for a blue question mark in a blue circle in the top left. Hovering over that bubble will show you what email address you used. Clicking on that button will take you to your email address settings on GitHub. Just add the email address on that page and you're all set. GitHub has more information about this option in their help center.

2. If you didn't use an email address at all, it was an invalid email, or it's one you can't link to your GitHub, you will need to change the authorship information of the commit and your global Git settings so this doesn't happen again going forward. GitHub provides some great instructions on how to change your authorship information in their help center.

   • If you only made a single commit you should be able to run

     git commit --amend --author="Author Name <[email protected]>"
     

     (substituting "Author Name" and "[email protected]" for your actual information) to set the authorship information.
   • If you made more than one commit and the commit with the missing authorship information is not the most recent one you have two options:
     1. You can re-create all commits missing authorship information. This is going to be the easiest solution for developers that aren't extremely confident in their Git and command line skills.
     2. You can use this script that GitHub provides to rewrite history. Please note: this should be used only if you are very confident in your abilities and understand its impacts.
   • Whichever method you choose, I will come by to re-check the pull request once you push the fixes to this branch.

We apologize for this inconvenience, especially since it usually bites new contributors to Home Assistant. We hope you understand the need for us to protect ourselves and the great community we all have built legally. The best thing to come out of this is that you only need to fix this once and it benefits the entire Home Assistant and GitHub community.

Thanks, I look forward to checking this PR again soon! ❤️

[home-assistant]

Hello @Meister1977,

When attempting to inspect the commits of your pull request for CLA signature status among all authors we encountered commit(s) which were not linked to a GitHub account, thus not allowing us to determine their status(es).

The commits that are missing a linked GitHub account are the following:

Unfortunately, we are unable to accept this pull request until this situation is corrected.

Here are your options:

1. If you had an email address set for the commit that simply wasn't linked to your GitHub account you can link that email now and it will retroactively apply to your commits. The simplest way to do this is to click the link to one of the above commits and look for a blue question mark in a blue circle in the top left. Hovering over that bubble will show you what email address you used. Clicking on that button will take you to your email address settings on GitHub. Just add the email address on that page and you're all set. GitHub has more information about this option in their help center.

2. If you didn't use an email address at all, it was an invalid email, or it's one you can't link to your GitHub, you will need to change the authorship information of the commit and your global Git settings so this doesn't happen again going forward. GitHub provides some great instructions on how to change your authorship information in their help center.

   • If you only made a single commit you should be able to run

     git commit --amend --author="Author Name <[email protected]>"
     

     (substituting "Author Name" and "[email protected]" for your actual information) to set the authorship information.
   • If you made more than one commit and the commit with the missing authorship information is not the most recent one you have two options:
     1. You can re-create all commits missing authorship information. This is going to be the easiest solution for developers that aren't extremely confident in their Git and command line skills.
     2. You can use this script that GitHub provides to rewrite history. Please note: this should be used only if you are very confident in your abilities and understand its impacts.
   • Whichever method you choose, I will come by to re-check the pull request once you push the fixes to this branch.

We apologize for this inconvenience, especially since it usually bites new contributors to Home Assistant. We hope you understand the need for us to protect ourselves and the great community we all have built legally. The best thing to come out of this is that you only need to fix this once and it benefits the entire Home Assistant and GitHub community.

Thanks, I look forward to checking this PR again soon! ❤️

[home-assistant]

Hi @Meister1977

It seems you haven't yet signed a CLA. Please do so here.

Once you do that we will be able to review and accept this pull request.

Thanks!

[Meister1977]

Please delete my email address from the comments. Thanks!

[dshokouhi]

This PR should have some kind of documentation linked to it. Possibly as part of network troubleshooting?

Also we may want to update the messaging to make it more clear not every user needs to use this. In fact we should probably hide this when the device is using HA cloud.

[marazmarci]

I tried your changes, and the app didn't let me reauthenticate when I revoked the session for my Cloudflare Access user. (It can be done here: https://one.dash.cloudflare.com/*****/team/users/view. Obviously, change ***** to the actual hex string for your CF Access account. Then click on the big red Revoke button on the right.)

After revoking the session, I was able to use a Service widget to toggle a light, so the OkHttpClient was fine using the Service Token I set up. But when I opened the app, I just reproduced #2650 and #3205. That means I got redirected to a browser, and I couldn't authenticate the HA app again, I was just constantly being redirected to the CF login page in the browser.

Maybe I'm doing something wrong 🤷‍♂️

[Meister1977]

@marazmarci , you should create service token in Cloudflare admin, and use that. My change is for this, not to solve the SSO in webview.

[Meister1977]

@dshokouhi , could you help int the text? I am not native English, so if you can change anything in the strings.xml, please suggest me.

[marazmarci]

@marazmarci , you should create service token in Cloudflare admin, and use that. My change is for this, not to solve the SSO in webview.

The Service Token is only used by the OkHttpClient, not the WebView (as I wrote above, it even lacks the ability to add custom headers). And in the WebView, you still have to authenticate via SSO, and that will eventually expire.

I did some testing:

I first set the Cloudflare Access application's session duration to 15 minutes. Then I installed your version on my device, used only my Cloudflare domain at the initial setup (not the internal), authenticated inside the WebView via e-mail + the 6-digit code I received in e-mail, then added the Service Token headers, and when 15 minutes have passed, I wasn't able to log back in first. But later I realized that the Enable Binding Cookie setting was the culprit because I had it turned on.

When I turned it off, I was able to authenticate in the browser, and when the session expired again (after 15mins), it showed the Unable to connect to Home Assistant. ... Retrying in xx seconds... screen (not dialog), but when I clicked on Retry now, it magically continued to work without showing the Cloudflare Access login page, and without opening a browser 🤷‍♂️

one.dash.cloudflare.com → Applications → <your HA application> → Settings → turn off Enable Binding Cookie

I tried exactly the same with the latest release (without your changes), and it behaved exactly the same as I described above. However, there was one difference: I was able to use a Service Button widget with your changes and a Service Token set up.

[mathix420]

Works perfectly for me, using Cloudflare Access and Service Tokens to grant access to the companion app to access my HA server behind cloudflared.

Nice work, however like @dshokouhi mentioned it, you might change the way options are shown in the settings.

[Meister1977]

Thanks @mathix420 , because I am not native English speaker, I need help to write the documentation and to change the text in the App. I have already asked @dshokouhi too.

[mathix420]

@marazmarci when using service tokens correctly you should not be prompted to authenticate, I don't really understand why you need to enter a PIN.

Here is my access config for using service tokens:

Note the use of a Service Auth action exclusively for service tokens.

Maybe my setup can help you understand your problem, or maybe you have different requirements than mine that I didn't understand.

[mathix420]

Thanks @mathix420 , because I am not native English speaker, I need help to write the documentation and to change the text in the App. I have already asked @dshokouhi too.

@Meister1977 Sure, I will try to help you with this once I got a bit of free time this week, but I have very few experience with Kotlin so my help might be limited.

[Meister1977]

Thanks @mathix420 ,
There are only a few strings should be changed. All of them in this file:
e40575f#diff-833a46a97033e77558372a2dce103fd6fee29aaaa899f610022a7aece592ee7b

[jpelgrom]

Thanks @mathix420 , because I am not native English speaker, I need help to (...) change the text in the App.

The requested changes do not only concern text/documentation, but also hiding the setting when using HA Cloud as it isn't relevant in that case.

[Meister1977]

@jpelgrom I am working on it to hide the settings. But I still need the good texts.

[mathix420]

@Meister1977 you can push changes here with the hidden/updated settings with placeholders, I will correct the texts.

[jpelgrom]

To quote the PR template: "user-facing change not in the frontend, please include screenshots in light and dark mode", which applies here, so please update the description with a screenshot as well after you're happy with the text :)

[home-assistant]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

[balloob]

Supporting these kind of remote connections require hacks, workaround and complicates the maintenance of our codebase. Therefore we will not be able to accept this pull request. Users can continue to use a browser to access their Home Assistant instance if they are using CloudFlare or other similar solutions.

[tajnymag]

Without remote connection, Home Assistant Companion App loses quite a lot of its usefulness.

Location tracking? Useless on LAN
Android Auto? Mostly useful outside of home
Mobile network status? Useless on LAN
Notifications? Less useful if they work solely if the device is at home
Geo zones? How would they even work without remote connection?

Yes, some of the features can work even in the browser version, but only some.

[piercy]

Supporting these kind of remote connections require hacks, workaround and complicates the maintenance of our codebase. Therefore we will not be able to accept this pull request. Users can continue to use a browser to access their Home Assistant instance if they are using CloudFlare or other similar solutions.

What an absurd statement to make with all the people following this thread, and the amount of effort gone into making it a reality.

as tajnymag said, you're making so many feature useless or your require us to open up unsecure ports on our home networks. I figured something as open as Home Assistant would make an effort to be security conscious but this decision completely goes against that.

[garysargentpersonal]

@balloob this is crazy a lot of hard work has gone into this, and MANY people want to secure their services using Cloudflare Zero Trust. Adding a few HTTP headers to requests is not a massive hack. I don't see why Home Assistant would not want to support enhanced security. Many other applications support this kind of extra layer of authentication - a layer that protects us from any zero-day bugs in Home Assistant.

[Meister1977]

I will keep maintenance my fork!
But I think, I will create a new forked app in Android Store to enable automatic updates.

[piercy]

I will keep maintenance my fork! But I think, I will create a new forked app in Android Store to enable automatic updates.

Thank you! I'll continue to use this security focused version as it seems basic security practices are "too complicated" for the main version.

@balloob :

complicates the maintenance of our codebase

[solazs]

Sad to see similar PRs getting closed without a sensible solution offered.
I can't see why home assistant actively discourages developers from extending authentication options. Proper MFA + SAML/OICD/OAUTH support would render these kinds of fixes unnecessary, but it seems home assistant devs don't want that either.

[Daniel-dev22]

Sad to see similar PRs getting closed without a sensible solution offered.
I can't see why home assistant actively discourages developers from extending authentication options. Proper MFA + SAML/OICD/OAUTH support would render these kinds of fixes unnecessary, but it seems home assistant devs don't want that either.

That's what I was thinking. If OIDC support was built in then this wouldn't even be needed as much and there are individuals willing to try to implement this but no support from key individuals to implement it so it gets denied.

I use MTLS but that's easy to maintain for a few devices but not if there're many devices it's not easy easy.

[Gathaeryx]

What an absurd statement, how is adding a few lines to a request considered a "hack"?

I get the feeling that the fact that a solution like this is in direct opposition to Home assistant Cloud somehow plays a part in this...

[piercy]

What an absurd statement, how is adding a few lines to a request considered a "hack"?

I get the feeling that the fact that a solution like this is in direct opposition to Home assistant Cloud somehow plays a part in this...

@Gathaeryx Would make more sense than "headers are too complicated / hacky". Could be onto something..

[garysargentpersonal]

I get the feeling that the fact that a solution like this is in direct opposition to Home assistant Cloud somehow plays a part in this...

I pay for Home Assistant cloud but prefer to use Cloudflare.

[garysargentpersonal]

I've spoken to one of the developers on the Discord channel, and the main blocker seems to be that WebView doesn't support extra headers, so they are not used on the front end part of the app. If that is true then that doesn't really sound great. A user would expect the headers to be used throughout, not on only part of the app.

[Meister1977]

@garysargentpersonal I use my fork since last June, and it works.

[Meister1977]

@garysargentpersonal so, there are two type of connections. One of them is the "api calls". These calls happenning in the background. These calls need the api-key in the header, because oauth tokens expire.
The other calls happen when the user see the call, like a webpage refresh. This can be redirected to the single sign on page with mfa.

[garysargentpersonal]

That does sound a bit hacky though and very tied into cloudflare. It isn't going to work with any other protection using just http header authentication is it? Like nginx.

[piercy]

@garysargentpersonal it just adds header fields that you can set to anything. It'll work with anything that can receive the headers. Nothing specifically to do with cloudflare.

The name and value can be set , so it's very generic

[garysargentpersonal]

It doesn't though thats the problem. It doesn't add them to requests from WebView.

[hutchiko]

WebView doesn't support extra headers

🤔 https://mobitechwise.com/ios/how-to-customize-webview-headers-on-ios-and-android/

[marazmarci]

WebView doesn't support extra headers

🤔 https://mobitechwise.com/ios/how-to-customize-webview-headers-on-ios-and-android/

Hi! Yes, true, technically you can add custom headers, but as I wrote at the end of this comment, WebViewClient doesn't provide a way to get the request's body. And for example, an empty body makes most POST requests kinda useless...

[hutchiko]

Thanks for the clarification @marazmarci that does explain the comments mentioned from Discord.

[piercy]

Too be honest, Reading through what you linked, including the open letter and trying to get a general jist of what's going on. It really does paint a picture that home assistant doesn't care about security. Every possible way people are suggesting to tighten things up seems to have some form of problem. One day HA is gonna have a big problem appear. A zero day, unseen by everyone and people are gonna point back to these discussions and hind sight will be 20/20.

Dont even get me started on "My dad isn't gonna setup oidc" - my dad also isn't gonna setup MFA but anyone wanna argue MFA is useless ?

There's an opportunity to work this out and try progress things , instead of shutting down PRs that are making things more secure.

[garysargentpersonal]

They do say mTLS is supported, which cloudflare supports. That might allow the HA companion app to work through Cloudflare zero trust.

[marazmarci]

They do say mTLS is supported, which cloudflare supports. That might allow the HA companion app to work through Cloudflare zero trust.

Yes, mTLS is supported and works with Cloudflare indeed. It also works in the HA Wear OS app. I put together a small guide mainly for future myself, but I hope it can be also useful for others:
https://mmarci.notion.site/Install-Cloudflare-mTLS-client-certificate-on-Android-0fd9997bea6249e88cb60f7d00b44672?pvs=4

[MasterCATZ]

thanks for mTLS guide , disappointed in the dev's not wanting to help with a solution

[garysargentpersonal]

I know its frustrating but blaming the devs isn't the answer. They have helped quite a few times adding comments. They are just not what you want to hear, which essentially is Android has some limitations which mean a neat solution that works for everyone without quirks isn't possible.

[balloob]

Thanks for all the feedback. This is not the right place to discuss this further, please join our community forums or Discord chat. There are enough other options that do work with the app including a VPN, Home Assistant Cloud or opening a port on your router.