• 오픈아이디 구성 예시
  • 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 계정이 없는 사용자를 위한 JIT(Just-In-Time) 계정 프로비저닝이 가능해집니다.

3. 프로바이더 구성을 추가합니다.

   Linux 패키지 설치의 경우:

   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 패키지 설치의 경우:

   { '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로 여러 식별 공급자를 사용하는 자세한 정보는 이슈 5992를 참조하십시오.

   자체 컴파일 설치의 경우:

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

   참고: 각 구성 옵션에 대한 자세한 정보는 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 (선택 사항)은 클라이언트를 인증하는 데 사용되는 방법을 지정합니다.
     • 지원되는 값은:
       • 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 (선택 사항): RFC 766의 “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는 Token 서명자가 키를 게시하는 엔드포인트의 URL입니다.
5. 구성 파일을 저장합니다.

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

   • Linux 패키지를 사용하여 GitLab을 설치한 경우, GitLab을 다시 구성합니다.
   • 자체 컴파일한 GitLab을 설치한 경우, GitLab을 다시 시작합니다.

로그인 페이지에서 기존의 로그인 양식 아래에 OpenID Connect 옵션이 있습니다. 이 옵션을 선택하여 인증 프로세스를 시작합니다. OpenID Connect 프로바이더 는 귀하에게 로그인하고 GitLab 애플리케이션을 클라이언트에서 확인이 필요한 경우 인증하도록 요청합니다. 그 후 GitLab로 리디렉션되어 로그인됩니다.

오픈아이디 구성 예시

다음 구성은 Linux 패키지 설치 시 여러 공급업체를 사용하여 오픈아이디를 설정하는 방법을 보여줍니다.

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의 오픈아이디 커넥트 (OIDC) 프로토콜은 Microsoft identity platform (v2) endpoints을 사용합니다. 시작하려면 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 프로토콜에 대한 플랫폼 사용 방법을 문서화했습니다.

Microsoft Entra 사용자 지정 서명 키

SAML claims-mapping 기능을 사용하기 때문에 응용 프로그램에 사용자 지정 서명 키가 있는 경우 오픈아이디 제공자를 다음과 같이 구성해야합니다.

• args.discovery를 생략하거나 false로 설정하여 오픈아이디 커넥트 디스커버리 비활성화.
• 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 메시지로 인증 오류가 발생한다면, 이는 jwks_uri 엔드포인트에서 제공된 키로 Microsoft에서 반환한 ID 토큰을 유효성 검사할 수 없기 때문입니다. GitLab은 이 오류를 발생시킵니다.

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

일반 OpenID Connect 구성으로 이관

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

먼저 uid_field를 설정하세요. uid_field와 uid_field로 선택할 sub 클레임은 공급업체에 따라 다릅니다. uid_field를 설정하지 않고 로그인하면 GitLab에서 수동으로 수정해야하는 추가적인 신원을 만들게 됩니다.

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

Linux 패키지 설치용 구성 업데이트:

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는 Entra ID의 email 클레임이 누락되거나 비어 있을 때 upn 클레임을 사용했을 수 있습니다.

• Entra ID의 이메일 주소를 가진 사용자를 위한 사용자 생성을 허용하려면, 다음을 구성하세요:

  • Linux 패키지 설치의 경우: omniauth_auto_link_user.
  • Helm 설치의 경우: autoLinkUser.

• 이메일 주소가 없는 사용자를 위한 조치: 관리자가 다음 조치 중 하나를 취해야합니다:

  • 다른 인증 방법 구성 또는 GitLab 사용자 이름 및 암호를 사용한 로그인을 활성화하세요. 그런 다음 사용자는 프로필을 사용하여 로그인하고 Azure 신원을 수동으로 연결할 수 있습니다.
  • 기존 azure_oauth2 옆에 새로운 제공자로 OpenID Connect를 구현하여 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 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는 사용자 로그인의 비즈니스 로직을 정의하는 두 가지 방법을 제공합니다:

• 사용자 플로우
• 사용자 지정 정책

표준 Azure B2C 사용자 플로우는 OpenID email 클레임을 보내지 않기 때문에 사용자의 allow_single_sign_on 또는 auto_link_user 매개변수와 일치하지 않습니다. 따라서 표준 사용자 플로우는 이메일 주소로 새 계정을 만들거나 기존 계정에 연결할 수 없습니다.

먼저, 사용자 정의 정책을 만드세요.

Microsoft의 지침에 따르면 사용자 정의 정책 스타터 팩에서 SocialAndLocalAccounts를 사용하지만, LocalAccounts는 로컬 Active Directory 계정에 대해 인증합니다. 정책을 업로드하기 전에 다음을 수행하세요:

1. email 클레임을 내보내려면 SignUpOrSignin.xml을 수정하세요. 다음 줄을 다음과 같이 바꾸세요:

   <OutputClaim ClaimTypeReferenceId="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에서 정책 이름은 소문자입니다. 예를 들어, 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/"
   

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을 구성하세요. 예를 들어, 이것은 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 문제 해결

• XML 정책 파일에서 B2C 테넌트 호스트명과 해당 클라이언트 ID가 포함된 yourtenant.onmicrosoft.com, ProxyIdentityExperienceFrameworkAppId, IdentityExperienceFrameworkAppId의 모든 발생을 확인하세요.
• 앱에 https://jwt.ms를 리디렉트 URI로 추가하고 맞춤 정책 테스터를 사용하세요. 페이로드에 사용자의 이메일과 일치하는 email을 포함시켜야 합니다.

• 맞춤 정책을 사용하도록 설정한 후, 사용자가 로그인을 시도한 후 유효하지 않은 사용자 이름 또는 비밀번호를 볼 수 있습니다. 이는 IdentityExperienceFramework 앱의 구성 문제일 수 있습니다. Microsoft 코멘트에서 앱 매니페스트에 다음 설정이 포함되어 있는지 확인해야 한다고 제안합니다:

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

  이 구성은 IdentityExperienceFramework 앱을 만들 때 사용한 지원되는 계정 유형 설정과 일치합니다.

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: "<당신의 클라이언트 ID>",
        secret: "<당신의 클라이언트 비밀>"
        redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback"
      }
    }
  }
]

