• 예시 구성
  • Google 구성
  • Microsoft Azure 구성
    • Microsoft Entra 사용자 정의 서명 키
    • 일반 OpenID Connect 구성으로 마이그레이션
  • Microsoft Azure Active Directory B2C 구성
    • 사용자 지정 정책 구성
    • Azure B2C 문제 해결
  • Keycloak 구성
    • 대칭 키 알고리즘으로 Keycloak 구성
  • Casdoor
• 여러 OpenID Connect 제공자 구성
• OIDC 그룹 구성에 따른 사용자 설정
  • 필수 그룹
  • 외부 그룹
  • 감사 그룹
  • 관리자 그룹
• 문제 해결

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

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", # 이 매개변수는 변경하지 마세요  
       label: "Provider name", # 로그인 버튼의 선택적 레이블, 기본값은 "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 패키지 설치가 여러 개의 ID 제공자를 사용하는 경우:

   { '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'  
      }  
    }  
   }  
   

   OIDC와 함께 여러 ID 제공자를 사용하는 방법에 대한 자세한 내용은 issue 5992를 참조하세요.

   자가 컴파일 설치의 경우:

     - { name: 'openid_connect', # 이 매개변수는 변경하지 마세요  
         label: 'Provider name', # 로그인 버튼의 선택적 레이블, 기본값은 "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'  
           }  
         }  
       }  
   

   각 구성 옵션에 대한 자세한 정보는 OmniAuth OpenID Connect 사용 문서 및 OpenID Connect Core 1.0 사양을 참조하세요.

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 Basic 인증.
       • jwt_bearer - JWT 기반 인증 (개인 키 및 클라이언트 비밀번호 서명).
       • mtls - 상호 TLS 또는 X.509 인증서 검증.
       • 기타 모든 값은 요청 본문에 클라이언트 ID와 비밀번호를 POST합니다.
     • 지정되지 않은 경우 이 값의 기본값은 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) 프로토콜은 Microsoft identity platform (v2) endpoints를 사용합니다. 시작하려면 Azure Portal에 로그인하십시오. 귀하의 앱에 필요한 정보는 다음과 같습니다:

• 테넌트 ID. 이미 하나를 가지고 있을 수 있습니다. 자세한 내용은 Microsoft Azure Tenant 문서를 참조하세요.
• 클라이언트 ID와 클라이언트 비밀. Microsoft Quickstart Register an Application 문서의 지침을 따라 귀하의 앱에 대한 테넌트 ID, 클라이언트 ID 및 클라이언트 비밀을 얻으십시오.

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 프로토콜과 함께 플랫폼이 작동하는 방식에 대해 문서화했습니다.

Microsoft Entra 사용자 정의 서명 키

응용 프로그램에 SAML 클레임 매핑 기능을 사용하여 사용자 정의 서명 키가 있는 경우, OpenID 공급자를 다음과 같이 구성해야 합니다:

• args.discovery를 생략하거나 false로 설정하여 OpenID Connect Discovery를 비활성화하십시오.
• client_options에서 다음을 지정하십시오:
  • appid 쿼리 매개변수를 포함한 jwks_uri: https://login.microsoftonline.com/<YOUR-TENANT-ID>/discovery/v2.0/keys?appid=<YOUR APP CLIENT ID>.
  • end_session_endpoint.
  • authorization_endpoint.
  • userinfo_endpoint.

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: "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은 해당 오류를 발생시킵니다.

자세한 내용은 Microsoft Entra의 토큰 검증 문서를 참조하세요.

일반 OpenID Connect 구성으로 마이그레이션

azure_activedirectory_v2 및 azure_oauth2에서 일반 OpenID Connect 구성으로 마이그레이션할 수 있습니다.

먼저, uid_field를 설정하십시오. 선택할 수 있는 uid_field와 sub 클레임은 공급자에 따라 다릅니다. uid_field를 설정하지 않고 로그인하면 GitLab 내에서 수동으로 수정해야 하는 추가 아이덴티티가 생성됩니다:

일반 OpenID Connect 구성으로 마이그레이션하려면 구성을 업데이트해야 합니다.

리눅스 패키지 설치의 경우, 구성을 다음과 같이 업데이트하십시오:

