[docs] Show how to enable Kerberos in various runtimes

webknjaz commented 1 month ago

With https://github.com/qutebrowser/qutebrowser/issues/4595#issuecomment-2369165892, I realized that different platforms have transitive dependencies pre-compiled differently. So I figured it'd be nice to document this.

What are the best pages in the docs to put this info in? FAQ? Configuring? Install? All 3?

It'd be good to document the following:

the need to enable the kerberos USE-flag on Gentoo (https://wiki.gentoo.org/wiki/Qutebrowser#Troubleshooting)
the need to make sure qtwebengine got compiled with Kerberos in other environments (I have no idea how)

a working example of the args in config.py:

$ cat ~/.config/qutebrowser/config.py
c.qt.args = [
"auth-server-allowlist=*.fedoraproject.org,*.work.corp.com",
"auth-server-whitelist=*.fedoraproject.org,*.work.corp.com",
"disable-auth-negotiate-cname-lookup=true",
]
config.load_autoconfig()

The-Compiler commented 1 month ago

the need to enable the kerberos USE-flag on Gentoo (https://wiki.gentoo.org/wiki/Qutebrowser#Troubleshooting)

That seems like something for the install docs, as it's Gentoo-specific

the need to make sure qtwebengine got compiled with Kerberos in other environments (I have no idea how)

From a quick look at Archlinux, Debian, NixOS they all compile with Kerberos support already, and as a user you typically don't recompile things from source (especially not something as big as QtWebEngine). So nothing to do there.

a working example of the args in config.py: [...]

If those are confirmed working, I'd rather turn them into qutebrowser settings. Relevant Qt commits:

Support --auth-server-whitelist (260597) · Gerrit Code Review (added in 5.13, so present in all versions we support)
Adaptations for Chromium 86 (318584) · Gerrit Code Review (changes whitelist to allowlist, we shouldn't pass both, but instead find the right one to pass based on Chromium version (we still support Chromium 83 via Qt 5.15.2, we'll probably drop that at some point, but until then it needs a quick version-specific adjustment)

What does the disable-auth-negotiate-cname-lookup=true thing do? From what I can gather, that was removed from Chromium in 2015, so that seems like a cargo-cult leftover?

tl;dr: Do things work as expected when you only pass auth-server-allowlist? If so, let's just turn that into a setting instead of documenting things.

webknjaz commented 1 month ago

Do things work as expected when you only pass auth-server-allowlist?

I think it worked when I tested it. I'll need to re-check.

What does the disable-auth-negotiate-cname-lookup=true thing do?

Not sure, but this was documented as needed in the internal docs. I'll need to dig deeper to understand. But I think it was supposed to prevent DNS lookups.

From what I can gather, that was removed from Chromium in 2015, so that seems like a cargo-cult leftover?

I think that thread is talking about removing the CLI argument and not the underlying setting.

One thing I like about configuring Chrome/Firefox is that they support policy files — they are JSON/YAML configs for some supported settings that are put into some system-wide location and picked up by the browsers automatically. On our company-provisioned systems, they just inject those and Kerberos is pre-configured, among other things. They can also list browser extensions to be auto-installed or forbid some toggles from being changed.

I suppose qutebrowser's config.py covers this partially, but it would be interesting to see it picking up the policy for Chrome or Chromium automatically (or with a one-line call in config.py).

the need to make sure qtwebengine got compiled with Kerberos in other environments (I have no idea how)

From a quick look at Archlinux, Debian, NixOS they all compile with Kerberos support already, and as a user you typically don't recompile things from source (especially not something as big as QtWebEngine). So nothing to do there.

I was thinking something along the lines of the “about” page of qutebrowser showing how the underlying libraries are compiled — I haven't been able to find this information in GUI, which would've been useful while debugging.

the need to enable the kerberos USE-flag on Gentoo (wiki.gentoo.org/wiki/Qutebrowser#Troubleshooting)

That seems like something for the install docs, as it's Gentoo-specific

Makes sense. It already mentions some USE-flags and hints. And I've updated the doc over in the Gentoo wiki already.

The-Compiler commented 1 month ago

No API exists for those policies, see [QTBUG-60778] Ability to set Chromium managed settings - Qt Bug Tracker. I also don't think info about how Qt was built exists at runtime.

webknjaz commented 1 month ago

Oh, too bad. It's sad that FF and Chrome have different policy formats. And Chrome vs. Chromium look into different locations. It would be easier to implement it if there was one standard schema...

webknjaz commented 1 month ago

FTR, here's how our docs recommend configuring GSSAPI in Chrome-like browsers:

Chrome, GNU/Linux

$ mkdir -p /etc/opt/chrome/policies/managed
$ vi /etc/opt/chrome/policies/managed/corp.json

// Chrome Version 100 or lower
// /etc/opt/chrome/policies/managed/corp.json
{
  "AuthServerWhitelist": "*.corp.com",
  "DisableAuthNegotiateCnameLookup" : true
}

// Chrome Version 100 or higher
// /etc/opt/chrome/policies/managed/corp.json
{
  "AuthServerAllowlist": "*.corp.com",
  "DisableAuthNegotiateCnameLookup" : true
}

Chromium, GNU/Linux

$ mkdir -p /etc/chromium/policies/managed
$ vi /etc/chromium/policies/managed/corp.json

// Chrome Version 100 or lower
// /etc/chromium/policies/managed/corp.json
{
  "AuthServerWhitelist": "*.corp.com",
  "DisableAuthNegotiateCnameLookup" : true
}

// Chrome Version 100 or higher
// /etc/chromium/policies/managed/corp.json
{
  "AuthServerAllowlist": "*.corp.com",
  "DisableAuthNegotiateCnameLookup" : true
}

Chrome, macOS

$ defaults write com.google.Chrome AuthServerAllowlist "*.corp.com"
$ defaults write com.google.Chrome DisableAuthNegotiateCnameLookup -boolean true

If this doesn't work, they suggest doing defaults delete com.google.Chrome before those commands. And for Brave and Edge, the third argument would be com.brave.Browser and com.microsoft.Edge.plist respectively.

Additionally, this is supposed to be verifiable via chrome://policy / brave://policy / edge://policy.

`AuthServerAllowlist`

This is the main requirement. It lets browser know where it's acceptable to attempt using Kerberos auth. It should be a narrow. Allowlisting anything would harm performance because the browser would attempt doing the authentication dance when visiting any web-site and it's just going to slow down loading pages.

`DisableAuthNegotiateCnameLookup`

I did some reading and this setting seems to be important. I looked into the reasoning of people asking for this setting to be added to the policies internally, and some public documentation on the internet.

Furthermore, I saw mentions of configuring a similar setting within the system Kerberos configs as well (dns_canonicalize_hostname = true in /etc/krb5.conf).

I may not have understood everything, but from what I gathered, the problem exists when DNS records of some services have CNAME setup instead of direct A/AAAA entries. And various Kerberos/browser components resolve that and use the intermediate domain CNAME points to for various lookups, which causes them to fail when only the nice canonical name is allowlisted.

`AuthNegotiateDelegateAllowlist`

This one must never be set, though, as it grants the ability to some servers to impersonate users.

The-Compiler commented 1 month ago

Important or not, passing disable-auth-negotiate-cname-lookup=true to qt.args will not do anything at all from what I can see.

webknjaz commented 1 month ago

Yeah, I guess I understand it better now. Still, wanted to document why it's there. Is there any other way to pass the setting to qtwebengine?

webknjaz commented 1 month ago

FWIW, this config works for me, so I think the auth-server-allowlist option does its job well. I suspect that it may break for certain network resources, since disable-auth-negotiate-cname-lookup doesn't work. Which I'm fine with for now. I think the suggestion of making these native settings is still valuable, even if it's currently only possible to have it for auth-server-allowlist and not disable-auth-negotiate-cname-lookup.

The-Compiler commented 1 month ago

Yeah, I guess I understand it better now. Still, wanted to document why it's there. Is there any other way to pass the setting to qtwebengine?

Only if Chromium provides a way to set such a "pref" thingy or policy settings via CLI arguments or env variables. From what I can see, there's only a small list that are exposed as CLI arguments, unfortunately.

webknjaz commented 1 month ago

Aha... So it seems like kAuthServerAllowlist is the only thing provided that is related to Kerberos: https://chromium.googlesource.com/chromium/src/+/main/chrome/browser/prefs/chrome_command_line_pref_store.cc#48.

qutebrowser / qutebrowser