身份验证和授权#

身份验证关乎身份，而授权关乎权限。在本节中，你将学习如何通过选择和配置 JupyterHub Authenticator 类来配置这两者。

例如，你可以将 JupyterHub 配置为将身份验证和授权委托给 GitHubOAuthenticator。它允许用户使用 GitHub 帐户登录，其中可能只允许少数特定用户以及属于特定 GitHub 组织的其他用户访问。

在使用外部身份提供商配置身份验证之前，你必须设置 HTTPS。

有用的理解#

Authenticator 类#

默认情况下，Z2JH 部署使用 jupyterhub.auth.DummyAuthenticator JupyterHub authenticator 类，它允许任何人使用任何用户名和密码登录。这只应用于初始测试目的。

你应该决定使用哪个 [jupyterhub authenticator 类]。Hub 镜像通过已安装的 Python 包提供了几个这样的类，下面将介绍其中几个。

配置系统#

首先，我们应该通过此 Helm chart 的 hub.config 配置来配置 JupyterHub 以使用我们选择的 authenticator 类以及 authenticator 类本身。

常规配置#

由于所有 authenticator 类都派生自 jupyterhub.auth.Authenticator 基类，它们共享一些配置选项。以下是基类的一些常见配置选项。

allowed_users / admin_users #

除了这个，一些 authenticator 类可能有专门的逻辑来授权用户。

hub:
  config:
    Authenticator:
      admin_users:
        - user1
        - user2
      allowed_users:
        - user3
        - user4
    # ...
    DummyAuthenticator:
      password: a-shared-secret-password
    JupyterHub:
      authenticator_class: dummy

在上面的配置中，我们配置了三件事

指示 JupyterHub 使用虚拟 authenticator 登录（仅适用于测试目的），
任何人都将能够使用用户名 user1-4 和密码 a-shared-secret-password 登录
user1 和 user2 将具有管理员权限，而 user3 和 user4 将是普通用户。

auto_login #

例如，如果你已配置使用 GitHub 进行身份验证，页面 /hub/login 将显示一个橙色按钮，用户需要按下该按钮进行登录。如果你想绕过此屏幕并直接将用户发送到 GitHub 登录页面，你可以将 auto_login 设置为 true。

hub:
  config:
    Authenticator:
      auto_login: true

enable_auth_state #

如果你希望 JupyterHub 持久化在登录过程中收到的通常是敏感的信息，你需要启用它。

hub:
  config:
    Authenticator:
      enable_auth_state: true

有关身份验证状态的更多信息，请参阅 JupyterHub 自己关于身份验证状态的文档。

注意

身份验证状态的加密和解密需要一个加密密钥。

自 1.0.0 版起，这将自动生成，无需手动设置。

如果你希望重置生成的密钥，你可以在通常名为 hub 的 k8s Secret 上使用 kubectl edit，并移除 k8s Secret 中的 hub.config.CryptKeeper.keys 条目，然后执行新的 helm upgrade。

要手动设置加密密钥，你可以这样做。

hub:
  config:
    CryptKeeper:
      keys:
        - 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

配置 authenticator 类#

下面我们提供了一些常用身份验证类的配置示例。有关它们的更多详细信息，请参阅身份验证类自己的文档。

基于 OAuth2 的身份验证#

JupyterHub 的 oauthenticator 项目支持让你的用户通过第三方 OAuth2 身份提供商（如 GitHub、Google 和 CILogon）进行身份验证。所有这些都需要一个 OAuth2 客户端 ID 和客户端密钥。

有关如何获取客户端 ID 和客户端密钥的详细信息，请参阅 oauthenticator 的文档。

GitHub#

警告

此文档可能最近没有更新。因此，请仅将其用作官方 GitHubOAuthenticator 文档的补充。

展望未来，我们的目标是确保 OAuthenticator 项目中有好的文档，并引用该文档，而不是在此项目中也维护类似的文档。

GitHub 是最大的 git 仓库托管服务。在 GitHub 上创建帐户是免费的，设置 OAuth 凭据以便用户可以使用其 GitHub 用户名/密码进行身份验证也相对简单。

要在 GitHub 上创建 OAuth 凭据，请按照以下步骤操作

点击你的个人资料图片 -> 设置 -> 开发者设置
确保你在“OAuth Apps”选项卡上，然后点击“New OAuth App”
填写表格（你需要你的 hub 地址）并生成你的 ID/密钥。

要启用 GitHub 身份验证，你的 config.yaml 应包含以下配置

hub:
  config:
    GitHubOAuthenticator:
      client_id: your-client-id
      client_secret: your-client-secret
      oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback
    JupyterHub:
      authenticator_class: github

确保 oauth_callback_url 与你在 GitHub 中设置的 URL 匹配。

要将访问权限限制为一个或多个 GitHub 组织的成员，请使用这些部分修改你之前的配置。

hub:
  config:
    GitHubOAuthenticator:
      allowed_organizations:
        - my-github-organization
      scope:
        - read:org

