Jupyter Notebook与Keycloak集成实现用户登录方案咨询

前提说明 #

Jupyter Notebook本身是单用户服务，若你已配置好JupyterHub与Keycloak的集成，更推荐通过JupyterHub统一管理Notebook访问（所有Notebook实例通过Hub的Keycloak认证）。若需单独为单用户Notebook配置Keycloak登录，可按以下步骤操作：

1. 安装OIDC认证扩展 #

使用pip安装jupyter-oidc扩展：

pip install jupyter-oidc

若使用conda环境，可执行：

conda install -c conda-forge jupyter-oidc

2. 在Keycloak中配置客户端 #

• 登录Keycloak控制台，进入目标Realm，创建新客户端：
  • 客户端类型选择公共
  • 设置重定向URI为你的Notebook访问地址 + /hub/oauth_callback（例如：http://your-notebook-domain:8888/hub/oauth_callback）
• 从Realm的「OpenID Endpoint Configuration」中获取以下端点信息：授权端点、令牌端点、用户信息端点

3. 配置Jupyter Notebook #

• 若未生成过Notebook配置文件，先执行：

  jupyter notebook --generate-config
  

• 打开生成的jupyter_notebook_config.py文件，添加以下配置（替换为你的Keycloak信息）：

  # 启用OIDC认证器
  c.NotebookApp.authenticator_class = 'jupyter_oidc.OIDCAuthenticator'
  
  # Keycloak客户端配置
  c.OIDCAuthenticator.client_id = '你的Keycloak客户端ID'
  c.OIDCAuthenticator.client_secret = '你的Keycloak客户端密钥（公共客户端可留空）'
  
  # OIDC端点信息
  c.OIDCAuthenticator.authorization_url = 'Keycloak授权端点地址'
  c.OIDCAuthenticator.token_url = 'Keycloak令牌端点地址'
  c.OIDCAuthenticator.userdata_url = 'Keycloak用户信息端点地址'
  
  # 用户标识字段（可根据需求选preferred_username/email等）
  c.OIDCAuthenticator.username_key = 'preferred_username'
  
  # 回调地址（需与Keycloak客户端配置一致）
  c.OIDCAuthenticator.redirect_uri = '你的Notebook回调地址'
  

• 注意：若Keycloak客户端为公共类型，需将client_secret设为空字符串，同时确保Keycloak客户端的「Access Type」设置为public

4. 验证集成效果 #

启动Jupyter Notebook：

jupyter notebook

访问Notebook地址后，会自动跳转至Keycloak登录页面，登录成功后即可进入Notebook界面。

常见问题提示 #

• 若出现认证失败，优先检查Keycloak客户端的重定向URI是否与配置一致
• 若用户登录后无访问权限，确认Keycloak中该用户的角色权限是否允许访问Notebook服务
• 已配置JupyterHub的场景下，建议通过Hub管理Notebook实例，避免重复配置单用户认证

内容的提问来源于stack exchange，提问作者coding