gitlab_rails['omniauth_providers'] = [
  {
    name: "azure_oauth2",
    label: "Azure OIDC", # 로그인 버튼의 선택적 레이블, 기본값은 "Openid Connect"
    args: {
      name: "azure_oauth2", # 기존 azure_oauth2 공급자 이름과 일치하며 아래의 strategy_class만 OpenID Connect를 구성합니다.
      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_activedirectory_v2",
    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"
      }
    }
  }
]

Helm 설치의 경우:

YAML 파일에서 공급자 구성을 추가합니다 (예: provider.yaml):

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

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

azure_oauth2에서 omniauth_openid_connect로 마이그레이션하면서 GitLab 17.0 이상으로 업그레이드하는 과정에서, 조직에 설정된 sub 클레임 값이 다를 수 있습니다. azure_oauth2는 Microsoft V1 엔드포인트를 사용하고, azure_activedirectory_v2 및 omniauth_openid_connect는 두 모두 Microsoft V2 엔드포인트를 사용하며 공통 sub 값을 가집니다.

• Entra ID의 이메일 주소를 가진 사용자의 경우, 이메일 주소로 돌아가고 사용자의 아이덴티티를 업데이트할 수 있도록 다음을 구성하십시오:
  • 리눅스 패키지 설치의 경우, 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 이상으로 업그레이드되어 사용자가 로그인 시도를 하는 경우 필요할 수 있습니다.

참고: azure_oauth2는 주소록에 email 클레임이 없거나 비어 있을 경우, Entra ID의 upn 클레임을 이메일 주소로 사용할 수 있습니다.

Microsoft Azure Active Directory B2C 구성

GitLab은 Azure Active Directory B2C와 함께 작동하도록 특별한 구성이 필요합니다. 시작하려면 Azure Portal에 로그인하십시오.

귀하의 앱을 위해 Azure에서 다음 정보를 얻어야 합니다:

• 테넌트 ID. 이미 가지고 있을 수 있습니다. 자세한 내용은 Microsoft Azure 테넌트 문서를 검토하십시오.

• 클라이언트 ID 및 클라이언트 비밀. 앱의 클라이언트 ID 및 클라이언트 비밀을 얻으려면 Microsoft 자습서 문서의 지침을 따르십시오.

• 사용자 흐름 또는 정책 이름. Microsoft 자습서의 지침을 따르십시오.

앱 구성:

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 지침은 사용자 지정 정책 스타터 팩에서 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으로 표시됩니다.

   마지막 forward 슬래시를 포함하는 것을 확인하십시오.

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", # 이 매개변수를 변경하지 마십시오
     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을 포함하는지 확인하십시오.

• 사용자 지정 정책을 활성화한 후 사용자가 로그인 시도 시 Invalid username or password 메시지가 표시될 수 있습니다.
  이는 IdentityExperienceFramework 앱의 구성 문제일 수 있습니다.
  이 Microsoft 댓글을 참고하시어 앱 매니페스트에 다음 설정이 포함되어 있는지 확인하십시오:

  • "accessTokenAcceptedVersion": null
  • "signInAudience": "AzureADMyOrg"

이 구성은 IdentityExperienceFramework 앱을 생성할 때 사용되는 Supported account types 설정과 일치합니다.

Keycloak 구성

GitLab은 HTTPS를 사용하는 OpenID 공급자와 작업합니다. HTTP를 사용하는 Keycloak 서버를 설정할 수 있지만, GitLab은 HTTPS를 사용하는 Keycloak 서버와만 통신할 수 있습니다.

Keycloak을 구성하여 대칭 키 암호화 알고리즘 대신 공개 키 암호화 알고리즘(예: RSA256 또는 RSA512)을 사용하여 토큰에 서명하십시오. 공개 키 암호화 알고리즘의 장점은 다음과 같습니다:

• 구성하기 쉽습니다.

• 개인 키가 유출되면 심각한 보안 문제를 초래하기 때문에 더 안전합니다.

1. Keycloak 관리 콘솔을 엽니다.

2. Realm Settings > Tokens > Default Signature Algorithm를 선택합니다.

3. 서명 알고리즘을 구성합니다.