如果你想将访问权限限制到 GitHub 组织内的特定团队，请使用以下语法

hub:
  config:
    GitHubOAuthenticator:
      allowed_organizations:
        - my-github-organization:my-team
      scope:
        - read:org

关于范围的选择

如果你的 allowed_organizations 配置中只列出整个组织而不是特定团队，并且用户将其组织成员身份公开，那么较窄的范围 read:user 就足以使其正常工作。

更广泛的范围 read:org 没有 read:user 的限制，但需要 allowed_organizations 中列出的 GitHub 组织的管理员进行一次性批准。组织用户可以按照 GitHub 上的文档请求此类批准。

有关 GitHub 范围的详细信息，请参阅 GitHub 的文档。

Google#

警告

此文档可能最近没有更新。因此，请仅将其用作官方 GoogleOAuthenticator 文档的补充。

展望未来，我们的目标是确保 OAuthenticator 项目中有好的文档，并引用该文档，而不是在此项目中也维护类似的文档。

Google 身份验证被许多大学使用（它是“G Suite”的一部分）。

如果你的机构是 G Suite 客户，集成了 Gmail、日历和云端硬盘等 Google 服务，你可以使用 Google 身份验证来验证 JupyterHub 的用户。

登录 Google API 控制台。
选择一个项目 > 创建一个项目… 并设置“项目名称”。这是一个仅在控制台中显示的短语。如果你已经创建了一个项目，可以跳过此步骤。
在顶部的搜索字段中输入“Credentials”，然后点击进入 Credentials API。
点击“创建凭据”，然后选择“OAuth 客户端 ID”。选择“应用类型” > “Web 应用”。
为你的 JupyterHub 实例输入一个名称。你可以给它一个描述性的名称，或者将其设置为 hub 的主机名。
将“已获授权的 JavaScript 来源”设置为你的 hub 的 URL。
将“已授权的重定向 URI”设置为你的 hub 的 URL，后跟 /hub/oauth_callback。例如，https://your-jupyterhub-domain/hub/oauth_callback。
当你点击“创建”时，控制台将生成并显示客户端 ID 和客户端密钥。保存这些值。
在顶部的搜索字段中输入“consent screen”，然后点击进入 OAuth 同意屏幕。在这里，你将自定义用户首次登录 JupyterHub 实例时看到的内容。完成后点击保存。
更新你的 Helm chart 的配置 (config.yaml) 如下所示。

hub:
  config:
    GoogleOAuthenticator:
      client_id: your-client-id.apps.googleusercontent.com
      client_secret: your-client-secret
      oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback
      hosted_domain:
        - your-university.edu
      login_service: Your university
    JupyterHub:
      authenticator_class: google

oauth_callback_url 键设置为你之前指定的已授权重定向 URI。将 hosted_domain 设置为你的机构的域名。 login_service 的值是你的机构的描述性术语，用于提醒用户他们正在使用哪个帐户登录。

CILogon#

警告

此文档可能最近没有更新。因此，请仅将其用作官方 CILogonOAuthenticator 文档的补充。

展望未来，我们的目标是确保 OAuthenticator 项目中有好的文档，并引用该文档，而不是在此项目中也维护类似的文档。

请参阅 CyberInfrastructure Logon 的网站以获取有关 CILogon 管理的身份类型的更多信息。

hub:
  config:
    CILogonOAuthenticator:
      client_id: your-client-id
      client_secret: your-client-secret
      oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback
    JupyterHub:
      authenticator_class: cilogon

Globus#

警告

此文档可能最近没有更新。因此，请仅将其用作官方 GlobusOAuthenticator 文档的补充。

展望未来，我们的目标是确保 OAuthenticator 项目中有好的文档，并引用该文档，而不是在此项目中也维护类似的文档。

Globus Auth 是一个基础身份和访问管理平台服务，旨在满足科学和工程界的独特需求。Globus 提供基于云的服务，用于可靠地移动、共享、发布和发现数据，无论你的文件是在超级计算机、实验室集群、磁带存档、公有云还是你自己的笔记本电脑上。在此处启动一个 Globus 应用！

hub:
  config:
    GlobusOAuthenticator:
      client_id: your-client-id
      client_secret: your-client-secret
      oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback
      identity_provider: your-university.edu
    JupyterHub:
      authenticator_class: globus

Azure Active Directory#

警告

此文档可能最近没有更新。因此，请仅将其用作官方 AzureAdOAuthenticator 文档的补充。

展望未来，我们的目标是确保 OAuthenticator 项目中有好的文档，并引用该文档，而不是在此项目中也维护类似的文档。

Azure Active Directory 是 Microsoft Azure 的身份提供商。除了需要 OAuth2 客户端 ID 和客户端密钥外，你还需要一个租户 ID。

hub:
  config:
    AzureAdOAuthenticator:
      client_id: your-client-id
      client_secret: your-client-secret
      oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback
      tenant_id: your-tenant-id
    JupyterHub:
      authenticator_class: azuread

