maint: update help/docstring and let login_service remain configurable

oauthenticator/auth0.py

@@ -47,9 +47,12 @@ class Auth0OAuthenticator(OAuthenticator):
         **OAuthenticator._deprecated_oauth_aliases,
     }
 
-    login_service = "Auth0"
     user_auth_state_key = "auth0_user"
 
+    @default("login_service")
+    def _login_service_default(self):
+        return os.environ.get("LOGIN_SERVICE", "Auth0")
+
     @default("username_claim")
     def _username_claim_default(self):
         return "email"

oauthenticator/azuread.py

@@ -11,16 +11,12 @@
 
 
 class AzureAdOAuthenticator(OAuthenticator):
-    login_service = Unicode(
-        os.environ.get('LOGIN_SERVICE', 'Azure AD'),
-        config=True,
-        help="""
-        Azure AD domain name string, e.g. My College
-        """,
-    )
-
     user_auth_state_key = "user"
 
+    @default("login_service")
+    def _login_service_default(self):
+        return os.environ.get("LOGIN_SERVICE", "Azure AD")
+
     tenant_id = Unicode(
         config=True,
         help="""

oauthenticator/bitbucket.py

@@ -1,6 +1,8 @@
 """
 Custom Authenticator to use Bitbucket OAuth with JupyterHub
 """
+import os
+
 from jupyterhub.auth import LocalAuthenticator
 from tornado.httputil import url_concat
 from traitlets import Set, default
@@ -14,11 +16,14 @@ class BitbucketOAuthenticator(OAuthenticator):
         **OAuthenticator._deprecated_oauth_aliases,
     }
 
-    login_service = "Bitbucket"
     client_id_env = "BITBUCKET_CLIENT_ID"
     client_secret_env = "BITBUCKET_CLIENT_SECRET"
     user_auth_state_key = "bitbucket_user"
 
+    @default("login_service")
+    def _login_service_default(self):
+        return os.environ.get("LOGIN_SERVICE", "Bitbucket")
+
     @default("authorize_url")
     def _authorize_url_default(self):
         return "https://bitbucket.org/site/oauth2/authorize"

oauthenticator/cilogon.py

@@ -67,19 +67,23 @@ class CILogonOAuthenticator(OAuthenticator):
         **OAuthenticator._deprecated_oauth_aliases,
     }
 
-    login_service = "CILogon"
+    login_handler = CILogonLoginHandler
 
+    user_auth_state_key = "cilogon_user"
     client_id_env = 'CILOGON_CLIENT_ID'
     client_secret_env = 'CILOGON_CLIENT_SECRET'
 
-    user_auth_state_key = "cilogon_user"
-
-    login_handler = CILogonLoginHandler
+    @default("login_service")
+    def _login_service_default(self):
+        return os.environ.get("LOGIN_SERVICE", "CILogon")
 
     cilogon_host = Unicode(
         os.environ.get("CILOGON_HOST") or "cilogon.org",
         config=True,
-        help="""""",
+        help="""
+        Used to determine the default values for `authorize_url`, `token_url`,
+        and `userdata_url`.
+        """,
     )
 
     @default("authorize_url")
@@ -107,9 +111,11 @@ def _username_claim_default(self):
         default_value=['openid', 'email', 'org.cilogon.userinfo', 'profile'],
         config=True,
         help="""
-        The OAuth scopes to request.
+        OAuth scopes to request.
+
+        `openid` and `org.cilogon.userinfo` is required.
 
-        See cilogon_scope.md for details. At least 'openid' is required.
+        Read more about CILogon scopes in https://www.cilogon.org/oidc.
         """,
     )
 

oauthenticator/generic.py

@@ -26,11 +26,9 @@ class GenericOAuthenticator(OAuthenticator):
         """,
     )
 
-    login_service = Unicode(
-        "OAuth 2.0",
-        config=True,
-        help="""""",
-    )
+    @default("login_service")
+    def _login_service_default(self):
+        return os.environ.get("LOGIN_SERVICE", "OAuth 2.0")
 
     claim_groups_key = Union(
         [Unicode(os.environ.get('OAUTH2_GROUPS_KEY', 'groups')), Callable()],
@@ -65,11 +63,12 @@ class GenericOAuthenticator(OAuthenticator):
         [Unicode(os.environ.get('OAUTH2_USERNAME_KEY', 'username')), Callable()],
         config=True,
         help="""
-        Userdata username key from returned json for USERDATA_URL.
+        When `userdata_url` returns a json response, the username will be taken
+        from this key.
 
         Can be a string key name or a callable that accepts the returned
-        json (as a dict) and returns the username.  The callable is useful
-        e.g. for extracting the username from a nested object in the
+        userdata json (as a dict) and returns the username.  The callable is
+        useful e.g. for extracting the username from a nested object in the
         response.
         """,
     )