Linux 패키지 설치를 위한 예시 구성 블록:

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은 웹 인터페이스에서 이 값을 노출하지 않습니다. 웹 인터페이스에서 볼 수 있는 클라이언트 비밀은 OAuth 2.0 클라이언트 비밀로, JSON 웹 토큰에 서명하는 데 사용되는 비밀과 다릅니다.

   예를 들어, 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)입니다. 우리는 GitLab 구성을 위해 첫 번째 value를 사용합니다.

2. value를 표준 base64로 변환합니다. Invalid signature with HS256 token 게시물에서 논의된 바와 같이 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에 연결하려면 HTTPS를 사용하세요.

앱에 대해 Casdoor에서 다음 단계를 완료하세요:

1. 클라이언트 ID 및 클라이언트 비밀을 가져옵니다.
2. GitLab 리디렉션 URL을 추가합니다. 예를 들어, GitLab 도메인이 gitlab.example.com인 경우, Casdoor 앱에 다음 리디렉션 URI가 포함되어 있는지 확인하세요: 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: "Provider name", # 로그인 버튼에 대한 선택적 레이블, 기본값은 "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", # 로그인 버튼에 대한 선택적 레이블, 기본값은 "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', # 로그인 버튼에 대한 선택적 레이블, 기본값은 "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', # 로그인 버튼에 대한 선택적 레이블, 기본값은 "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}에 대해 다른 아이덴티티를 발견했습니다.")
              continue
          else:
              logger.info(f"사용자 {user.id}를 위한 아이덴티티 'provider': {provider}, 'extern_uid': {extern_uid}를 추가합니다.")
              user.provider = provider
              user.extern_uid = extern_uid
              user = self.save_user(user)
  return user

자세한 내용은 GitLab API 사용자 메서드 문서를 참조하세요.

OIDC 그룹 구성에 따른 사용자 설정

• 도입됨 GitLab 15.10에서.

OIDC 그룹 구성원 자격을 설정하여 다음을 수행할 수 있습니다:

• 사용자가 특정 그룹의 구성원이어야 합니다.
• 사용자에게 외부, 관리자 또는 감사자 역할을 그룹 구성원 자격에 따라 할당합니다.

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

필수 그룹

귀하의 신원 공급자(IdP)는 OIDC 응답에 그룹 정보를 GitLab에 전달해야 합니다. 이 응답을 사용하여 사용자가 특정 그룹의 구성원이어야 하도록 하려면, GitLab이 다음을 확인하도록 구성합니다:

• OIDC 응답에서 그룹을 검색할 위치를 groups_attribute 설정을 사용하여 지정합니다.
• 로그인을 위해 필요한 그룹 구성원을 required_groups 설정을 사용하여 지정합니다.

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

외부 그룹

귀하의 IdP는 OIDC 응답에서 GitLab에 그룹 정보를 전달해야 합니다. 이 응답을 사용하여 그룹 구성원 자격을 기반으로 사용자를 외부 사용자로 식별하려면 GitLab을 구성하여 다음을 식별합니다:

• OIDC 응답에서 그룹을 찾을 위치를 지정하기 위해 groups_attribute 설정을 사용합니다.
• 사용자를 외부 사용자로 식별할 그룹 구성원 자격을 지정하기 위해 external_groups 설정을 사용합니다.

감사 그룹

세부정보: Tier: Premium, Ultimate Offering: Self-managed

귀하의 IdP는 OIDC 응답에서 GitLab에 그룹 정보를 전달해야 합니다. 이 응답을 사용하여 그룹 구성원 자격에 따라 사용자를 감사자로 지정하려면 GitLab을 구성하여 다음을 식별합니다:

• OIDC 응답에서 그룹을 찾을 위치를 지정하기 위해 groups_attribute 설정을 사용합니다.
• 사용자가 감사자 접근 권한을 부여받는 그룹 구성원 자격을 지정하기 위해 auditor_groups 설정을 사용합니다.

관리자 그룹

귀하의 IdP는 OIDC 응답에서 GitLab에 그룹 정보를 전달해야 합니다. 이 응답을 사용하여 그룹 멤버십에 따라 사용자를 관리자에 할당하려면 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은 https://accounts.google.com/.well-known/openid-configuration URL에 사용됩니다.

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