OpenID Connect을 인증 제공자로 사용하기
Offering: Self-Managed
OpenID Connect을 OmniAuth 제공자로 사용하여 GitLab을 클라이언트 응용 프로그램으로 사용할 수 있습니다.
OpenID Connect OmniAuth 제공자를 활성화하려면 응용 프로그램을 OpenID Connect 제공자에 등록해야 합니다.
OpenID Connect 제공자는 클라이언트의 세부 정보와 사용할 수 있도록 클라이언트의 비밀을 제공합니다.
-
GitLab 서버에서 구성 파일을 엽니다.
Linux 패키지 설치의 경우:
sudo editor /etc/gitlab/gitlab.rb
직접 컴파일한 설치의 경우:
cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml
-
일반 설정을 구성하여
openid_connect
을 단일 사인온 제공자로 추가합니다. 이를 통해 기존 GitLab 계정이 없는 사용자들에 대한 Just-In-Time 계정 프로비저닝이 가능해집니다. -
제공자 구성을 추가합니다.
Linux 패키지 설치의 경우:
ruby gitlab_rails['omniauth_providers'] = [ { name: "openid_connect", # 이 매개변수를 변경하지 마세요 label: "제공자 이름", # 선택 사항으로 로그인 버튼의 기본값은 "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 패키지 설치에서 다중 신원 제공자를 사용하는 경우:
ruby { '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' => { ... 'redirect_uri' => 'https://.../users/auth/openid_connect/callback' } } }, ...
직접 컴파일한 설치의 경우:
yaml - { name: 'openid_connect', # 이 매개변수를 변경하지 마세요 label: '제공자 이름', # 선택 사항으로 로그인 버튼의 기본값은 "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' } } }
OIDC와 다중 신원 제공자를 사용하는 데 대한 자세한 내용은 이슈 5992를 참조하십시오. -
제공자 구성을 변경하여 OpenID Connect 클라이언트 설정과 일치하도록 합니다. 아래를 참고하세요:
-
<your_oidc_label>
은 로그인 페이지에 표시되는 레이블입니다. -
<custom_provider_icon>
(선택 사항)은 로그인 페이지에 표시되는 아이콘입니다. 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
(선택 사항): Proof Key for Code Exchange를 활성화합니다. GitLab 15.9에서 사용 가능합니다. -
client_options
는 OpenID Connect 클라이언트별 옵션입니다. 특히:-
identifier
는 OpenID Connect 서비스 제공자에서 구성된 클라이언트 식별자입니다. -
secret
은 OpenID Connect 서비스 제공자에서 구성된 클라이언트 시크릿입니다. 예를 들어, OmniAuth 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입니다.
-
-
-
- 구성 파일을 저장합니다.
-
변경 사항이 적용되려면:
- GitLab을 설치하는 데 Linux 패키지를 사용했다면, GitLab을 다시 구성합니다.
- GitLab 설치를 직접 컴파일했다면, GitLab을 다시 시작합니다.
로그인 페이지에서 일반 로그인 양식 아래에 OpenID Connect 옵션이 표시됩니다.
인증 프로세스를 시작하려면 이 옵션을 선택하십시오. OpenID Connect 제공자는 확인이 필요한 경우 GitLab 응용 프로그램을 승인하고 로그인하도록 요청합니다. 그런 다음 GitLab로 리디렉션되어 로그인됩니다.
예제 구성
다음 구성은 Linux 패키지 설치 시 OpenID를 설정하는 방법을 보여줍니다.
Google 구성
자세한 내용은 Google 문서를 참조하세요:
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect", # 이 매개변수를 변경하지 마십시오.
label: "Google OpenID", # 선택적인 로그인 버튼 레이블, 기본값은 "Openid Connect"
args: {
name: "openid_connect",
scope: ["openid", "profile", "email"],
response_type: "code",
issuer: "https://accounts.google.com",
client_auth_method: "query",
discovery: true,
uid_field: "preferred_username",
pkce: true,
client_options: {
identifier: "<YOUR PROJECT CLIENT ID>",
secret: "<YOUR PROJECT CLIENT SECRET>",
redirect_uri: "https://example.com/users/auth/openid_connect/callback",
}
}
}
]
Microsoft Azure 구성
Microsoft Azure의 OpenID Connect(OIDC) 프로토콜은 마이크로소프트 ID 플랫폼(v2) 엔드포인트를 사용합니다. 시작하려면 Azure Portal에 로그인하세요. 앱에 대해 다음 정보가 필요합니다.
- 테넌트 ID. 이미 가지고 있을 수 있습니다. 자세한 내용은 Microsoft Azure Tenant 문서를 참조하세요.
- 클라이언트 ID 및 클라이언트 시크릿. 앱에 대한 테넌트 ID, 클라이언트 ID 및 클라이언트 시크릿을 얻으려면 Microsoft Quickstart Register an Application 문서의 지침을 따르세요.
Linux 패키지 설치를 위한 예제 구성 블록:
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect", # 이 매개변수를 변경하지 마십시오.
label: "Azure OIDC", # 선택적인 로그인 버튼 레이블, 기본값은 "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는 OIDC 프로토콜과의 플랫폼 연동 방법을 문서화했습니다.
일반 OpenID Connect 구성으로 마이그레이션
일반 OpenID Connect 구성으로 azure_activedirectory_v2
및 azure_oauth2
에서 마이그레이션할 수 있습니다.
먼저, 공급업체별로 다른 uid_field
를 설정하세요:
공급업체 | uid
| 지원 정보 |
---|---|---|
omniauth-azure-oauth2
| sub
|
info 객체 내에서 oid 및 tid 가 제공됩니다.
|
omniauth-azure-activedirectory-v2
| oid
| 마이그레이션할 때 uid_field 로 oid 를 구성해야 합니다.
|
omniauth_openid_connect
| sub
| 다른 필드를 사용하려면 uid_field 를 지정하세요.
|
일반 OpenID Connect 구성으로 마이그레이션하려면 다음 구성을 변경해야 합니다:
:::Azure OAuth 2.0
gitlab_rails['omniauth_providers'] = [
{
name: "azure_oauth2",
label: "Azure OIDC", # 선택적인 로그인 버튼 레이블, 기본값은 "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: "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"
}
}
}
]
:::Azure Active Directory v2
gitlab_rails['omniauth_providers'] = [
{
name: "azure_oauth2",
label: "Azure OIDC", # 선택적인 로그인 버튼 레이블, 기본값은 "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"
}
}
}
]
Microsoft Azure Active Directory B2C 구성
GitLab을 Azure Active Directory B2C와 함께 사용하려면 특별한 구성이 필요합니다. 시작하려면 Azure Portal에 로그인하세요. 앱에 대해 다음 Azure 정보가 필요합니다:
- 테넌트 ID. 이미 가지고 있을 수 있습니다. 자세한 내용은 Microsoft Azure Tenant 문서를 참조하세요.
- 클라이언트 ID 및 클라이언트 시크릿. 앱에 대한 클라이언트 ID 및 클라이언트 시크릿을 얻으려면 Microsoft 튜토리얼 문서의 지침을 따르세요.
- 사용자 플로우 또는 정책 이름. Microsoft 튜토리얼의 지침을 따라 사용자 플로우 또는 정책 이름을 얻으세요.
앱을 구성하세요:
-
앱
리디렉션 URI
를 설정하세요. 예를 들어, GitLab 도메인이gitlab.example.com
인 경우, 앱리디렉션 URI
를https://gitlab.example.com/users/auth/openid_connect/callback
로 설정하세요. -
ID 토큰을 활성화하세요.
-
앱에 다음 API 권한을 추가하세요:
openid
offline_access
커스텀 정책 구성
Azure B2C에서는 유저 로그인의 비즈니스 로직을 정의하는 두 가지 방법을 제공합니다:
일반적인 Azure B2C 사용자 흐름은 표준 Azure B2C 사용자 흐름과 함께 작동하지 않기 때문에 커스텀 정책이 필요합니다.
그 이유는 표준 사용자 흐름에서는 OpenID email
클레임을 보내지 않기 때문입니다(https://github.com/MicrosoftDocs/azure-docs/issues/16566).
따라서 GitLab은 표준 Azure B2C 정책으로는 새 계정을 생성하거나 기존 계정에 이메일 주소를 연결할 수 없습니다.
먼저 커스텀 정책을 생성하세요.
마이크로소프트 매뉴얼는 커스텀 정책 스타터 팩에서 SocialAndLocalAccounts
를 사용하지만, LocalAccounts
는 로컬 Active Directory 계정에 대해 인증을 수행합니다. 정책을 업로드하기 전에 다음을 수행하세요:
-
SignUpOrSignin.xml
에서email
클레임을 내보내려면 다음과 같이 코드를 수정하세요:<OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email" />
-
B2C에서 OIDC 디스커버리가 작동하려면 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> ...
-
정책을 업로드하세요. 기존 정책을 업데이트하는 경우 기존 파일을 덮어씁니다.
-
발행자 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
으로 나타납니다.반드시 뒤에 슬래시를 포함하세요.
-
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
예를 들어,
도메인
이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/"
-
signup_signin
에 사용되는 커스텀 정책과 발행자 URL을 구성하세요. 예를 들어, 리눅스 패키지 설치에 사용되는b2c_1a_signup_signin
의 커스텀 정책 설정은 다음과 같습니다:gitlab_rails['omniauth_providers'] = [ { name: "openid_connect", # 이 매개변수를 변경하지 마십시오 label: "Azure B2C OIDC", # 로그인 버튼의 선택 사항 레이블, 기본값은 "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로 추가하고 페이로드에 사용자의 이메일 액세스와 일치하는email
을 포함하는지 확인하세요. -
커스텀 정책을 활성화한 후 사용자가 로그인을 시도한 후
잘못된 사용자 이름 또는 암호
가 표시될 수 있습니다. 이는IdentityExperienceFramework
앱의 구성 문제일 수 있습니다. 이 Microsoft 코멘트를 참조하여 앱 매니페스트에 이러한 설정이 포함되어 있는지 확인할 것을 권장합니다:"accessTokenAcceptedVersion": null
"signInAudience": "AzureADMyOrg"
이 구성은 IdentityExperienceFramework
앱을 만들 때 사용된 지원되는 계정 유형
설정과 일치합니다.
Keycloak 구성
GitLab은 HTTPS를 사용하는 OpenID 제공자와 작동합니다. Keycloak 서버로 HTTP를 사용하는 Keycloak 서버를 설정할 수는 있지만, GitLab은 HTTPS를 사용하는 Keycloak 서버와만 통신할 수 있습니다.
토큰 서명에 대해 대칭 키 암호화 알고리즘(예: HS256 또는 HS358) 대신 공개 키 암호화 알고리즘(예: RSA256 또는 RSA512)을 사용하도록 Keycloak을 구성하세요. 공개 키 암호화 알고리즘은 다음과 같습니다:
- 구성이 더 쉽습니다.
- 개인 키가 유출될 경우 심각한 보안 문제가 발생합니다.
- Keycloak 관리 콘솔을 엽니다.
- Realm 설정 > 토큰 > 기본 서명 알고리즘을 선택합니다.
- 서명 알고리즘을 구성합니다.
리눅스 패키지 설치에 대한 예제 구성 블록:
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect", # 이 매개변수를 변경하지 마십시오
label: "Keycloak", # 로그인 버튼의 선택 사항 레이블, 기본값은 "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 구성
대칭 키 암호화를 사용하려면:
-
Keycloak 데이터베이스에서 비밀 키를 추출합니다. Keycloak은 웹 인터페이스에서 이 값을 노출하지 않습니다. 웹 인터페이스에 표시된 클라이언트 비밀은 JSON 웹 토큰을 서명하는 데 사용되는 비밀과 다릅니다.
예를 들어, Keycloak의 백엔드 데이터베이스로 PostgreSQL을 사용하는 경우:
- 데이터베이스 콘솔에 로그인합니다.
-
다음 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
)를 위한 두 개의 비밀 키가 있습니다. GitLab을 구성하는 데 첫 번째value
를 사용합니다.
-
value
를 표준 base64로 변환합니다. HS256 토큰의 유효하지 않은 서명 게시물에 설명된대로,value
는 RFC 4648의 URL 및 파일명 안전 문자로 Base 64 인코딩 섹션에 인코딩됩니다. 이를 RFC 2045에서 정의된 표준 base64로 변환해야 합니다. 다음 Ruby 스크립트가 이 작업을 수행합니다:require 'base64' value = "lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62-sqGc8drp3XW-wr93zru8PFsQokHZZuJJbaUXvmiOftCZM3C4KW3-g" Base64.encode64(Base64.urlsafe_decode64(value))
이 결과는 다음 값을 생성합니다:
lo6cqjD6Ika8pk7qc3fpFx9ysrhf7E62+sqGc8drp3XW+wr93zru8PFsQokH\nZZuJJbaUXvmiOftCZM3C4KW3+g==\n
-
이 base64로 인코딩된 비밀을
jwt_secret_base64
에 지정합니다. 예:gitlab_rails['omniauth_providers'] = [ { name: "openid_connect", # 이 매개변수는 변경하지 마세요 label: "Keycloak", # 선택적인 로그인 버튼 레이블, 기본값은 "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 제공자와 함께 작동합니다. Casdoor를 통해 OpenID를 통해 GitLab에 연결하려면 다음 단계를 완료하세요:
- 클라이언트 ID 및 클라이언트 비밀을 가져옵니다.
- GitLab 리디렉션 URL을 추가합니다. 예를 들어, GitLab 도메인이
gitlab.example.com
인 경우, Casdoor 애플리케이션이 다음Redirect URI
를 가지고 있는지 확인하세요:https://gitlab.example.com/users/auth/openid_connect/callback
.
더 많은 세부 정보는 Casdoor 설명서를 참조하세요.
Linux 패키지 설치의 예제 구성 (파일 경로: /etc/gitlab/gitlab.rb
):
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect", # 이 매개변수는 변경하지 마세요
label: "Casdoor", # 선택적인 로그인 버튼 레이블, 기본값은 "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', # 이 매개변수는 변경하지 마세요
label: 'Casdoor', # 선택적인 로그인 버튼 레이블, 기본값은 "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 프로토콜로 마이그레이션.
- 다른 수준의 인증 제공.
다음 예제 구성에서는 2FA를 사용하거나 2FA를 사용하지 않는 서로 다른 수준의 인증을 제공하는 방법을 보여줍니다.
Linux 패키지 설치를 위한 예:
gitlab_rails['omniauth_providers'] = [
{
name: "openid_connect",
label: "제공자 이름", # 선택적인 로그인 버튼 레이블, 기본값은 "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: "제공자 이름 2FA", # 선택적인 로그인 버튼 레이블, 기본값은 "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: '제공자 이름', # 선택적인 로그인 버튼 레이블, 기본값은 "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: '제공자 이름 2FA', # 선택적인 로그인 버튼 레이블, 기본값은 "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 = [
identity
for identity in user.identities
if identity.get("provider") == provider
and 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"{user.id} 사용자에 대한 제공자 {provider}에서 다른 ID를 찾았습니다.")
continue
else:
logger.info(f"{user.id} 사용자에 대한 'provider': {provider}, 'extern_uid': {extern_uid} ID 추가")
user.provider = provider
user.extern_uid = extern_uid
user = self.save_user(user)
return user
더 많은 정보는 GitLab API 사용자 메서드 설명서를 참조하세요.
OIDC 그룹 멤버쉽에 따라 사용자 구성하기
OIDC 그룹 멤버쉽을 다음과 같이 구성할 수 있습니다:
- 특정 그룹의 구성원으로 사용자를 요구합니다.
- 그룹 멤버쉽에 따라 사용자에게 external, 관리자 또는 감사자 역할을 할당합니다.
GitLab은 각 로그인 시에 이러한 그룹을 확인하고 필요에 따라 사용자 속성을 업데이트합니다. 이 기능을 사용하면 GitLab 그룹에 사용자를 자동으로 추가할 수는 없습니다.
필수 그룹
당신의 식별 공급자(Identity Provider, IdP)는 OIDC 응답에서 그룹 정보를 GitLab에 전달해야 합니다. 이 응답을 사용하여 특정 그룹의 구성원으로 사용자를 요구하려면 GitLab을 다음과 같이 구성하세요:
- OIDC 응답에서 그룹을 찾을 위치를
groups_attribute
설정을 사용하여 식별합니다. - 로그인에 필요한 그룹 멤버쉽을
required_groups
설정을 사용하여 식별합니다.
required_groups
를 설정하지 않거나 설정을 비워 둔 경우, OIDC를 통해 인증된 모든 사용자가 GitLab을 사용할 수 있습니다.
-
/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"] } } } } ]
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성하세요.
-
/home/git/gitlab/config/gitlab.yml
파일을 편집하세요:production: &base 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"] } } } }
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성하세요.
외부 그룹
당신의 IdP는 OIDC 응답에서 그룹 정보를 GitLab에 전달해야 합니다. 이 응답을 사용하여 그룹 멤버쉽에 따라 사용자를 external users로 식별하려면 GitLab을 다음과 같이 구성하세요:
- OIDC 응답에서 그룹을 찾을 위치를
groups_attribute
설정을 사용하여 식별합니다. - 그룹 멤버쉽에 따라 사용자를 external user로 식별하는 데 사용할
external_groups
설정을 식별합니다.
-
/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을 재구성하세요.
-
/home/git/gitlab/config/gitlab.yml
파일을 편집하세요:production: &base 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을 재구성하세요.
감사자 그룹
당신의 IdP는 OIDC 응답에서 그룹 정보를 GitLab에 전달해야 합니다. 이 응답을 사용하여 그룹 멤버쉽에 따라 사용자를 감사자로 지정하려면 GitLab을 다음과 같이 구성하세요:
- OIDC 응답에서 그룹을 찾을 위치를
groups_attribute
설정을 사용하여 식별합니다. - 그룹 멤버쉽에 따라 사용자에게 감사자 액세스를 부여하는 데 사용할
auditor_groups
설정을 식별합니다.
-
/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"] } } } } ]
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성하세요.
-
/home/git/gitlab/config/gitlab.yml
파일을 편집하세요:production: &base 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"] } } } }
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 재구성하세요.
관리자 그룹
당신의 IdP는 그룹 정보를 OIDC 응답에서 GitLab으로 전달해야 합니다. 사용자를 관리자로 지정하기 위해 응답을 사용하려면 다음을 구성하세요:
-
groups_attribute
설정을 사용하여 OIDC 응답에서 그룹을 찾을 위치를 지정합니다. -
admin_groups
설정을 사용하여 사용자에게 관리자 액세스를 부여하는 그룹 멤버십을 지정합니다.
-
/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"] } } } } ]
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 구성합니다.
-
/home/git/gitlab/config/gitlab.yml
파일을 편집합니다:production: &base 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"] } } } }
-
파일을 저장하고 변경 사항이 적용되도록 GitLab을 다시 구성합니다.
문제 해결
-
discovery
가true
로 설정되어 있는지 확인합니다.false
로 설정한 경우 OpenID를 작동시키는 데 필요한 모든 URL 및 키를 지정해야 합니다. -
시스템 클럭을 확인하여 시간이 올바르게 동기화되었는지 확인합니다.
-
OmniAuth OpenID Connect 문서에서 언급한 대로
issuer
가 Discovery URL의 기본 URL에 해당하는지 확인합니다. 예를 들어,https://accounts.google.com
은 URLhttps://accounts.google.com/.well-known/openid-configuration
을 위해 사용됩니다. -
OpenID Connect 클라이언트는
client_auth_method
가 정의되지 않았거나basic
로 설정된 경우 OAuth 2.0 액세스 토큰을 보내기 위해 HTTP Basic 인증을 사용합니다.client_auth_method
가 정의되지 않았거나basic
로 설정한 경우userinfo
엔드포인트를 검색할 때 401 오류가 발생하는 경우 OpenID 웹 서버 구성을 확인합니다. 예를 들어,oauth2-server-php
의 경우 Apache에 구성 매개변수를 추가해야 할 수 있습니다.