oauthenticator/github.py

@@ -18,16 +18,22 @@ class GitHubOAuthenticator(OAuthenticator):
         **OAuthenticator._deprecated_oauth_aliases,
     }
 
-    login_service = "GitHub"
     user_auth_state_key = "github_user"
 
+    @default("login_service")
+    def _login_service_default(self):
+        return os.environ.get("LOGIN_SERVICE", "GitHub")
+
     @default("username_claim")
     def _username_claim_default(self):
         return "login"
 
     github_url = Unicode(
         config=True,
-        help="""""",
+        help="""
+        Used to determine the default values for `github_api`, `authorize_url`,
+        `token_url`, and `userdata_url`.
+        """,
     )
 
     @default("github_url")
@@ -64,14 +70,21 @@ def _github_url_default(self):
 
     github_api = Unicode(
         config=True,
-        help="""""",
+        help="""
+        URL to the GitHub REST API to use.
+
+        Determined based on `github_url` by default and may never need to be
+        explicitly set.
+        """,
     )
 
     @default("github_api")
     def _github_api_default(self):
         if self.github_url == "https://github.com":
             return "https://api.github.com"
         else:
+            # Only github.com has its api at api.github.com, enterprise server
+            # deployments has it in the same domain path under /api/v3
             return self.github_url + "/api/v3"
 
     @default("authorize_url")

oauthenticator/gitlab.py

@@ -21,25 +21,26 @@ def _api_headers(access_token):
 
 
 class GitLabOAuthenticator(OAuthenticator):
-    # see gitlab_scopes.md for details about scope config
-    # set scopes via config, e.g.
-    # c.GitLabOAuthenticator.scope = ['read_user']
-
     _deprecated_oauth_aliases = {
         "gitlab_group_whitelist": ("allowed_gitlab_groups", "0.12.0"),
         "gitlab_project_id_whitelist": ("allowed_project_ids", "0.12.0"),
         **OAuthenticator._deprecated_oauth_aliases,
     }
 
-    login_service = "GitLab"
     user_auth_state_key = "gitlab_user"
-
     client_id_env = 'GITLAB_CLIENT_ID'
     client_secret_env = 'GITLAB_CLIENT_SECRET'
 
+    @default("login_service")
+    def _login_service_default(self):
+        return os.environ.get("LOGIN_SERVICE", "GitLab")
+
     gitlab_url = Unicode(
         config=True,
-        help="""""",
+        help="""
+        Used to determine the default values for `gitlab_api`, `authorize_url`,
+        `token_url`.
+        """,
     )
 
     @default("gitlab_url")
@@ -71,21 +72,6 @@ def _default_gitlab_url(self):
 
         return gitlab_url
 
-    gitlab_api_version = CUnicode(
-        "4",
-        config=True,
-        help="""""",
-    )
-
-    @default('gitlab_api_version')
-    def _gitlab_api_version_default(self):
-        return os.environ.get('GITLAB_API_VERSION') or '4'
-
-    gitlab_api = Unicode(
-        config=True,
-        help="""""",
-    )
-
     @default("gitlab_api")
     def _default_gitlab_api(self):
         return f"{self.gitlab_url}/api/v{self.gitlab_api_version}"
@@ -98,6 +84,26 @@ def _authorize_url_default(self):
     def _token_url_default(self):
         return f"{self.gitlab_url}/oauth/token"
 
+    gitlab_api_version = CUnicode(
+        config=True,
+        help="""
+        Used to determine the default values for `gitlab_api`.
+
+        For details, see https://docs.gitlab.com/ee/api/rest/.
+        """,
+    )
+
+    @default("gitlab_api_version")
+    def _gitlab_api_version_default(self):
+        return os.environ.get("GITLAB_API_VERSION") or "4"
+
+    gitlab_api = Unicode(
+        config=True,
+        help="""
+        Used to determine the default value for `userdata_url`.
+        """,
+    )
+
     @default("userdata_url")
     def _userdata_url_default(self):
         return f"{self.gitlab_api}/user"

oauthenticator/globus.py

@@ -59,14 +59,20 @@ async def clear_tokens(self, user):
 
 
 class GlobusOAuthenticator(OAuthenticator):
