• 예제 구성
  • Google 구성
  • Microsoft Azure 구성
    • 일반 OpenID Connect 구성으로 마이그레이션
  • Microsoft Azure Active Directory B2C 구성
    • 커스텀 정책 구성
    • Azure B2C 문제 해결
  • Keycloak 구성
    • 대칭 키 알고리즘을 사용하여 Keycloak 구성
  • Casdoor
• 여러 개의 OpenID Connect 제공자 구성
• OIDC 그룹 멤버쉽에 따라 사용자 구성하기
  • 필수 그룹
  • 외부 그룹
  • 감사자 그룹
  • 관리자 그룹
• 문제 해결

OpenID Connect을 인증 제공자로 사용하기

OpenID Connect을 OmniAuth 제공자로 사용하여 GitLab을 클라이언트 응용 프로그램으로 사용할 수 있습니다.

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 계정이 없는 사용자들에 대한 Just-In-Time 계정 프로비저닝이 가능해집니다.

3. 제공자 구성을 추가합니다.

   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를 참조하십시오.

4. 제공자 구성을 변경하여 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입니다.
5. 구성 파일을 저장합니다.

6. 변경 사항이 적용되려면:

   • 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를 설정하세요:

일반 OpenID Connect 구성으로 마이그레이션하려면 다음 구성을 변경해야 합니다:

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"
      }
    }
  }
]

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 튜토리얼의 지침을 따라 사용자 플로우 또는 정책 이름을 얻으세요.

앱을 구성하세요:

1. 앱 리디렉션 URI를 설정하세요. 예를 들어, GitLab 도메인이 gitlab.example.com인 경우, 앱 리디렉션 URI를 https://gitlab.example.com/users/auth/openid_connect/callback로 설정하세요.

2. ID 토큰을 활성화하세요.

3. 앱에 다음 API 권한을 추가하세요:

   • openid
   • offline_access

커스텀 정책 구성

Azure B2C에서는 유저 로그인의 비즈니스 로직을 정의하는 두 가지 방법을 제공합니다:

• 사용자 흐름(User flows)
• 커스텀 정책(Custom policies)

