極狐GitLab 是 GitLab 在中國的發行版,關于中文參考文檔和資料有:
- 極狐GitLab 中文文檔
- 極狐GitLab 中文論壇
- 極狐GitLab 官網
使用 OpenID Connect 作為認證提供者 (BASIC SELF)
您可以使用極狐GitLab 作為客戶端應用程序,與 OpenID Connect 作為 OmniAuth 提供者一起使用。
要啟用 OpenID Connect OmniAuth 提供者,您必須在 OpenID Connect 提供者處注冊您的應用程序。OpenID Connect 提供者會向您提供客戶端的詳細信息和秘密供您使用。
1.在您的極狐GitLab 服務器上,打開配置文件。
對于 Linux 軟件包安裝:
sudo editor /etc/gitlab/gitlab.rb
對于自編譯安裝:
cd /home/git/gitlab
sudo -u git -H editor config/gitlab.yml
2.配置通用設置以添加 openid_connect 作為單點登錄提供者。這為沒有現有極狐GitLab 帳戶的用戶啟用即時賬戶配置。
3.添加提供者配置。
對于 Linux 軟件包安裝:
gitlab_rails['omniauth_providers'] = [{name: "openid_connect", # do not change this parameterlabel: "Provider name", # optional label for login button, defaults to "Openid Connect"icon: "<custom_provider_icon>",args: {name: "openid_connect",scope: ["openid","profile","email"],response_type: "code",issuer: "<your_oidc_url>",discovery: true,client_auth_method: "query",uid_field: "<uid_field>",send_scope_to_token_endpoint: "false",pkce: true,client_options: {identifier: "<your_oidc_client_id>",secret: "<your_oidc_client_secret>",redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback"}}}
]
對于具有多個身份提供者的 Linux 軟件包安裝:
{ 'name' => 'openid_connect','label' => '...','icon' => '...','args' => {'name' => 'openid_connect','strategy_class': 'OmniAuth::Strategies::OpenIDConnect','scope' => ['openid', 'profile', 'email'],'discovery' => true,'response_type' => 'code','issuer' => 'https://...','client_auth_method' => 'query','uid_field' => '...','client_options' => {`identifier`: "<your_oidc_client_id>",`secret`: "<your_oidc_client_secret>",'redirect_uri' => 'https://.../users/auth/openid_connect/callback'}}
},
{ 'name' => 'openid_connect_2fa','label' => '...','icon' => '...','args' => {'name' => 'openid_connect_2fa','strategy_class': 'OmniAuth::Strategies::OpenIDConnect','scope' => ['openid', 'profile', 'email'],'discovery' => true,'response_type' => 'code','issuer' => 'https://...','client_auth_method' => 'query','uid_field' => '...','client_options' => {...'redirect_uri' => 'https://.../users/auth/openid_connect_2fa/callback'}}
}
對于自編譯安裝:
- { name: 'openid_connect', # do not change this parameterlabel: 'Provider name', # optional label for login button, defaults to "Openid Connect"icon: '<custom_provider_icon>',args: {name: 'openid_connect',scope: ['openid','profile','email'],response_type: 'code',issuer: '<your_oidc_url>',discovery: true,client_auth_method: 'query',uid_field: '<uid_field>',send_scope_to_token_endpoint: false,pkce: true,client_options: {identifier: '<your_oidc_client_id>',secret: '<your_oidc_client_secret>',redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback'}}}
4.對于提供者配置,更改提供者的值以匹配您的 OpenID Connect 客戶端設置。使用以下作為指南:
-
<your_oidc_label> 是登錄頁面上顯示的標簽。
-
<custom_provider_icon> (可選)是登錄頁面上顯示的圖標。極狐GitLab 內置了主要社交登錄平臺的圖標,但您可以通過指定此參數來覆蓋這些圖標。極狐GitLab 接受本地路徑和絕對 URL。
-
<your_oidc_url> (可選)是指向 OpenID Connect 提供者的 URL(例如,https://example.com/auth/realms/your-realm)。如果未提供此值,則 URL 是從 client_options 構建的,格式為:<client_options.scheme>://<client_options.host>:<client_options.port>。
-
如果 discovery 設置為 true,OpenID Connect 提供者會嘗試使用 <your_oidc_url>/.well-known/openid-configuration 自動發現客戶端選項。默認值為 false。
-
client_auth_method (可選)指定用于與 OpenID Connect 提供者認證客戶端的方法。
-
支持的值包括:
-
basic - HTTP 基本認證。
-
jwt_bearer - 基于 JWT 的認證(私鑰和客戶端秘密簽名)。
-
mtls - 互相 TLS 或 X.509 證書驗證。
-
任何其他值都會在請求體中發布客戶端 ID 和秘密。
-
-
如果未指定,此值默認為 basic。
-
-
<uid_field> (可選)是 user_info.raw_attributes 中定義 uid 值的字段名稱(例如,preferred_username)。如果您未提供此值,或者配置的值的字段在 user_info.raw_attributes 詳細信息中缺失,則 uid 使用 sub 字段。
-
send_scope_to_token_endpoint 默認為 true,因此 scope 參數通常會包含在對令牌端點的請求中。但是,如果您的 OpenID Connect 提供者不接受此類請求中的 scope 參數,請將其設置為 false。
-
pkce (可選):啟用 代碼交換的證明密鑰。可用于極狐GitLab 15.9。
-
client_options 是 OpenID Connect 客戶端特定選項。具體來說:
-
identifier 是在 OpenID Connect 服務提供者中配置的客戶端標識符。
-
secret 是在 OpenID Connect 服務提供者中配置的客戶端密鑰。如果服務提供者不需要密鑰,請提供任何值并忽略它。
-
redirect_uri 是極狐GitLab URL,用于在成功登錄后重定向用戶(例如,http://example.com/users/auth/openid_connect/callback)。
-
end_session_endpoint (可選)是結束會話的端點 URL。如果自動發現失敗或未成功,您可以提供此 URL。
以下 client_options 是可選的,除非自動發現失敗或未成功:-
authorization_endpoint 是授權最終用戶的端點 URL。
-
token_endpoint 是提供訪問令牌的端點 URL。
-
userinfo_endpoint 是提供用戶信息的端點 URL。
-
jwks_uri 是令牌簽名者發布其密鑰的端點 URL。
-
-
5.保存配置文件。
6.要使更改生效,如果您:
- 使用 Linux 軟件包安裝極狐GitLab,重新配置極狐GitLab。
- 自編譯了您的極狐GitLab 安裝,重啟極狐GitLab。
在登錄頁面上,您在常規登錄表單下方有一個 OpenID Connect 選項。選擇此選項開始認證過程。如果客戶端要求確認,OpenID Connect 提供者會要求您登錄并授權極狐GitLab 應用程序。您將被重定向到極狐GitLab 并登錄。
示例配置
以下配置說明如何在使用 Linux 軟件包安裝時與不同提供者一起設置 OpenID。
配置 Microsoft Azure
Microsoft Azure 的 OpenID Connect (OIDC) 協議使用 Microsoft identity platform (v2) endpoints。要開始,請登錄 Azure Portal。對于您的應用,您需要以下信息:
- 一個租戶 ID。您可能已經有一個。
- 一個客戶端 ID 和一個客戶端秘密。獲取您的應用的租戶 ID、客戶端 ID 和客戶端秘密。
Linux 軟件包安裝的示例配置塊:
gitlab_rails['omniauth_providers'] = [{name: "openid_connect", # do not change this parameterlabel: "Azure OIDC", # optional label for login button, defaults to "Openid Connect"args: {name: "openid_connect",scope: ["openid", "profile", "email"],response_type: "code",issuer: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0",client_auth_method: "query",discovery: true,uid_field: "preferred_username",pkce: true,client_options: {identifier: "<YOUR APP CLIENT ID>",secret: "<YOUR APP CLIENT SECRET>",redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"}}}
]
Microsoft Entra 自定義簽名密鑰
如果您的應用程序有自定義簽名密鑰,因為您使用了 SAML claims-mapping feature,則必須以以下方式配置 OpenID 提供者:
-
通過省略 args.discovery 或將其設置為 false 來禁用 OpenID Connect 發現。
-
在 client_options 中,指定以下內容:
-
使用 appid 查詢參數的 jwks_uri: https://login.microsoftonline.com//discovery/v2.0/keys?appid=。
-
end_session_endpoint。
-
authorization_endpoint。
-
userinfo_endpoint。
-
Linux 軟件包安裝的示例配置:
gitlab_rails['omniauth_providers'] = [{name: "openid_connect", # do not change this parameterlabel: "Azure OIDC", # optional label for login button, defaults to "Openid Connect"args: {name: "openid_connect",scope: ["openid", "profile", "email"],response_type: "code",issuer: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0",client_auth_method: "basic",discovery: false,uid_field: "preferred_username",pkce: true,client_options: {identifier: "<YOUR APP CLIENT ID>",secret: "<YOUR APP CLIENT SECRET>",redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback",end_session_endpoint: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/oauth2/v2.0/logout",authorization_endpoint: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/oauth2/v2.0/authorize",token_endpoint: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/oauth2/v2.0/token",userinfo_endpoint: "https://graph.microsoft.com/oidc/userinfo",jwks_uri: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/discovery/v2.0/keys?appid=<YOUR APP CLIENT ID>"}}}
]
如果您看到帶有 KidNotFound 消息的認證失敗,這可能是因為缺少或錯誤的 appid 查詢參數。當 Microsoft 返回的 ID 令牌無法通過 jwks_uri 端點提供的密鑰進行驗證時,極狐GitLab 會引發該錯誤。
遷移到通用 OpenID Connect 配置
您可以從 azure_activedirectory_v2 和 azure_oauth2 遷移到通用 OpenID Connect 配置。
首先,設置 uid_field。uid_field 和您可以選擇作為 uid_field 的 sub 聲明因提供者而異。未設置 uid_field 的情況下登錄會導致在極狐GitLab 中創建額外的身份,這些身份必須手動修改:
提供商 | uid_field | 支持信息 |
---|---|---|
omniauth-azure-oauth2 | sub | 在 info 對象內會提供額外的屬性 oid 和 tid。 |
omniauth-azure-activedirectory-v2 | oid | 當遷移的時候,您必須將 oid 配置為 uid_field。 |
omniauth_openid_connect | sub | 指定 uid_field 使用其他字段。 |
要遷移到通用 OpenID Connect 配置,您必須更新配置。
對于 Linux 軟件包安裝,請按以下方式更新配置:
::Tabs
:::TabTitle Azure OAuth 2.0
gitlab_rails['omniauth_providers'] = [{name: "azure_oauth2",label: "Azure OIDC", # optional label for login button, defaults to "Openid Connect"args: {name: "azure_oauth2", # this matches the existing azure_oauth2 provider name, and only the strategy_class immediately below configures OpenID Connectstrategy_class: "OmniAuth::Strategies::OpenIDConnect",scope: ["openid", "profile", "email"],response_type: "code",issuer: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0",client_auth_method: "query",discovery: true,uid_field: "sub",send_scope_to_token_endpoint: "false",client_options: {identifier: "<YOUR APP CLIENT ID>",secret: "<YOUR APP CLIENT SECRET>",redirect_uri: "https://gitlab.example.com/users/auth/azure_oauth2/callback"}}}
]
:::TabTitle Azure Active Directory v2
gitlab_rails['omniauth_providers'] = [{name: "azure_activedirectory_v2",label: "Azure OIDC", # optional label for login button, defaults to "Openid Connect"args: {name: "azure_activedirectory_v2",strategy_class: "OmniAuth::Strategies::OpenIDConnect",scope: ["openid", "profile", "email"],response_type: "code",issuer: "https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0",client_auth_method: "query",discovery: true,uid_field: "oid",send_scope_to_token_endpoint: "false",client_options: {identifier: "<YOUR APP CLIENT ID>",secret: "<YOUR APP CLIENT SECRET>",redirect_uri: "https://gitlab.example.com/users/auth/azure_activedirectory_v2/callback"}}}
]
::EndTabs
對于 Helm 安裝:
在 YAML 文件(例如,provider.yaml)中添加提供者的配置:
::Tabs
:::TabTitle Azure OAuth 2.0
{"name": "azure_oauth2","args": {"name": "azure_oauth2","strategy_class": "OmniAuth::Strategies::OpenIDConnect","scope": ["openid","profile","email"],"response_type": "code","issuer": "https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0","client_auth_method": "query","discovery": true,"uid_field": "sub","send_scope_to_token_endpoint": false,"client_options": {"identifier": "<YOUR APP CLIENT ID>","secret": "<YOUR APP CLIENT SECRET>","redirect_uri": "https://gitlab.example.com/users/auth/azure_oauth2/callback"}}
}
:::TabTitle Azure Active Directory v2
{"name": "azure_activedirectory_v2","args": {"name": "azure_activedirectory_v2","strategy_class": "OmniAuth::Strategies::OpenIDConnect","scope": ["openid","profile","email"],"response_type": "code","issuer": "https://login.microsoftonline.com/<YOUR-TENANT-ID>/v2.0","client_auth_method": "query","discovery": true,"uid_field": "sub","send_scope_to_token_endpoint": false,"client_options": {"identifier": "<YOUR APP CLIENT ID>","secret": "<YOUR APP CLIENT SECRET>","redirect_uri": "https://gitlab.example.com/users/auth/activedirectory_v2/callback"}}
}
::EndTabs
當您遷移到 omniauth_openid_connect 作為極狐GitLab 17.0 或以上版本升級的一部分時,為您的組織設置的 sub 聲明值可能會有所不同。azure_oauth2 使用 Microsoft V1 端點,而 azure_activedirectory_v2 和 omniauth_openid_connect 都使用具有通用 sub 值的 Microsoft V2 端點。
-
對于在 Entra ID 中有電子郵件地址的用戶,為了允許回退到電子郵件地址并更新用戶身份,請配置以下內容:
- 在 Linux 軟件包安裝中,omniauth_auto_link_user。
- 在 Helm 安裝中,autoLinkUser。
-
對于沒有電子郵件地址的用戶,管理員必須采取以下行動之一:
- 設置另一種認證方法或啟用使用極狐GitLab 用戶名和密碼登錄。然后,用戶可以登錄并使用其個人資料手動鏈接其 Azure 身份。
- 實施 OpenID Connect 作為現有 azure_oauth2 的新提供者,以便用戶可以通過 OAuth2 登錄,并鏈接其 OpenID Connect 身份(類似于前一種方法)。此方法也適用于有電子郵件地址的用戶,只要啟用了 auto_link_user。
- 手動更新 extern_uid。為此,請使用 API 或 Rails 控制臺 更新每個用戶的 extern_uid。如果實例已升級到 17.0 或更高版本,且用戶已嘗試登錄,則可能需要此方法。
NOTE:
如果在配置極狐GitLab 帳戶時缺少或為空,azure_oauth2 可能已使用 Entra ID 的 upn 聲明作為電子郵件地址。
配置 Microsoft Azure Active Directory B2C
極狐GitLab 需要特殊配置才能與 Azure Active Directory B2C協同工作。首先,請登錄 Azure Portal。對于您的應用,您需要從 Azure 獲得以下信息:
- 租戶 ID。
- 客戶端 ID 和客戶端密鑰。
- 用戶流或策略名稱。
配置應用:
1.設置應用 Redirect URI。例如,如果您的極狐GitLab 域名是 gitlab.example.com,則將應用 Redirect URI 設置為 https://gitlab.example.com/users/auth/openid_connect/callback。
2.啟用 ID 令牌。
3.向應用添加以下 API 權限:
- openid
- offline_access
配置自定義策略
Azure B2C 提供兩種定義用戶登錄業務邏輯的方法:
- 用戶流
- 自定義策略
需要自定義策略,因為標準 Azure B2C 用戶流不發送 OpenID email 聲明。因此,標準用戶流無法與 allow_single_sign_on 或 auto_link_user 參數 一起使用。使用標準 Azure B2C 策略時,極狐GitLab 無法創建新賬戶或鏈接到具有電子郵件地址的現有賬戶。
首先,創建自定義策略。
Microsoft 指南在 custom policy starter pack 中使用 SocialAndLocalAccounts,但 LocalAccounts 是針對本地 Active Directory 賬戶進行身份驗證。在您上傳策略之前,請執行以下操作:
1.要導出 email 聲明,修改 SignUpOrSignin.xml。替換以下行:
<OutputClaim ClaimTypeReferenceId="email" />
替換為:
<OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email" />
2.為使 OIDC 發現與 B2C 一起工作,請使用與 OIDC 規范 兼容的發行者配置策略。在 TrustFrameworkBase.xml 中的 JwtIssuer 下,將 IssuanceClaimPattern 設置為 AuthorityWithTfp:
<ClaimsProvider><DisplayName>Token Issuer</DisplayName><TechnicalProfiles><TechnicalProfile Id="JwtIssuer"><DisplayName>JWT Issuer</DisplayName><Protocol Name="None" /><OutputTokenFormat>JWT</OutputTokenFormat><Metadata><Item Key="IssuanceClaimPattern">AuthorityWithTfp</Item>...
3.上傳策略。如果您正在更新現有策略,請覆蓋現有文件。
4.要確定發行者 URL,請使用登錄策略。發行者 URL 的格式為:
https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/
URL 中的策略名稱是小寫的。例如,B2C_1A_signup_signin 策略顯示為 b2c_1a_signup_sigin。
確保您包括尾部斜杠。
5.驗證 OIDC 發現 URL 和發行者 URL 的操作,并在發行者 URL 后附加 .well-known/openid-configuration:
https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/<YOUR-SIGN-IN-POLICY-NAME>/v2.0/.well-known/openid-configuration
例如,如果 domain 是 example.b2clogin.com,租戶 ID 是 fc40c736-476c-4da1-b489-ee48cee84386,您可以使用 curl 和 jq 提取發行者:
$ curl --silent "https://example.b2clogin.com/tfp/fc40c736-476c-4da1-b489-ee48cee84386/b2c_1a_signup_signin/v2.0/.well-known/openid-configuration" | jq .issuer
"https://example.b2clogin.com/tfp/fc40c736-476c-4da1-b489-ee48cee84386/b2c_1a_signup_signin/v2.0/"
6.使用 signup_signin 的自定義策略配置發行者 URL。例如,這是 Linux 軟件包安裝的 b2c_1a_signup_signin 自定義策略配置:
gitlab_rails['omniauth_providers'] = [
{name: "openid_connect", # do not change this parameterlabel: "Azure B2C OIDC", # optional label for login button, defaults to "Openid Connect"args: {name: "openid_connect",scope: ["openid"],response_mode: "query",response_type: "id_token",issuer: "https://<YOUR-DOMAIN>/tfp/<YOUR-TENANT-ID>/b2c_1a_signup_signin/v2.0/",client_auth_method: "query",discovery: true,send_scope_to_token_endpoint: true,pkce: true,client_options: {identifier: "<YOUR APP CLIENT ID>",secret: "<YOUR APP CLIENT SECRET>",redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"}}
}]
Azure B2C 故障排除
-
確保所有 yourtenant.onmicrosoft.com、ProxyIdentityExperienceFrameworkAppId 和 IdentityExperienceFrameworkAppId 匹配您的 B2C 租戶主機名以及 XML 策略文件中的相應客戶端 ID。
-
將 https://jwt.ms 添加為應用的重定向 URI,并使用 custom policy tester。確保有效負載包含與用戶電子郵件訪問匹配的 email。
-
啟用自定義策略后,用戶可能會在嘗試登錄后看到 Invalid username or password。這可能是 IdentityExperienceFramework 應用的配置問題。建議您檢查應用清單包含以下設置:
- “accessTokenAcceptedVersion”: null
- “signInAudience”: “AzureADMyOrg”
此配置與創建 IdentityExperienceFramework 應用時使用的 Supported account types 設置相對應。
配置 Keycloak
極狐GitLab 可與使用 HTTPS 的 OpenID 提供者一起工作。雖然您可以設置使用 HTTP 的 Keycloak 服務器,但極狐GitLab 只能與使用 HTTPS 的 Keycloak 服務器通信。
配置 Keycloak 以使用公鑰加密算法(例如,RSA256 或 RSA512)而不是對稱密鑰加密算法(例如,HS256 或 HS358)來簽署令牌。公鑰加密算法更容易配置,并且更安全,因為泄露私鑰會帶來嚴重的安全后果。
- 打開 Keycloak 管理控制臺。
- 選擇 Realm Settings > Tokens > Default Signature Algorithm。
- 配置簽名算法。
Linux 軟件包安裝示例配置塊:
gitlab_rails['omniauth_providers'] = [{name: "openid_connect", # do not change this parameterlabel: "Keycloak", # optional label for login button, defaults to "Openid Connect"args: {name: "openid_connect",scope: ["openid", "profile", "email"],response_type: "code",issuer: "https://keycloak.example.com/realms/myrealm",client_auth_method: "query",discovery: true,uid_field: "preferred_username",pkce: true,client_options: {identifier: "<YOUR CLIENT ID>",secret: "<YOUR CLIENT SECRET>",redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"}}}
]
使用對稱密鑰算法配置 Keycloak
WARNING:以下說明僅為完整性而包含,但僅在絕對必要時使用對稱密鑰加密。
要使用對稱密鑰加密:
1.從 Keycloak 數據庫中提取密鑰。Keycloak 不在網絡界面中公開該值。網絡界面中看到的客戶端密鑰是 OAuth 2.0 客戶端密鑰,與用于簽署 JSON Web Tokens 的密鑰不同。
例如,如果您使用 PostgreSQL 作為 Keycloak 的后端數據庫:
-
登錄數據庫控制臺。
-
運行以下 SQL 查詢以提取密鑰:
$ psql -U keycloak
psql (13.3 (Debian 13.3-1.pgdg100+1))
Type "help" for help.keycloak=# SELECT c.name, value FROM component_config CC INNER JOIN component C ON(CC.component_id = C.id) WHERE C.realm_id = 'master' and provider_id = 'hmac-generated' AND CC.name = 'secret';
-[ RECORD 1 ]---------------------------------------------------------------------------------
name | hmac-generated
value | lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62-sqGc8drp3XW-wr93zru8PFsQokHZZuJJbaUXvmiOftCZM3C4KW3-g
-[ RECORD 2 ]---------------------------------------------------------------------------------
name | fallback-HS384
value | UfVqmIs--U61UYsRH-NYBH3_mlluLONpg_zN7CXEwkJcO9xdRNlzZfmfDLPtf2xSTMvqu08R2VhLr-8G-oZ47A
在此示例中,有兩個私鑰:一個用于 HS256 (hmac-generated) 和另一個用于 HS384 (fallback-HS384)。我們使用第一個 value 來配置極狐GitLab。
2.將 value 轉換為標準 base64。如 Invalid signature with HS256 token post 中所述,value 是根據 Base 64 Encoding with URL and Filename Safe Alphabet section 的 RFC 4648 編碼的。必須將其轉換為 RFC 2045 中定義的標準 base64。以下 Ruby 腳本執行此操作:
require 'base64'value = "lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62-sqGc8drp3XW-wr93zru8PFsQokHZZuJJbaUXvmiOftCZM3C4KW3-g"
Base64.encode64(Base64.urlsafe_decode64(value))
結果為以下值:
lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62+sqGc8drp3XW+wr93zru8PFsQokH\nZZuJJbaUXvmiOftCZM3C4KW3+g==\n
3.在 jwt_secret_base64 中指定此 base64 編碼的密鑰。例如:
gitlab_rails['omniauth_providers'] = [{name: "openid_connect", # do not change this parameterlabel: "Keycloak", # optional label for login button, defaults to "Openid Connect"args: {name: "openid_connect",scope: ["openid", "profile", "email"],response_type: "code",issuer: "https://keycloak.example.com/auth/realms/myrealm",client_auth_method: "query",discovery: true,uid_field: "preferred_username",jwt_secret_base64: "<YOUR BASE64-ENCODED SECRET>",pkce: true,client_options: {identifier: "<YOUR CLIENT ID>",secret: "<YOUR CLIENT SECRET>",redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"}}}
]
如果您看到 JSON::JWS::VerificationFailed 錯誤,您指定了錯誤的密鑰。
Casdoor
極狐GitLab 可與使用 HTTPS 的 OpenID 提供者一起工作。使用 HTTPS 通過 OpenID 與 Casdoor 連接到極狐GitLab。
對于您的應用,請在 Casdoor 上完成以下步驟:
-
獲取客戶端 ID 和客戶端密鑰。
-
添加您的極狐GitLab 重定向 URL。例如,如果您的極狐GitLab 域名是 gitlab.example.com,確保 Casdoor 應用具有以下 Redirect URI:https://gitlab.example.com/users/auth/openid_connect/callback。
Linux 軟件包安裝示例配置(文件路徑:/etc/gitlab/gitlab.rb):
gitlab_rails['omniauth_providers'] = [{name: "openid_connect", # do not change this parameterlabel: "Casdoor", # optional label for login button, defaults to "Openid Connect"args: {name: "openid_connect",scope: ["openid", "profile", "email"],response_type: "code",issuer: "https://<CASDOOR_HOSTNAME>",client_auth_method: "query",discovery: true,uid_field: "sub",client_options: {identifier: "<YOUR CLIENT ID>",secret: "<YOUR CLIENT SECRET>",redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"}}}
]
自編譯安裝示例配置(文件路徑:config/gitlab.yml):
- { name: 'openid_connect', # do not change this parameterlabel: 'Casdoor', # optional label for login button, defaults to "Openid Connect"args: {name: 'openid_connect',scope: ['openid','profile','email'],response_type: 'code',issuer: 'https://<CASDOOR_HOSTNAME>',discovery: true,client_auth_method: 'query',uid_field: 'sub',client_options: {identifier: '<YOUR CLIENT ID>',secret: '<YOUR CLIENT SECRET>',redirect_uri: 'https://gitlab.example.com/users/auth/openid_connect/callback'}}}
配置多個 OpenID Connect 提供商
您可以配置您的應用程序以使用多個 OpenID Connect (OIDC) 提供商。您可以通過在配置文件中顯式設置 strategy_class 來實現這一點。
您應該在以下任一場景中執行此操作:
- 遷移到 OpenID Connect 協議。
- 提供不同級別的身份驗證。
NOTE:這與 基于 OIDC 組成員身份配置用戶 不兼容。
以下示例配置展示了如何提供不同級別的身份驗證,一個選項使用 2FA,一個不使用 2FA。
對于 Linux 軟件包安裝:
gitlab_rails['omniauth_providers'] = [{name: "openid_connect",label: "Provider name", # optional label for login button, defaults to "Openid Connect"icon: "<custom_provider_icon>",args: {name: "openid_connect",strategy_class: "OmniAuth::Strategies::OpenIDConnect",scope: ["openid","profile","email"],response_type: "code",issuer: "<your_oidc_url>",discovery: true,client_auth_method: "query",uid_field: "<uid_field>",send_scope_to_token_endpoint: "false",pkce: true,client_options: {identifier: "<your_oidc_client_id>",secret: "<your_oidc_client_secret>",redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback"}}},{name: "openid_connect_2fa",label: "Provider name 2FA", # optional label for login button, defaults to "Openid Connect"icon: "<custom_provider_icon>",args: {name: "openid_connect_2fa",strategy_class: "OmniAuth::Strategies::OpenIDConnect",scope: ["openid","profile","email"],response_type: "code",issuer: "<your_oidc_url>",discovery: true,client_auth_method: "query",uid_field: "<uid_field>",send_scope_to_token_endpoint: "false",pkce: true,client_options: {identifier: "<your_oidc_client_id>",secret: "<your_oidc_client_secret>",redirect_uri: "<your_gitlab_url>/users/auth/openid_connect_2fa/callback"}}}
]
對于私有化部署安裝:
- { name: 'openid_connect',label: 'Provider name', # optional label for login button, defaults to "Openid Connect"icon: '<custom_provider_icon>',args: {name: 'openid_connect',strategy_class: "OmniAuth::Strategies::OpenIDConnect",scope: ['openid','profile','email'],response_type: 'code',issuer: '<your_oidc_url>',discovery: true,client_auth_method: 'query',uid_field: '<uid_field>',send_scope_to_token_endpoint: false,pkce: true,client_options: {identifier: '<your_oidc_client_id>',secret: '<your_oidc_client_secret>',redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback'}}}- { name: 'openid_connect_2fa',label: 'Provider name 2FA', # optional label for login button, defaults to "Openid Connect"icon: '<custom_provider_icon>',args: {name: 'openid_connect_2fa',strategy_class: "OmniAuth::Strategies::OpenIDConnect",scope: ['openid','profile','email'],response_type: 'code',issuer: '<your_oidc_url>',discovery: true,client_auth_method: 'query',uid_field: '<uid_field>',send_scope_to_token_endpoint: false,pkce: true,client_options: {identifier: '<your_oidc_client_id>',secret: '<your_oidc_client_secret>',redirect_uri: '<your_gitlab_url>/users/auth/openid_connect_2fa/callback'}}}
在這種用例中,您可能希望根據現有的已知標識符在您的企業目錄中同步不同提供商之間的 extern_uid。
為此,您需要設置 uid_field。以下示例代碼展示了如何執行此操作:
def sync_missing_provider(self, user: User, extern_uid: str)existing_identities = []for identity in user.identities:existing_identities.append(identity.get("provider"))local_extern_uid = extern_uid.lower()for provider in ("openid_connect_2fa", "openid_connect"):identity = [identityfor identity in user.identitiesif identity.get("provider") == providerand identity.get("extern_uid").lower() != local_extern_uid]if provider not in existing_identities or identity:if identity and identity[0].get("extern_uid") != "":logger.error(f"Found different identity for provider {provider} for user {user.id}")continueelse:logger.info(f"Add identity 'provider': {provider}, 'extern_uid': {extern_uid} for user {user.id}")user.provider = provideruser.extern_uid = extern_uiduser = self.save_user(user)return user
有關更多信息,請參閱 極狐 GitLab API 用戶方法文檔。
基于 OIDC 組成員身份配置用戶 (PREMIUM ALL)
- 在極狐 GitLab 15.10 中引入。
您可以配置 OIDC 組成員身份來:
- 要求用戶是某個特定組的成員。
- 根據組成員身份分配用戶 外部、管理員或 審計員 角色。
極狐 GitLab 在每次登錄時檢查這些組并根據需要更新用戶屬性。此功能不允許您自動將用戶添加到極狐 GitLab 組中。
必需組
您的身份提供商 (IdP) 必須在 OIDC 響應中傳遞組信息給極狐 GitLab。要使用此響應來要求用戶成為某個特定組的成員,請配置極狐 GitLab 識別:
- 在 OIDC 響應中查找組的位置,使用 groups_attribute 設置。
- 登錄所需的組成員身份,使用 required_groups 設置。
如果您未設置 required_groups 或將設置留空,任何通過 IdP 通過 OIDC 認證的用戶都可以使用極狐 GitLab。
::Tabs
:::TabTitle Linux 軟件包 (Omnibus)
1.編輯 /etc/gitlab/gitlab.rb:
gitlab_rails['omniauth_providers'] = [{name: "openid_connect",label: "Provider name",args: {name: "openid_connect",scope: ["openid","profile","email"],response_type: "code",issuer: "<your_oidc_url>",discovery: true,client_auth_method: "query",uid_field: "<uid_field>",client_options: {identifier: "<your_oidc_client_id>",secret: "<your_oidc_client_secret>",redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback",gitlab: {groups_attribute: "groups",required_groups: ["Developer"]}}}}
]
2.保存文件并 重新配置極狐 GitLab 以使更改生效。
:::TabTitle 私有化部署 (source)
1.編輯 /home/git/gitlab/config/gitlab.yml:
production: &baseomniauth:providers:- { name: 'openid_connect',label: 'Provider name',args: {name: 'openid_connect',scope: ['openid','profile','email'],response_type: 'code',issuer: '<your_oidc_url>',discovery: true,client_auth_method: 'query',uid_field: '<uid_field>',client_options: {identifier: '<your_oidc_client_id>',secret: '<your_oidc_client_secret>',redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback',gitlab: {groups_attribute: "groups",required_groups: ["Developer"]}}}}
2.保存文件并 重新配置極狐 GitLab 以使更改生效。
::EndTabs
外部組
您的 IdP 必須在 OIDC 響應中傳遞組信息給極狐 GitLab。要使用此響應根據組成員身份識別用戶為 外部用戶,請配置極狐 GitLab 識別:
- 在 OIDC 響應中查找組的位置,使用 groups_attribute 設置。
- 哪些組成員身份應識別用戶為 外部用戶,使用 external_groups 設置。
::Tabs
:::TabTitle Linux 軟件包 (Omnibus)
1.編輯 /etc/gitlab/gitlab.rb:
gitlab_rails['omniauth_providers'] = [{name: "openid_connect",label: "Provider name",args: {name: "openid_connect",scope: ["openid","profile","email"],response_type: "code",issuer: "<your_oidc_url>",discovery: true,client_auth_method: "query",uid_field: "<uid_field>",client_options: {identifier: "<your_oidc_client_id>",secret: "<your_oidc_client_secret>",redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback",gitlab: {groups_attribute: "groups",external_groups: ["Freelancer"]}}}}
]
保存文件并 重新配置極狐 GitLab 以使更改生效。
:::TabTitle 私有化部署 (source)
1.編輯 /home/git/gitlab/config/gitlab.yml:
production: &baseomniauth:providers:- { name: 'openid_connect',label: 'Provider name',args: {name: 'openid_connect',scope: ['openid','profile','email'],response_type: 'code',issuer: '<your_oidc_url>',discovery: true,client_auth_method: 'query',uid_field: '<uid_field>',client_options: {identifier: '<your_oidc_client_id>',secret: '<your_oidc_client_secret>',redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback',gitlab: {groups_attribute: "groups",external_groups: ["Freelancer"]}}}}
2.保存文件并 重新配置極狐 GitLab 以使更改生效。
::EndTabs
審計員組 (PREMIUM SELF)
您的 IdP 必須在 OIDC 響應中傳遞組信息給極狐 GitLab。要使用此響應根據組成員身份分配用戶為審計員,請配置極狐 GitLab 識別:
在 OIDC 響應中查找組的位置,使用 groups_attribute 設置。
哪些組成員身份授予用戶審計員訪問權限,使用 auditor_groups 設置。
::Tabs
:::TabTitle Linux 軟件包 (Omnibus)
1.編輯 /etc/gitlab/gitlab.rb:
gitlab_rails['omniauth_providers'] = [{name: "openid_connect",label: "Provider name",args: {name: "openid_connect",scope: ["openid","profile","email","groups"],response_type: "code",issuer: "<your_oidc_url>",discovery: true,client_auth_method: "query",uid_field: "<uid_field>",client_options: {identifier: "<your_oidc_client_id>",secret: "<your_oidc_client_secret>",redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback",gitlab: {groups_attribute: "groups",auditor_groups: ["Auditor"]}}}}
]
2.保存文件并 重新配置極狐 GitLab 以使更改生效。
:::TabTitle 私有化部署 (source)
1.編輯 /home/git/gitlab/config/gitlab.yml:
production: &baseomniauth:providers:- { name: 'openid_connect',label: 'Provider name',args: {name: 'openid_connect',scope: ['openid','profile','email','groups'],response_type: 'code',issuer: '<your_oidc_url>',discovery: true,client_auth_method: 'query',uid_field: '<uid_field>',client_options: {identifier: '<your_oidc_client_id>',secret: '<your_oidc_client_secret>',redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback',gitlab: {groups_attribute: "groups",auditor_groups: ["Auditor"]}}}}
2.保存文件并 重新配置極狐 GitLab 以使更改生效。
::EndTabs
管理員組
您的 IdP 必須在 OIDC 響應中傳遞組信息給極狐 GitLab。要使用此響應根據組成員身份分配用戶為管理員,請配置極狐 GitLab 識別:
- 在 OIDC 響應中查找組的位置,使用 groups_attribute 設置。
- 哪些組成員身份授予用戶管理員訪問權限,使用 admin_groups 設置。
::Tabs
:::TabTitle Linux 軟件包 (Omnibus)
1.編輯 /etc/gitlab/gitlab.rb:
gitlab_rails['omniauth_providers'] = [{name: "openid_connect",label: "Provider name",args: {name: "openid_connect",scope: ["openid","profile","email"],response_type: "code",issuer: "<your_oidc_url>",discovery: true,client_auth_method: "query",uid_field: "<uid_field>",client_options: {identifier: "<your_oidc_client_id>",secret: "<your_oidc_client_secret>",redirect_uri: "<your_gitlab_url>/users/auth/openid_connect/callback",gitlab: {groups_attribute: "groups",admin_groups: ["Admin"]}}}}
]
2.保存文件并 重新配置極狐 GitLab 以使更改生效。
:::TabTitle 私有化部署 (source)
1.編輯 /home/git/gitlab/config/gitlab.yml:
production: &baseomniauth:providers:- { name: 'openid_connect',label: 'Provider name',args: {name: 'openid_connect',scope: ['openid','profile','email'],response_type: 'code',issuer: '<your_oidc_url>',discovery: true,client_auth_method: 'query',uid_field: '<uid_field>',client_options: {identifier: '<your_oidc_client_id>',secret: '<your_oidc_client_secret>',redirect_uri: '<your_gitlab_url>/users/auth/openid_connect/callback',gitlab: {groups_attribute: "groups",admin_groups: ["Admin"]}}}}
2.保存文件并 重新配置極狐 GitLab 以使更改生效。
::EndTabs
故障排除
1.確保 discovery 設置為 true。如果設置為 false,則必須指定所有用于使 OpenID 工作的 URL 和密鑰。
2.檢查您的系統時鐘以確保時間同步正確。
3.如在 OmniAuth OpenID Connect 文檔中所述,確保 issuer 對應于 Discovery URL 的基本 URL。例如,https://accounts.example.com 用于 URL https://accounts.example.com/.well-known/openid-configuration。
4.如果未定義 client_auth_method 或將其設置為 basic,則 OpenID Connect 客戶端使用 HTTP Basic Authentication 發送 OAuth 2.0 訪問令牌。如果在檢索 userinfo 端點時看到 401 錯誤,請檢查您的 OpenID Web 服務器配置。例如,對于 oauth2-server-php,您可能需要向 Apache 添加配置參數。