gh-scoped-creds

从JupyterHub或HPC系统提供对GitHub的精确范围推送访问。

目标

1. 允许JupyterHub上的用户仅授予对特定存储库的推送访问权限，而不是他们可以访问的所有存储库。
2. 不要在磁盘上存储长期凭据（如个人访问令牌或ssh密钥），因为这些凭据将来可能会被存档或落入错误的手中。
3. 允许GitHub组织管理员可见性和控制用户从远程系统（如JupyterHub或共享集群）推送到的存储库，而在远程系统中的其他管理员可能能够访问具有存储库推送权限的用户的文件。这对于供应链安全有严重的影响，因为凭据可能会被盗或丢失，严重漏洞会被推送到存储库。

这些目标通过以下方式实现

1. 为远程服务（JupyterHub、HPC集群等）创建一个特定的 GitHub 应用。用户和GitHub组织管理员可以为该GitHub应用提供细粒度、仓库级别的访问权限 - 用户只能向已安装该应用的仓库推送。
2. 一个命令行工具（gh-scoped-creds），允许特定用户临时授权对所选仓库的推送访问 - 令牌8小时后过期。
3. 一个IPython魔法（%ghscopedcreds），为在Jupyter Notebook内部调用gh-scoped-creds提供了一个方便的包装器。

将来，还可能提供可选的Web应用来帮助进行身份验证。

安装

您可以从PyPI安装gh-scoped-creds。

pip install gh-scoped-creds

GitHub应用配置

1. 为服务（JupyterHub、HPC集群等）创建一个 GitHub 应用。您可以在您的 个人账户 下创建它，或者更合适的是在GitHub组织账户下创建（转到设置 -> 开发者设置 -> GitHub应用 -> 从组织的GitHub页面创建新的GitHub应用）。

2. 给它一个描述性的名称和描述，因为您的用户在认证时会看到这些。提供链接到一个描述您服务的页面（如果您使用的是JupyterHub，这可以是您的JupyterHub URL）。

3. 选择“启用设备流”，因为我们依赖于 设备流认证方法。

4. 禁用webhooks（取消选中“Webhooks”下的“Active”复选框）。所有其他文本框都可以留空。

5. 在“仓库权限”下，选择“内容”的“读取和写入”。这将使用户通过应用认证时仅获得足够的权限来推送和拉取仓库。

6. 在“此GitHub应用可以安装在哪里？”下，选择“任何账户”。这将使用户能够推送自己的用户仓库或其他组织仓库，而不仅仅是拥有此GitHub应用的用户或组织的仓库。

7. 保存应用信息页面中提供的Client ID。您需要在客户端使用它。也要保存Public link，因为用户需要使用它来授予对特定仓库的访问权限。

客户端配置

1. gh-scoped-creds需要知道创建的GitHub应用的“Client ID”来进行认证。这可以通过环境变量GH_SCOPED_CREDS_CLIENT_ID设置，或者当用户使用它进行认证时，作为命令行参数--client-id传递给gh-scoped-creds脚本。

2. 用户需要明确授予从特定JupyterHub或HPC系统推送的仓库的访问权限（请参阅下文的使用部分）。管理员可以将GH_SCOPED_CREDS_APP_URL环境变量设置为告知用户去哪里管理此访问的地方 - gh-scoped-creds会在认证后打印出此信息。

使用

授予GitHub应用的访问权限

用户首先需要访问GitHub应用的公开页面，并在他们想要推送的仓库的个人账户和组织中“安装”应用。我们 强烈建议只允许对选定的仓库进行访问，并明确选择此托管服务（JupyterHub、HPC集群等）应能推送到的仓库。您可以在之后修改此列表，以确保您只授予所需的权限。

鉴于常见的使用模式，您通常只从特定的托管服务推送有限数量的仓库，这应该不会太繁琐。

管理员可以将GH_SCOPED_CREDS_APP_URL设置为GitHub应用的Public Link，以便用户更容易知道去哪里。

认证到GitHub

托管服务必须安装gh-scoped-creds。

1. 打开终端，输入gh-scoped-creds。如果你在一个基于Python的Jupyter Notebook中，你也可以这样做

   import gh_scoped_creds
   
   %ghscopedcreds
   

   这将为你提供一个新窗口打开页面，并且方便地复制你需要粘贴到新窗口中的代码。

   如果你在一个非容器化系统（如HPC）上，你必须显式地使用--git-credentials-path指定放置凭据文件的路径。前面提到的gitconfig配置中也必须使用相同的路径。

2. 它应该给你一个要去的链接，以及打开链接时要在网页中输入的代码。打开链接，在那里输入代码（页面接受粘贴，因此你可以从输出中复制它）。

3. 在网页中授权设备，你就算完成了！

认证有效期为8小时，一旦过期，则需要重复此过程。未来，我们可能有一个网络应用程序或其他进程来减轻这种痛苦。然而，将此会话的长度限制在很小的范围内也极大地有助于提高安全性。

替代方案

1. 为托管服务（JupyterHub、HPC集群等）创建一个专门的ssh密钥，并将其添加到你的GitHub账户中。如果密钥没有密码，这是非常不安全的 - 任何人一旦窃取了你的密钥就可以保留并随时使用。即使有密码，密钥在使用时也可能会被盗取密码，且无法限制可以推送到的存储库，这是一个大问题。

2. 创建一个个人访问令牌并使用它。与ssh密钥相比，这稍微有点不安全，因为被盗取后它也可以代表你发出请求！也没有办法限制可以推送到的存储库。

3. 为每个你想从托管服务推送到的存储库创建一个GitHub部署密钥。虽然这让你可以控制哪些存储库可以访问此ssh密钥，但它仍然长期存储在风险中，并且可能被窃取。