일반적인 Azure B2C 사용자 흐름은 표준 Azure B2C 사용자 흐름과 함께 작동하지 않기 때문에 커스텀 정책이 필요합니다. 그 이유는 표준 사용자 흐름에서는 OpenID email 클레임을 보내지 않기 때문입니다(https://github.com/MicrosoftDocs/azure-docs/issues/16566). 따라서 GitLab은 표준 Azure B2C 정책으로는 새 계정을 생성하거나 기존 계정에 이메일 주소를 연결할 수 없습니다.

먼저 커스텀 정책을 생성하세요.

마이크로소프트 매뉴얼는 커스텀 정책 스타터 팩에서 SocialAndLocalAccounts를 사용하지만, LocalAccounts는 로컬 Active Directory 계정에 대해 인증을 수행합니다. 정책을 업로드하기 전에 다음을 수행하세요:

1. SignUpOrSignin.xml에서 email 클레임을 내보내려면 다음과 같이 코드를 수정하세요:

   <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" PartnerClaimType="email" />
   

2. 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>
           ...
   

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
   

   예를 들어, 도메인이 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을 구성하세요. 예를 들어, 리눅스 패키지 설치에 사용되는 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을 구성하세요. 공개 키 암호화 알고리즘은 다음과 같습니다:

• 구성이 더 쉽습니다.
• 개인 키가 유출될 경우 심각한 보안 문제가 발생합니다.

1. Keycloak 관리 콘솔을 엽니다.
2. Realm 설정 > 토큰 > 기본 서명 알고리즘을 선택합니다.
3. 서명 알고리즘을 구성합니다.

리눅스 패키지 설치에 대한 예제 구성 블록:

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 구성

대칭 키 암호화를 사용하려면:

1. 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를 사용합니다.

2. 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
   

3. 이 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에 연결하려면 다음 단계를 완료하세요:

1. 클라이언트 ID 및 클라이언트 비밀을 가져옵니다.
2. 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 그룹 멤버쉽에 따라 사용자 구성하기

• GitLab 15.10에서 도입됨.

OIDC 그룹 멤버쉽을 다음과 같이 구성할 수 있습니다:

• 특정 그룹의 구성원으로 사용자를 요구합니다.
• 그룹 멤버쉽에 따라 사용자에게 external, 관리자 또는 감사자 역할을 할당합니다.

GitLab은 각 로그인 시에 이러한 그룹을 확인하고 필요에 따라 사용자 속성을 업데이트합니다. 이 기능을 사용하면 GitLab 그룹에 사용자를 자동으로 추가할 수는 없습니다.

필수 그룹

당신의 식별 공급자(Identity Provider, IdP)는 OIDC 응답에서 그룹 정보를 GitLab에 전달해야 합니다. 이 응답을 사용하여 특정 그룹의 구성원으로 사용자를 요구하려면 GitLab을 다음과 같이 구성하세요:

• OIDC 응답에서 그룹을 찾을 위치를 groups_attribute 설정을 사용하여 식별합니다.
• 로그인에 필요한 그룹 멤버쉽을 required_groups 설정을 사용하여 식별합니다.

required_groups를 설정하지 않거나 설정을 비워 둔 경우, OIDC를 통해 인증된 모든 사용자가 GitLab을 사용할 수 있습니다.

외부 그룹

당신의 IdP는 OIDC 응답에서 그룹 정보를 GitLab에 전달해야 합니다. 이 응답을 사용하여 그룹 멤버쉽에 따라 사용자를 external users로 식별하려면 GitLab을 다음과 같이 구성하세요:

• OIDC 응답에서 그룹을 찾을 위치를 groups_attribute 설정을 사용하여 식별합니다.
• 그룹 멤버쉽에 따라 사용자를 external user로 식별하는 데 사용할 external_groups 설정을 식별합니다.

감사자 그룹

당신의 IdP는 OIDC 응답에서 그룹 정보를 GitLab에 전달해야 합니다. 이 응답을 사용하여 그룹 멤버쉽에 따라 사용자를 감사자로 지정하려면 GitLab을 다음과 같이 구성하세요:

• OIDC 응답에서 그룹을 찾을 위치를 groups_attribute 설정을 사용하여 식별합니다.
• 그룹 멤버쉽에 따라 사용자에게 감사자 액세스를 부여하는 데 사용할 auditor_groups 설정을 식별합니다.

관리자 그룹

당신의 IdP는 그룹 정보를 OIDC 응답에서 GitLab으로 전달해야 합니다. 사용자를 관리자로 지정하기 위해 응답을 사용하려면 다음을 구성하세요:

• groups_attribute 설정을 사용하여 OIDC 응답에서 그룹을 찾을 위치를 지정합니다.
• admin_groups 설정을 사용하여 사용자에게 관리자 액세스를 부여하는 그룹 멤버십을 지정합니다.

문제 해결

1. discovery가 true로 설정되어 있는지 확인합니다. false로 설정한 경우 OpenID를 작동시키는 데 필요한 모든 URL 및 키를 지정해야 합니다.

2. 시스템 클럭을 확인하여 시간이 올바르게 동기화되었는지 확인합니다.

3. OmniAuth OpenID Connect 문서에서 언급한 대로 issuer가 Discovery URL의 기본 URL에 해당하는지 확인합니다. 예를 들어, https://accounts.google.com은 URL https://accounts.google.com/.well-known/openid-configuration을 위해 사용됩니다.

4. OpenID Connect 클라이언트는 client_auth_method가 정의되지 않았거나 basic로 설정된 경우 OAuth 2.0 액세스 토큰을 보내기 위해 HTTP Basic 인증을 사용합니다. client_auth_method가 정의되지 않았거나 basic로 설정한 경우 userinfo 엔드포인트를 검색할 때 401 오류가 발생하는 경우 OpenID 웹 서버 구성을 확인합니다. 예를 들어, oauth2-server-php의 경우 Apache에 구성 매개변수를 추가해야 할 수 있습니다.