Auth0#

警告

此文档可能最近没有更新。因此，请仅将其用作官方 Auth0OAuthenticator 文档的补充。

展望未来，我们的目标是确保 OAuthenticator 项目中有好的文档，并引用该文档，而不是在此项目中也维护类似的文档。

Auth0 是一家商业身份管理提供商。

hub:
  config:
    Auth0OAuthenticator:
      client_id: client-id-from-auth0-here
      client_secret: client-secret-from-auth0-here
      oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback
      auth0_domain: prod-8ua-1yy9.auth0.com
      scope:
        - openid
        - email
    JupyterHub:
      authenticator_class: auth0

GenericOAuthenticator - OpenID Connect#

警告

此文档可能最近没有更新。因此，请仅将其用作官方 GenericOAuthenticator 文档的补充。

展望未来，我们的目标是确保 OAuthenticator 项目中有好的文档，并引用该文档，而不是在此项目中也维护类似的文档。

OpenID Connect 是 OAuth 2.0 协议之上的一个身份层，由各种服务器和服务实现。虽然 oauthentiator 不支持 OpenID Connect 端点发现，但你仍然可以通过在 GenericOAuthenticator 类中指定所有端点来配置 JupyterHub 以使用 OpenID Connect 提供商进行身份验证。

KeyCloak#

警告

此文档可能最近没有更新。因此，请仅将其用作官方 GenericOAuthenticator 文档的补充。

展望未来，我们的目标是确保 OAuthenticator 项目中有好的文档，并引用该文档，而不是在此项目中也维护类似的文档。

KeyCloak 是一个开源的身份管理提供商，你可以自己托管。以下是如何配置 GenericOAuthenticator 类以对 KeyCloak 服务器（版本 17 或更高版本）进行身份验证的示例。

要配置 OpenID Connect 客户端，请参阅 KeyCloak 自己的文档。

hub:
  config:
    GenericOAuthenticator:
      client_id: your-client-id
      client_secret: your-client-secret
      oauth_callback_url: https://your-jupyterhub-domain/hub/oauth_callback
      authorize_url: https://${host}/realms/${realm}/protocol/openid-connect/auth
      token_url: https://${host}/realms/${realm}/protocol/openid-connect/token
      userdata_url: https://${host}/realms/${realm}/protocol/openid-connect/userinfo
      login_service: keycloak
      username_claim: preferred_username
      userdata_params:
        state: state
      # Allow all Keycloak users
      allow_all: true
      admin_users:
        - admin
    JupyterHub:
      authenticator_class: generic-oauth

LDAP 和 Active Directory#

警告

此文档可能最近没有更新。因此，请仅将其用作官方 LDAPAuthenticator 文档的补充。

展望未来，我们的目标是确保 OAuthenticator 项目中有好的文档，并引用该文档，而不是在此项目中也维护类似的文档。

JupyterHub 支持 LDAP 和 Active Directory 身份验证。请阅读 ldapauthenticator 文档以获取可用参数的完整说明。

只需要 server_address 和 bind_dn_template，因此最小配置如下所示。

hub:
  config:
    JupyterHub:
      authenticator_class: ldapauthenticator.LDAPAuthenticator
    LDAPAuthenticator:
      bind_dn_template:
        - cn={username},ou=edir,ou=people,ou=EXAMPLE-UNIT,o=EXAMPLE
      server_address: ldap.EXAMPLE.org

下面提供了另一个示例，等同于 ldapauthenticator README 中给出的示例。

hub:
  config:
    JupyterHub:
      authenticator_class: ldapauthenticator.LDAPAuthenticator
    LDAPAuthenticator:
      allowed_groups:
        - cn=researcher,ou=groups,dc=wikimedia,dc=org
        - cn=operations,ou=groups,dc=wikimedia,dc=org
      bind_dn_template:
        - uid={username},ou=people,dc=wikimedia,dc=org
        - uid={username},ou=developers,dc=wikimedia,dc=org
      escape_userdn: false
      lookup_dn: true
      lookup_dn_search_filter: ({login_attr}={login})
      lookup_dn_search_password: secret
      lookup_dn_search_user: ldap_search_user_technical_account
      lookup_dn_user_dn_attribute: cn
      server_address: ad.EXAMPLE.org
      user_attribute: sAMAccountName
      user_search_base: ou=people,dc=wikimedia,dc=org

身份验证和授权#

有用的理解#

Authenticator 类#

配置系统#

常规配置#

allowed_users / admin_users#

auto_login#

enable_auth_state#

配置 authenticator 类#

基于 OAuth2 的身份验证#

GitHub#

Google#

CILogon#

Globus#

Azure Active Directory#

Auth0#

GenericOAuthenticator - OpenID Connect#

KeyCloak#

LDAP 和 Active Directory#

本页

allowed_users / admin_users #

auto_login #

enable_auth_state #