github-app-user-auth

为JupyterHub提供从GitHub的细粒度推送访问。

目标

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

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

1. 创建一个针对远程服务（JupyterHub、HPC集群等）的特定GitHub应用。用户和GitHub组织管理员可以为此GitHub应用提供细粒度、仓库级别的访问权限 - 用户只能推送到已安装应用的仓库。
2. 一个命令行工具（github-app-user-auth），允许特定用户临时授权对选定仓库的推送访问权限 - 令牌在8小时后过期。

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

安装

您可以从PyPI安装github-app-user-auth。

pip install github-app-user-auth

GitHub应用配置

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

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

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

4. 在“仓库权限”下，为“内容”选择“读/写”。这将使用户通过应用程序认证时恰好有足够的权限从仓库推送和拉取。

5. 在“此GitHub应用程序可安装的位置”下，选择“任何账户”。这将使用户能够将内容推送到他们自己的用户仓库或其他组织仓库，而不仅仅是拥有此GitHub应用程序的用户或组织的仓库。

6. 保存应用程序信息页面中提供的客户端ID。您将在客户端需要此ID。同时也要保存公共链接，因为用户将需要使用它来授予对特定仓库的访问权限。

客户端配置

1. github-app-user-auth使用git-credentials-store通过写入到/tmp/github-app-git-credentials文件来提供适当的认证。这确保我们不会覆盖某人可能正在使用的默认~/.git-credentials文件。git必须配置为使用新文件。

   您可以将以下片段放入/etc/gitconfig（对于容器）或~/.gitconfig

   [credential]
       helper = store --file=/tmp/github-app-git-credentials
   

   或者，您可以运行以下命令（这将将其放入~/.gitconfig）

   git config --global credential.helper "store --file=/tmp/github-app-git-credentials"
   

2. github-app-user-auth需要知道创建的GitHub应用程序的“客户端ID”才能执行认证。这可以通过环境变量GITHUB_APP_CLIENT_ID设置，或者当用户使用它进行认证时作为命令行参数--client-id传递给github-app-user-auth脚本。

用法

授予对GitHub应用程序的访问权限

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

考虑到常见的使用模式，您仅从特定的托管服务向有限数量的仓库推送，这应该不会太繁琐。

认证到GitHub

托管服务必须安装github-app-user-auth。

1. 打开终端，并输入github-app-user-auth。
2. 它应该提供一个链接供您访问，并在打开链接时输入一个代码。打开链接，输入代码。
3. 在网页上授予对设备的访问权限，您就完成了！

认证有效期为8小时，一旦过期，需要重复此过程。未来，我们可能有一个网络应用程序或其他过程来简化这一过程。然而，保持会话长度有限也有助于提高安全性。

替代方案

1. 为托管服务（JupyterHub、HPC集群等）创建一个特定的SSH密钥，并将其添加到您的GitHub账户中。如果密钥没有密码，这非常不安全 - 任何能够一次窃取您的密钥的人都可以保留它，并在他们想要的时候使用它。即使有密码，密钥也可能会在使用时被盗取密码。此外，也没有办法限制它可以推送到哪些仓库，这是一个大问题。

2. 创建一个个人访问令牌并使用它。这与SSH密钥相比略不安全，因为一旦被窃取，它也可以代表你发出请求！此外，也无法限制可以推送到的仓库。

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