deprecate hosted_domain in favor of restrict_hosted_domains, always apply strip_domain if True, clarify docstrings

[minrk]

related to #828 and the confusion that led to it

In discussing this, I also considered deprecating hosted_domain in favor of restrict_hosted_domains to be even clearer and disambiguate from the new allow_hosted_domains, but didn't take that step here, this is just the docstring.

[manics]

I think this is fine, and deprecating is also fine if you want since the configuration is pretty complex.

Is it intentional that strip_domain is ignored for everything other than hosted_domain

oauthenticator/oauthenticator/google.py

Lines 250 to 251 in 5ffbbe9

	if self.strip_domain and user_info["domain"] in self.hosted_domain:
	username = username.split("@")[0]

i.e. domains are never stripped if you're using allowed_domains?

[yuvipanda]

+1 for rename & deprecate, I think it makes this much clearer.

[minrk]

Is it intentional that strip_domain is ignored for everything other than hosted_domain

I think that's a valid question, and I think the answer is "yes" that it's intentional, but that doesn't mean it has to be that way. It seems confusing that strip_domain has no effect when hosted_domain is not set, and potentially inconvenient if you want to use it for some reason. However, strip_domain is really only safe to use with hosted_domain (the restrictive one) of length exactly 1, it is not safe to use in any other configuration where usernames come from multiple @domain namespaces.

[minrk]

What should the behavior of strip_domain be, and how should we migrate to it? This is a bit relevant to the deprecation of the name, since I'd like to not inherit the implicit behavior of the old name, if we can help it.

Here's what I think is the simplest:

1. if strip_domain is true, it is applied to all accounts instead of just hosted_domain matches
2. keep strip_domain = True default only when deprecated hosted_domain has length 1
3. DO NOT default strip_domain = True in any other circumstances (i.e. don't inherit this conditional default in the new restrict_hosted_domains, and unconditional default=False when deprecated hosted_domain is dropped)

2 and 3 keep consistent current behavior and offer a smooth deprecation path, but 1 could be considered a breaking change, because if anyone had explicit strip_domain = True in a situation without hosted_domain set, it is a nonsensical (but safe!) no-op now (strip_domain = True + no hosted_domain is the same as strip_domain = False) , and becomes an actual sensible (but unsafe!) configuration with the change.

[minrk]

This PR now reflects the above proposal - hosted_domain behavior is unchanged, but deprecated in favor of restrict_hosted_domains (always a list, doesn't need backward-compatibility shims for scalar string value). strip_domain now always strips the domain, regardless of hd and the value of of hosted_domain. It is only implicitly True when hosted_domain has exactly one value, otherwise it's must be set explicitly.