diff --git a/content/en/security-compliance/oidc/gitlab.md b/content/en/security-compliance/oidc/gitlab.md new file mode 100644 index 00000000..2c8ead1f --- /dev/null +++ b/content/en/security-compliance/oidc/gitlab.md @@ -0,0 +1,160 @@ +--- +title: "GitLab" +description: "Configure GitLab as an OpenID Connect identity provider for RustFS Console single sign-on." +--- + +RustFS integrates with **GitLab** through the OpenID Connect (OIDC) Authorization Code Flow. The examples on this page use the default RustFS provider ID, `default`. + +## Requirements + +Before you begin, prepare: + +- An [installed GitLab instance](https://about.gitlab.com/install/) and access to its Admin area. +- A RustFS deployment with a public HTTPS Console origin. +- A RustFS policy to assign to GitLab users. The examples use `consoleAdmin`; use a policy with only the permissions your users require in production. + +## Overview + +The browser login flow is: + +1. RustFS sends an authorization-code request with a Proof Key for Code Exchange (PKCE) S256 challenge. +2. GitLab authenticates the user and redirects the browser to RustFS with `code` and `state`. +3. RustFS exchanges the code at the GitLab token endpoint. +4. RustFS verifies the ID token signature, issuer, audience, expiry, and nonce. +5. RustFS assigns the configured local Identity and Access Management (IAM) policy and issues temporary credentials for the Console session. + +GitLab authenticates the user, while RustFS policies authorize S3 and administration operations. + +The examples use the following values. Replace the hostnames and client secret for your environment: + +| Setting | Example | +| --- | --- | +| GitLab issuer | `https://gitlab.example.com` | +| GitLab application ID | `` | +| Public RustFS origin | `https://rustfs.example.com` | +| RustFS callback URL | `https://rustfs.example.com/rustfs/admin/v3/oidc/callback/default` | + +## Configuration + +### GitLab configuration + +#### Create the OAuth application + +1. Sign in to GitLab as an administrator. +2. Open **Admin Area**, select **Applications**, and select **New application**. +3. Enter `RustFS OIDC` as the application name. +4. Set **Redirect URI** to the exact RustFS callback URL: + + ```text + https://rustfs.example.com/rustfs/admin/v3/oidc/callback/default + ``` + +5. Enable **Confidential**. +6. Enable **Trusted** to skip the user authorization prompt for this instance-wide application. +7. Select the `openid`, `profile`, and `email` scopes. +8. Save the application, then copy the generated application ID and secret. + +See the [GitLab OAuth provider documentation](https://docs.gitlab.com/integration/oauth_provider/) for details about administering applications. + +![GitLab Admin area showing the RustFS OIDC instance OAuth application as trusted and confidential](./images/gitlab-oidc-configuration.png) + +:::note[Test environment shown] + +The screenshot shows an HTTP callback URL from a test environment. Use the public HTTPS callback URL for your RustFS deployment. + +::: + +### RustFS configuration + +Configure the GitLab provider through environment variables. + +#### Configure with environment variables + +Add the GitLab provider and public browser origin to the RustFS service environment: + +```ini title="/etc/default/rustfs" +RUSTFS_BROWSER_REDIRECT_URL="https://rustfs.example.com" + +RUSTFS_IDENTITY_OPENID_ENABLE=on +RUSTFS_IDENTITY_OPENID_CONFIG_URL="https://gitlab.example.com" +RUSTFS_IDENTITY_OPENID_CLIENT_ID="" +RUSTFS_IDENTITY_OPENID_CLIENT_SECRET="" +RUSTFS_IDENTITY_OPENID_SCOPES="openid,profile,email" +RUSTFS_IDENTITY_OPENID_REDIRECT_URI="https://rustfs.example.com/rustfs/admin/v3/oidc/callback/default" +RUSTFS_IDENTITY_OPENID_REDIRECT_URI_DYNAMIC=off +RUSTFS_IDENTITY_OPENID_DISPLAY_NAME="GitLab" +RUSTFS_IDENTITY_OPENID_EMAIL_CLAIM="email" +RUSTFS_IDENTITY_OPENID_USERNAME_CLAIM="preferred_username" +RUSTFS_IDENTITY_OPENID_ROLE_POLICY="consoleAdmin" +``` + +Restart RustFS after applying the configuration. + +`RUSTFS_BROWSER_REDIRECT_URL` must contain the public scheme and authority without a path. It controls the Console success redirect and logout fallback URL. The provider callback URL must exactly match the URL registered in GitLab. + +:::warning[Limit the assigned policy] + +`RUSTFS_IDENTITY_OPENID_ROLE_POLICY` assigns the same RustFS policy to every user who signs in through this provider. Replace `consoleAdmin` with a policy that grants only the permissions required by your GitLab users. + +::: + +For a reverse proxy or load balancer, preserve the callback query string and route the authorize and callback requests to the same RustFS node. The in-flight OIDC `state` is local to that node. + +## Verification + +### Verify GitLab discovery + +Query the GitLab discovery document: + +```bash +curl -fsS "https://gitlab.example.com/.well-known/openid-configuration" | jq '{ + issuer, + authorization_endpoint, + token_endpoint, + jwks_uri, + scopes_supported, + code_challenge_methods_supported +}' +``` + +Confirm that: + +- `issuer` is `https://gitlab.example.com`. +- `authorization_endpoint`, `token_endpoint`, and `jwks_uri` are present. +- `scopes_supported` includes `openid`, `profile`, and `email`. +- `code_challenge_methods_supported` includes `S256`. + +### Verify the RustFS provider + +After restarting RustFS, check that the provider is available: + +```bash +curl -fsS "https://rustfs.example.com/rustfs/admin/v3/oidc/providers" | jq +``` + +The response should include the `default` provider with the display name `GitLab`. + +### Test Console login + +Open the RustFS Console and select **GitLab**, or open the authorization endpoint directly: + +```text +https://rustfs.example.com/rustfs/admin/v3/oidc/authorize/default +``` + +![RustFS Console login page showing the Login with GitLab option](./images/rustfs-console-gitlab-oidc.png) + +Verify the complete flow: + +1. The browser redirects to GitLab. +2. The user signs in and authorizes the application when prompted. +3. GitLab redirects to the RustFS callback URL with `code` and `state`. +4. RustFS validates the ID token and creates the Console session. +5. The Console opens with the configured RustFS policy. + +If GitLab reports a redirect URI mismatch, confirm that the URI registered in the GitLab application exactly matches `RUSTFS_IDENTITY_OPENID_REDIRECT_URI`. + +## Next steps + +- Review [users, groups, and policies](../iam/policies.md) before selecting the policy assigned to GitLab users. +- Review the [Console security notes](/administration/console) before exposing the login endpoint publicly. \ No newline at end of file diff --git a/content/en/security-compliance/oidc/images/gitlab-oidc-configuration.png b/content/en/security-compliance/oidc/images/gitlab-oidc-configuration.png new file mode 100644 index 00000000..4284d6a2 Binary files /dev/null and b/content/en/security-compliance/oidc/images/gitlab-oidc-configuration.png differ diff --git a/content/en/security-compliance/oidc/images/rustfs-console-gitlab-oidc.png b/content/en/security-compliance/oidc/images/rustfs-console-gitlab-oidc.png new file mode 100644 index 00000000..9704a1e8 Binary files /dev/null and b/content/en/security-compliance/oidc/images/rustfs-console-gitlab-oidc.png differ diff --git a/content/en/security-compliance/oidc/index.md b/content/en/security-compliance/oidc/index.md index 676df9e9..0d784b7a 100644 --- a/content/en/security-compliance/oidc/index.md +++ b/content/en/security-compliance/oidc/index.md @@ -32,6 +32,7 @@ Use a dedicated client for RustFS and grant each identity only the policies it r ## Provider guides - [Configure Keycloak](/security-compliance/oidc/keycloak) as an OIDC provider for the RustFS Console. +- [Configure GitLab](/security-compliance/oidc/gitlab) as an OIDC provider for the RustFS Console. ## Next steps diff --git a/content/en/security-compliance/oidc/meta.json b/content/en/security-compliance/oidc/meta.json index 853c25c4..ca4090f4 100644 --- a/content/en/security-compliance/oidc/meta.json +++ b/content/en/security-compliance/oidc/meta.json @@ -1,4 +1,4 @@ { "title": "OIDC", - "pages": ["keycloak"] + "pages": ["keycloak", "gitlab"] } \ No newline at end of file diff --git a/content/zh/security-compliance/oidc/gitlab.md b/content/zh/security-compliance/oidc/gitlab.md new file mode 100644 index 00000000..d72bfa9a --- /dev/null +++ b/content/zh/security-compliance/oidc/gitlab.md @@ -0,0 +1,160 @@ +--- +title: "GitLab" +description: "将 GitLab 配置为 OpenID Connect 身份提供商，实现 RustFS 控制台单点登录。" +--- + +RustFS 通过 OpenID Connect（OIDC）授权码流程与 **GitLab** 集成。本页示例使用 RustFS 默认提供商 ID `default`。 + +## 前置条件 + +开始之前，请准备： + +- 一个[已安装的 GitLab 实例](https://gitlab.cn/install)，以及该实例 Admin area 的访问权限。 +- 一个具有公共 HTTPS 控制台源的 RustFS 部署。 +- 一个分配给 GitLab 用户的 RustFS 策略。示例使用 `consoleAdmin`；在生产环境中，请使用仅包含用户所需权限的策略。 + +## 概述 + +浏览器登录流程如下： + +1. RustFS 发送包含授权码交换证明（Proof Key for Code Exchange，PKCE）S256 质询的授权码请求。 +2. GitLab 验证用户身份，并使用 `code` 和 `state` 将浏览器重定向到 RustFS。 +3. RustFS 在 GitLab 令牌端点交换授权码。 +4. RustFS 验证 ID 令牌的签名、签发者、受众、有效期和 nonce。 +5. RustFS 分配已配置的本地身份与访问管理（IAM）策略，并为控制台会话签发临时凭证。 + +GitLab 负责验证用户身份，RustFS 策略则负责授权 S3 操作和管理操作。 + +示例使用以下值。请根据你的环境替换主机名和客户端密钥： + +| 设置 | 示例 | +| --- | --- | +| GitLab issuer | `https://gitlab.example.com` | +| GitLab application ID | `` | +| Public RustFS origin | `https://rustfs.example.com` | +| RustFS callback URL | `https://rustfs.example.com/rustfs/admin/v3/oidc/callback/default` | + +## 配置 + +### GitLab 配置 + +#### 创建 OAuth 应用 + +1. 以管理员身份登录 GitLab。 +2. 打开 **Admin Area**，选择 **Applications**，然后选择 **New application**。 +3. 输入应用名称 `RustFS OIDC`。 +4. 将 **Redirect URI** 设置为精确的 RustFS 回调 URL： + + ```text + https://rustfs.example.com/rustfs/admin/v3/oidc/callback/default + ``` + +5. 启用 **Confidential**。 +6. 启用 **Trusted**，使这个 instance-wide 应用跳过用户授权提示。 +7. 选择 `openid`、`profile` 和 `email` scope。 +8. 保存应用，然后复制生成的 application ID 和 secret。 + +有关应用管理的详细信息，请参阅 [GitLab OAuth provider 文档](https://docs.gitlab.com/integration/oauth_provider/)。 + +![GitLab Admin area 中显示为 trusted 和 confidential 的 RustFS OIDC instance OAuth 应用](./images/gitlab-oidc-configuration.png) + +:::note[截图中的测试环境] + +截图显示的是测试环境中的 HTTP 回调 URL。请为你的 RustFS 部署使用公共 HTTPS 回调 URL。 + +::: + +### RustFS 配置 + +通过环境变量配置 GitLab 提供商。 + +#### 使用环境变量配置 + +将 GitLab 提供商和公共浏览器源添加到 RustFS 服务环境： + +```ini title="/etc/default/rustfs" +RUSTFS_BROWSER_REDIRECT_URL="https://rustfs.example.com" + +RUSTFS_IDENTITY_OPENID_ENABLE=on +RUSTFS_IDENTITY_OPENID_CONFIG_URL="https://gitlab.example.com" +RUSTFS_IDENTITY_OPENID_CLIENT_ID="" +RUSTFS_IDENTITY_OPENID_CLIENT_SECRET="" +RUSTFS_IDENTITY_OPENID_SCOPES="openid,profile,email" +RUSTFS_IDENTITY_OPENID_REDIRECT_URI="https://rustfs.example.com/rustfs/admin/v3/oidc/callback/default" +RUSTFS_IDENTITY_OPENID_REDIRECT_URI_DYNAMIC=off +RUSTFS_IDENTITY_OPENID_DISPLAY_NAME="GitLab" +RUSTFS_IDENTITY_OPENID_EMAIL_CLAIM="email" +RUSTFS_IDENTITY_OPENID_USERNAME_CLAIM="preferred_username" +RUSTFS_IDENTITY_OPENID_ROLE_POLICY="consoleAdmin" +``` + +应用配置后重启 RustFS。 + +`RUSTFS_BROWSER_REDIRECT_URL` 必须包含不带路径的公共 scheme 和 authority。它控制控制台成功重定向和注销回退 URL。提供商回调 URL 必须与 GitLab 中注册的 URL 完全匹配。 + +:::warning[限制分配的策略] + +`RUSTFS_IDENTITY_OPENID_ROLE_POLICY` 会向通过此提供商登录的所有用户分配同一个 RustFS 策略。请将 `consoleAdmin` 替换为仅授予 GitLab 用户所需权限的策略。 + +::: + +使用反向代理或负载均衡器时，请保留回调查询字符串，并将授权请求和回调请求路由到同一个 RustFS 节点。进行中的 OIDC `state` 位于该节点本地。 + +## 验证 + +### 验证 GitLab 发现信息 + +查询 GitLab 发现文档： + +```bash +curl -fsS "https://gitlab.example.com/.well-known/openid-configuration" | jq '{ + issuer, + authorization_endpoint, + token_endpoint, + jwks_uri, + scopes_supported, + code_challenge_methods_supported +}' +``` + +确认： + +- `issuer` 为 `https://gitlab.example.com`。 +- 存在 `authorization_endpoint`、`token_endpoint` 和 `jwks_uri`。 +- `scopes_supported` 包含 `openid`、`profile` 和 `email`。 +- `code_challenge_methods_supported` 包含 `S256`。 + +### 验证 RustFS 提供商 + +重启 RustFS 后，检查提供商是否可用： + +```bash +curl -fsS "https://rustfs.example.com/rustfs/admin/v3/oidc/providers" | jq +``` + +响应应包含 `default` 提供商，其显示名称为 `GitLab`。 + +### 测试控制台登录 + +打开 RustFS 控制台并选择 **GitLab**，或直接打开授权端点： + +```text +https://rustfs.example.com/rustfs/admin/v3/oidc/authorize/default +``` + +![RustFS 控制台登录页面中的 Login with GitLab 选项](./images/rustfs-console-gitlab-oidc.png) + +验证完整流程： + +1. 浏览器重定向到 GitLab。 +2. 用户登录，并在出现提示时授权应用。 +3. GitLab 使用 `code` 和 `state` 重定向到 RustFS 回调 URL。 +4. RustFS 验证 ID 令牌并创建控制台会话。 +5. 控制台以已配置的 RustFS 策略打开。 + +如果 GitLab 报告重定向 URI 不匹配，请确认 GitLab 应用中注册的 URI 与 `RUSTFS_IDENTITY_OPENID_REDIRECT_URI` 完全一致。 + +## 后续步骤 + +- 选择分配给 GitLab 用户的策略之前，请查看[用户、组和策略](../iam/policies.md)。 +- 公开登录端点之前，请查看[控制台安全说明](/administration/console)。 \ No newline at end of file diff --git a/content/zh/security-compliance/oidc/images/gitlab-oidc-configuration.png b/content/zh/security-compliance/oidc/images/gitlab-oidc-configuration.png new file mode 100644 index 00000000..4284d6a2 Binary files /dev/null and b/content/zh/security-compliance/oidc/images/gitlab-oidc-configuration.png differ diff --git a/content/zh/security-compliance/oidc/images/rustfs-console-gitlab-oidc.png b/content/zh/security-compliance/oidc/images/rustfs-console-gitlab-oidc.png new file mode 100644 index 00000000..9704a1e8 Binary files /dev/null and b/content/zh/security-compliance/oidc/images/rustfs-console-gitlab-oidc.png differ diff --git a/content/zh/security-compliance/oidc/index.md b/content/zh/security-compliance/oidc/index.md index 09003670..f7b4095b 100644 --- a/content/zh/security-compliance/oidc/index.md +++ b/content/zh/security-compliance/oidc/index.md @@ -32,6 +32,7 @@ RustFS 使用带有授权码交换证明（Proof Key for Code Exchange，PKCE） ## 提供商指南 - [配置 Keycloak](/security-compliance/oidc/keycloak)，将其用作 RustFS 控制台的 OIDC 提供商。 +- [配置 GitLab](/security-compliance/oidc/gitlab)，将其用作 RustFS 控制台的 OIDC 提供商。 ## 后续步骤 diff --git a/content/zh/security-compliance/oidc/meta.json b/content/zh/security-compliance/oidc/meta.json index 853c25c4..ca4090f4 100644 --- a/content/zh/security-compliance/oidc/meta.json +++ b/content/zh/security-compliance/oidc/meta.json @@ -1,4 +1,4 @@ { "title": "OIDC", - "pages": ["keycloak"] + "pages": ["keycloak", "gitlab"] } \ No newline at end of file