대칭 키 알고리즘으로 Keycloak 구성

주의: 아래 지침은 전체성을 위해 포함되었지만, 대칭 키 암호화는 절대적으로 필요한 경우에만 사용하세요.

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

1. Keycloak 데이터베이스에서 비밀 키를 추출하세요. Keycloak은 이 값을 웹 인터페이스에서 노출하지 않습니다. 웹 인터페이스에서 볼 수 있는 클라이언트 비밀은 JSON Web Tokens에 서명하는 데 사용되는 비밀과 다릅니다.

   예를 들어, 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의 Base 64 Encoding with URL and Filename Safe Alphabet 섹션에 인코딩되어 있습니다. 이를 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: "<당신의 base64로 인코딩된 비밀>",
         pkce: true,
         client_options: {
           identifier: "<당신의 클라이언트 ID>",
           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를 추가하세요: 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: "<당신의 클라이언트 ID>",
                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: "<당신의 클라이언트 ID>",
            secret: "<당신의 클라이언트 시크릿>",
            redirect_uri: "https://gitlab.example.com/users/auth/openid_connect/callback",
          },
      },
  }

여러 OpenID Connect 프로바이더 구성

응용 프로그램을 여러 OpenID Connect(OIDC) 프로바이더를 사용하도록 구성할 수 있습니다. 이를 위해 구성 파일에서 명시적으로 strategy_class를 설정해야 합니다.

다음 시나리오 중 하나에 해당하는 경우에 이 작업을 수행해야 합니다:

• 일반 OpenID Connect 프로토콜로의 마이그레이션
• 다른 수준의 인증 제공.

참고: 이는 OIDC 그룹 멤버십에 기반한 사용자 구성과 호환되지 않습니다. 자세한 정보는 이슈 408248를 참조하세요.

다음 예제 구성은 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"Found different identity for provider {provider} for user {user.id}")
              continue
          else:
              logger.info(f"Add identity 'provider': {provider}, 'extern_uid': {extern_uid} for user {user.id}")
              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을 구성하여 다음을 식별해야 합니다:

• groups_attribute 설정을 사용하여 OIDC 응답 내에서 그룹을 찾을 위치
• required_groups 설정을 사용하여 로그인에 필요한 그룹 멤버십 식별

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

외부 그룹

당신의 IdP는 OIDC 응답에서 그룹 정보를 GitLab에 전달해야 합니다. 그룹 멤버십에 따라 사용자를 외부 사용자로 식별하려면 다음을 식별하도록 GitLab을 구성해야 합니다:

• groups_attribute 설정을 사용하여 OIDC 응답 내에서 그룹을 찾을 위치
• external_groups 설정을 사용하여 사용자를 외부 사용자로 식별하는 데 사용할 그룹 멤버십 식별

감사자 그룹

당신의 IdP는 OIDC 응답에서 그룹 정보를 GitLab에 전달해야 합니다. 그룹 멤버십에 따라 사용자를 감사자로 할당하려면 다음을 식별하도록 GitLab을 구성해야 합니다:

• groups_attribute 설정을 사용하여 OIDC 응답 내에서 그룹을 찾을 위치
• 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 기본 인증을 사용합니다. userinfo 엔드포인트를 검색할 때 401 오류가 발생하는 경우 OpenID 웹 서버 구성을 확인하십시오. 예를 들어, oauth2-server-php의 경우, Apache에 구성 매개변수를 추가해야 할 수 있습니다.