[All] breaking: add allow_existing_users config defaulting to False

[consideRatio]

Before the introduction of this config, existing jupyterhub users would when allowed_users was configured be allowed as well, but now they won't unless allow_existing_users is explicitly configured to True, and then they will be allowed independently if allowed_users was configured with any users or not.

Checklist

• [x] Changelog breaking change entry added
• [x] Tests added Note that the test validates the add_user hook adds users to the allowed_users set if allow_existing_users is configured. So, we don't make a full end to end test where the authenticator authenticates and authorizes an existing user. We have tests for successful use of the allowed_users set though, so the part missing is testing the assumption that add_user is called by JupyterHub for existing users on startup and for newly created users, but that is a JuptyerHub promise for Authenticator.add_user.
• [x] Documentation updated

Related

• Fixes #619
• Discussion about this in jupyterhub/jupyterhub, considering if we can add config like this in the Authenticator base class and if so how it should be named etc: https://github.com/jupyterhub/jupyterhub/issues/4483

[consideRatio]

One idea that might be worth communicating in the help string is the idea that "users previously granted access will continue to have access" (by any means) if this is True.

If "granted access" means "configured to be allowed" then this isn't true if allowed_organizations was configured for example. But if "granted access" means "successfully signed in", then its true but also leaves out the case when they were configured to be allowed via allowed_users or similar. This complexity makes me not come up with an alternative formulation that I think is better =/ If you have a formulation idea that you think is better, go for it.

Another point to perhaps add clearly and succinctly, which follows directly from the previous one, but I think is worth communicating is that this option means removing users from allowed_users does NOT revoke access if this is True.

I've updated the allow_existing_users help string about this, and made the changelog reference to config be links to the configuration reference.

[consideRatio]

I rebased to reduce complexity of documentation PRs I'm working on building on this PR.