-    """The Globus OAuthenticator handles both authorization and passing
-    transfer tokens to the spawner."""
+    """
+    The Globus OAuthenticator handles authentication, authorization, and sets
+    transfer tokens on the spawner environment variables via a pre_spawn_start
+    hook.
+    """
 
-    login_service = 'Globus'
     logout_handler = GlobusLogoutHandler
 
     user_auth_state_key = "globus_user"
 
+    @default("login_service")
+    def _login_service_default(self):
+        return os.environ.get("LOGIN_SERVICE", "Globus")
+
     @default("userdata_url")
     def _userdata_url_default(self):
         return "https://auth.globus.org/v2/oauth2/userinfo"
@@ -84,6 +90,7 @@ def _token_url_default(self):
         config=True,
         help="Globus URL to revoke live tokens.",
     )
+
     globus_groups_url = Unicode(
         "https://groups.api.globus.org/v2/groups/my_groups",
         config=True,
@@ -197,7 +204,8 @@ def _revoke_tokens_on_logout_default(self):
     )
 
     async def pre_spawn_start(self, user, spawner):
-        """Add tokens to the spawner whenever the spawner starts a notebook.
+        """
+        Add tokens to the spawner whenever the spawner starts a notebook.
         This will allow users to create a transfer client:
         globus-sdk-python.readthedocs.io/en/stable/tutorial/#tutorial-step4
         """

oauthenticator/google.py

@@ -21,9 +21,9 @@ class GoogleOAuthenticator(OAuthenticator, GoogleOAuth2Mixin):
 
     user_auth_state_key = "google_user"
 
-    @default("authorize_url")
-    def _authorize_url_default(self):
-        return "https://accounts.google.com/o/oauth2/v2/auth"
+    @default("login_service")
+    def _login_service_default(self):
+        return os.environ.get("LOGIN_SERVICE", "Google")
 
     @default("scope")
     def _scope_default(self):
@@ -33,9 +33,15 @@ def _scope_default(self):
     def _username_claim_default(self):
         return "email"
 
+    @default("authorize_url")
+    def _authorize_url_default(self):
+        return "https://accounts.google.com/o/oauth2/v2/auth"
+
     google_api_url = Unicode(
         config=True,
-        help="""""",
+        help="""
+        Used to determine the default values for `token_url` and `userdata_url`.
+        """,
     )
 
     @default("google_api_url")
@@ -62,14 +68,20 @@ def _userdata_url_default(self):
         config=True,
         help="""
         Service account keys to use with each domain, see https://developers.google.com/admin-sdk/directory/v1/guides/delegation
+
+        Required if and only if `allowed_google_groups` or `admin_google_groups`
+        is configured.
         """,
     )
 
     gsuite_administrator = Dict(
         Unicode(),
         config=True,
         help="""
-        Username of a G Suite Administrator for the service account to act as
+        Username of a G Suite Administrator for the service account to act as.
+
+        Required if and only if `allowed_google_groups` or `admin_google_groups`
+        is configured.
         """,
     )
 
@@ -85,6 +97,9 @@ def _userdata_url_default(self):
         config=True,
         help="""
         Allow members of selected Google groups to sign in.
+
+        Use of this requires configuration of `gsuite_administrator` and
+        `google_service_account_keys`.
         """,
     )
 
@@ -97,6 +112,9 @@ def _userdata_url_default(self):
 
         If this is set and a user isn't part of one of these groups or listed in
         `admin_users`, a user signing in will have their admin status revoked.
+
+        Use of this requires configuration of `gsuite_administrator` and
+        `google_service_account_keys`.
         """,
     )
 
@@ -226,7 +244,7 @@ def _service_client_credentials(self, scopes, user_email_domain):
         except:
             raise ImportError(
                 "Could not import google.oauth2's service_account,"
-                "you may need to run pip install oauthenticator[googlegroups] or not declare google groups"
+                "you may need to run 'pip install oauthenticator[googlegroups]' or not declare google groups"
             )
 
         gsuite_administrator_email = "{}@{}".format(
@@ -250,7 +268,7 @@ def _service_client(self, service_name, service_version, credentials, http=None)
         except:
             raise ImportError(
                 "Could not import googleapiclient.discovery's build,"
-                "you may need to run pip install oauthenticator[googlegroups] or not declare google groups"
+                "you may need to run 'pip install oauthenticator[googlegroups]' or not declare google groups"
             )
 
         self.log.debug(