InfoGrab DocsInfoGrab Docs

gitlab-sshd를 사용한 인스턴스 수준 SSH 인증서

요약

GitLab Self-Managed 인스턴스가 gitlab-sshd를 사용한다면 인스턴스 수준 SSH 인증서 인증을 구성할 수 있습니다. 이 방식은 OpenSSH의 TrustedUserCAKeys 지시어에 해당하는 gitlab-sshd 방식이며, OpenSSH 기반 SSH 인증서 설정의 대안입니다.

히스토리

GitLab Self-Managed 인스턴스가 gitlab-sshd를 사용한다면 인스턴스 수준 SSH 인증서 인증을 구성할 수 있습니다.

  • 인증 기관(Certificate Authority, CA) 인증서로 SSH 인증을 중앙에서 관리합니다.
  • Rails API 호출이나 데이터베이스 변경이 필요하지 않습니다.

이 방식은 OpenSSH의 TrustedUserCAKeys 지시어에 해당하는 gitlab-sshd 방식이며, OpenSSH 기반 SSH 인증서 설정의 대안입니다.

gitlab_sshd 인증 워크플로#

gitlab_sshd 인증 워크플로는 다음 과정을 따릅니다.

  1. 관리자가 CA 키 쌍을 생성합니다.
  2. 관리자가 config.yml의 sshd.trusted_user_ca_keys 아래에 CA 공개 키 파일 경로를 추가합니다.
  3. 관리자가 CA 개인 키로 사용자의 SSH 공개 키에 서명합니다. 인증서의 KeyId는 사용자의 GitLab 사용자 이름으로 설정됩니다.
  4. 사용자가 인증서로 연결하면 다음이 진행됩니다.
    • gitlab-sshd가 인증서 서명과 만료 여부를 검증합니다.
    • gitlab-sshd가 KeyId를 추출해 GitLab 사용자 이름으로 사용합니다.
    • 표준 GitLab 접근 확인이 진행됩니다(사용자 존재 여부, 프로젝트 권한).

gitlab-sshd 프로세스는 인증서 검증 자체에 Rails API 나 데이터베이스 호출이 필요하지 않습니다. /allowed 엔드포인트는 다른 SSH 연결과 마찬가지로 인가를 위해 여전히 호출됩니다.

다른 SSH 인증서 방식과의 비교#

GitLab은 여러 SSH 인증서 인증 방식을 지원합니다.

속성 gitlab-sshd 구성 파일 Admin 영역(베타) OpenSSH 최상위 그룹
CA를 추가하는 위치 config.yml Admin 영역 또는 REST API sshd_config REST API
SSH 서버 gitlab-sshd gitlab-sshd OpenSSH gitlab-sshd
Offering GitLab Self-Managed GitLab Self-Managed GitLab Self-Managed GitLab.com
Tier Free, Premium, Ultimate Free, Premium, Ultimate Free, Premium, Ultimate Premium, Ultimate
범위 인스턴스 전체 인스턴스 전체 인스턴스 전체 최상위 그룹과 그 하위 그룹
사용자 이름 매핑 인증서 KeyId 인증서 KeyId AuthorizedPrincipalsCommand를 통한 인증서 KeyId API를 통한 인증서 ID
엔터프라이즈 사용자 필요 여부 아니요 아니요 아니요 예
문서 신뢰할 수 있는 CA 키 구성 Admin 영역에서 신뢰할 수 있는 CA 키 관리 OpenSSH AuthorizedPrincipalsCommand 그룹 SSH 인증서

사전 요구 사항#

인스턴스 수준 SSH 인증서를 구성하기 전에 다음을 확인합니다.

  • GitLab Self-Managed 인스턴스에서 gitlab-sshd가 활성화되어 있어야 합니다. 자세한 내용은 gitlab-sshd 활성화를 참고합니다.
  • CA 키를 생성하고 config.yml을 편집하려면 서버 파일 시스템에 접근할 수 있어야 합니다.
  • SSH 인증서의 KeyId 필드는 GitLab 사용자 이름과 정확히 일치해야 합니다.

신뢰할 수 있는 CA 키 구성#

인스턴스 수준 SSH 인증서 인증을 구성하는 방법은 다음과 같습니다.

  1. CA 키 쌍을 생성합니다.

    ssh-keygen -t ed25519 -f ssh_user_ca -C "GitLab SSH User CA"
    

    프롬프트가 나타나면 CA 개인 키를 보호할 강력한 패스프레이즈를 입력합니다.

    이 명령은 파일 두 개를 생성합니다.

    • ssh_user_ca: CA 개인 키입니다.
    • ssh_user_ca.pub: CA 공개 키입니다.

    GitLab 서버에는 공개 키만 복사합니다.

    sudo cp ssh_user_ca.pub /etc/gitlab/ssh_user_ca.pub
    

    CA 개인 키는 안전한 위치에 보관하며, GitLab 서버가 아닌 오프라인 시스템에 두는 것이 가장 좋습니다. 개인 키는 사용자 인증서에 서명할 때만 필요합니다.

  2. gitlab-sshd 구성에 CA 공개 키 파일 경로를 추가합니다.

  3. /etc/gitlab/gitlab.rb를 편집합니다.

    gitlab_sshd['trusted_user_ca_keys'] = ['/etc/gitlab/ssh_user_ca.pub']
    
    1. 파일을 저장하고 GitLab을 재구성합니다.

      sudo gitlab-ctl reconfigure
      
  1. CA 공개 키가 담긴 Kubernetes Secret을 생성합니다.

    kubectl create secret generic my-ssh-ca-keys \
      --from-file=ca.pub=ssh_user_ca.pub
    
    1. Helm 값을 내보냅니다.

      helm get values gitlab > gitlab_values.yaml
      
    2. Secret을 참조하도록 gitlab_values.yaml을 편집합니다.

      gitlab:
        gitlab-shell:
          sshDaemon: gitlab-sshd
          config:
            trustedUserCAKeys:
              secret: my-ssh-ca-keys
              keys:
                - ca.pub
      
    3. 파일을 저장하고 새 값을 적용합니다.

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    

    Helm chart 구성에 대한 자세한 내용은 GitLab Shell chart 문서를 참고합니다.

  1. 다음 로그를 확인해 gitlab-sshd가 정상적으로 시작되었는지 검증합니다.

    Loaded trusted user CA keys for instance-level SSH certificates count=1
    

Admin 영역에서 신뢰할 수 있는 CA 키 관리#

히스토리
Feature flag

이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 히스토리를 참고합니다. 이 기능은 테스트용으로 사용할 수 있으며 프로덕션 환경에서 사용할 준비가 되지 않았습니다.

config.yml의 대안으로 Admin 영역이나 인스턴스 SSH 인증서 API에서 신뢰할 수 있는 CA 키를 추가할 수 있습니다. 변경 사항은 재시작 없이 모든 gitlab-sshd 노드에 즉시 적용됩니다.

두 방식을 동시에 사용할 수 있습니다. gitlab-sshd는 config.yml의 CA 키를 먼저 확인하고, 서명한 CA가 config.yml에 없을 때에만 Admin 영역에서 추가한 CA 키를 확인합니다.

사전 요구 사항:

신뢰할 수 있는 CA 키를 추가하려면 다음을 수행합니다.

  1. 신뢰할 수 있는 CA 키 구성에 설명된 대로 CA 키 쌍을 생성합니다. 공개 키를 GitLab 서버에 복사할 필요는 없습니다.
  2. 오른쪽 위 모서리에서 Admin을 선택합니다.
  3. 왼쪽 사이드바에서 Access > Certificate authorities를 선택합니다.
  4. Add certificate authority를 선택합니다.
  5. Title에 CA의 이름을 입력합니다.
  6. Public key에 CA 공개 키 파일(예: ssh_user_ca.pub)의 내용을 붙여넣습니다.
  7. Add certificate authority를 선택합니다.

GitLab은 FIPS가 활성화된 인스턴스의 더 엄격한 기본값을 포함해, 인스턴스의 SSH 키 제한을 충족하지 않는 CA 공개 키를 거부합니다.

신뢰할 수 있는 CA 키를 삭제하려면 다음을 수행합니다.

  1. 오른쪽 위 모서리에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Access > Certificate authorities를 선택합니다.
  3. CA 옆에서 More actions(⋮) > Delete certificate authority를 선택합니다.
  4. 확인 대화 상자에서 Delete certificate authority를 선택합니다.

CA를 삭제하면 GitLab은 신뢰를 즉시 해제하며, 해당 CA가 서명한 인증서는 더 이상 작동하지 않습니다.

GitLab Premium과 Ultimate에서는 CA를 추가하거나 삭제할 때 GitLab이 감사 이벤트를 기록합니다.

사용자에게 SSH 인증서 발급#

신뢰할 수 있는 CA 키를 구성한 다음에는 사용자에게 인증서를 발급합니다.

  1. 사용자의 SSH 공개 키를 확보합니다 (예: id_ed25519.pub).

  2. -I(identity/KeyId) 플래그를 사용자의 정확한 GitLab 사용자 이름으로 설정해 CA로 사용자의 공개 키에 서명합니다.

    ssh-keygen -s ssh_user_ca -I <gitlab-username> -V +1d user-key.pub
    

    이 명령은 하루 동안 유효한 인증서 파일 (예: user-key-cert.pub)을 생성합니다.

    유효 기간을 더 길게 설정하려면 -V 플래그를 조정합니다. 예를 들어 30 일은 -V +30d, 1 년은 -V +52w로 지정합니다.

  3. 사용자에게 인증서 파일을 배포합니다.

  4. 사용자는 인증서로 연결합니다.

    ssh git@gitlab.example.com
    

    인증서 파일이 기본 명명 규칙(<key> 옆에 <key>-cert.pub)을 따르면 SSH가 자동으로 사용합니다. 그렇지 않으면 인증서를 명시적으로 지정합니다.

    ssh -o CertificateFile=~/.ssh/id_ed25519-cert.pub git@gitlab.example.com
    

여러 인증 기관 사용#

CA 교체나 다중 CA 구성을 위해 CA 공개 키 파일을 여러 개 지정할 수 있습니다.

  1. /etc/gitlab/gitlab.rb를 편집합니다.

    gitlab_sshd['trusted_user_ca_keys'] = [
      '/etc/gitlab/ssh_user_ca_current.pub',
      '/etc/gitlab/ssh_user_ca_next.pub'
    ]
    
  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure
    
  1. CA 공개 키 두 개가 모두 담긴 Kubernetes Secret을 생성합니다.

    kubectl create secret generic my-ssh-ca-keys \
      --from-file=ca_current.pub=ssh_user_ca_current.pub \
      --from-file=ca_next.pub=ssh_user_ca_next.pub
    
  2. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml
    
  3. Secret을 참조하도록 gitlab_values.yaml을 편집합니다.

    gitlab:
      gitlab-shell:
        sshDaemon: gitlab-sshd
        config:
          trustedUserCAKeys:
            secret: my-ssh-ca-keys
            keys:
              - ca_current.pub
              - ca_next.pub
    
  4. 파일을 저장하고 새 값을 적용합니다.

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    

하나의 파일에 CA 공개 키를 한 줄에 하나씩 여러 개 담을 수도 있습니다. gitlab-sshd는 파일 전체에서 키 중복을 자동으로 제거합니다.

보안 고려 사항#

인스턴스 수준 SSH 인증서는 CA 개인 키를 가진 모든 사람에게 인증 권한을 부여합니다. 배포하기 전에 다음 보안 고려 사항을 검토합니다.

Warning

CA 개인 키에 접근할 수 있는 사람은 인스턴스의 모든 GitLab 사용자에 대한 인증서에 서명할 수 있습니다. 제한적인 파일 권한, 하드웨어 보안 모듈(HSM), 오프라인 환경 등 적절한 접근 제어로 CA 개인 키를 보호합니다.

인증서 해지 없음#

gitlab-sshd에는 내장된 인증서 해지 메커니즘이 없습니다. 인증서나 CA 키가 손상되면 trusted_user_ca_keys 구성에서 해당 CA를 제거하고 새 CA로 인증서를 재발급합니다. 노출 기간을 최소화하려면 단기 인증서(예: 24 시간)를 사용합니다.

CA 구성 변경에 대한 감사 이벤트 없음#

GitLab은 config.yml의 trusted_user_ca_keys 변경을 감사 이벤트로 기록하지 않습니다. 인프라 모니터링 도구로 이 구성 파일의 변경을 모니터링합니다.

gitlab-sshd는 SSH 인증서 인증의 성공 및 실패 시도를 ssh_user, public_key_fingerprint, signing_ca_fingerprint, certificate_identity, certificate_username 필드와 함께 로그에 기록합니다.

클러스터 배포#

gitlab-sshd 노드가 여러 개인 환경에서는 모든 노드에 걸쳐 구성과 CA 공개 키 파일을 동기화합니다. 구성이 일치하지 않으면 간헐적인 인증 실패가 발생할 수 있습니다. Helm chart 배포에서는 Kubernetes Secret 이 Pod 전체에 자동으로 공유됩니다.

문제 해결#

CA 키 추가 후 gitlab-sshd 시작 실패#

CA 키 파일을 읽을 수 없거나 유효하지 않은 내용이 들어 있으면 gitlab-sshd가 시작되지 않습니다. 로그 출력에 다음과 같은 오류 메시지가 있는지 확인합니다.

certificate rejected: not a user certificate#

인증서가 사용자 인증서가 아니라 호스트 인증서로 생성되었습니다. ssh-keygen으로 서명할 때는 -h 플래그를 사용하지 않습니다.

certificate KeyId does not match GitLab username format#

인증서의 KeyId가 GitLab 사용자 이름 규칙을 따르지 않습니다. 서명할 때 사용한 -I 값이 GitLab 사용자 이름과 정확히 일치하는지 확인합니다.

ssh: cert has expired#

인증서 유효 기간이 지났습니다. -V 플래그를 사용해 적절한 유효 기간으로 새 인증서를 발급합니다.

gitlab-sshd를 사용한 인스턴스 수준 SSH 인증서

GitLab v19.6
Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed
원문 보기

요약

GitLab Self-Managed 인스턴스가 gitlab-sshd를 사용한다면 인스턴스 수준 SSH 인증서 인증을 구성할 수 있습니다. 이 방식은 OpenSSH의 TrustedUserCAKeys 지시어에 해당하는 gitlab-sshd 방식이며, OpenSSH 기반 SSH 인증서 설정의 대안입니다.

히스토리

GitLab Self-Managed 인스턴스가 gitlab-sshd를 사용한다면 인스턴스 수준 SSH 인증서 인증을 구성할 수 있습니다.

  • 인증 기관(Certificate Authority, CA) 인증서로 SSH 인증을 중앙에서 관리합니다.
  • Rails API 호출이나 데이터베이스 변경이 필요하지 않습니다.

이 방식은 OpenSSH의 TrustedUserCAKeys 지시어에 해당하는 gitlab-sshd 방식이며, OpenSSH 기반 SSH 인증서 설정의 대안입니다.

gitlab_sshd 인증 워크플로#

gitlab_sshd 인증 워크플로는 다음 과정을 따릅니다.

  1. 관리자가 CA 키 쌍을 생성합니다.
  2. 관리자가 config.yml의 sshd.trusted_user_ca_keys 아래에 CA 공개 키 파일 경로를 추가합니다.
  3. 관리자가 CA 개인 키로 사용자의 SSH 공개 키에 서명합니다. 인증서의 KeyId는 사용자의 GitLab 사용자 이름으로 설정됩니다.
  4. 사용자가 인증서로 연결하면 다음이 진행됩니다.
    • gitlab-sshd가 인증서 서명과 만료 여부를 검증합니다.
    • gitlab-sshd가 KeyId를 추출해 GitLab 사용자 이름으로 사용합니다.
    • 표준 GitLab 접근 확인이 진행됩니다(사용자 존재 여부, 프로젝트 권한).

gitlab-sshd 프로세스는 인증서 검증 자체에 Rails API 나 데이터베이스 호출이 필요하지 않습니다. /allowed 엔드포인트는 다른 SSH 연결과 마찬가지로 인가를 위해 여전히 호출됩니다.

다른 SSH 인증서 방식과의 비교#

GitLab은 여러 SSH 인증서 인증 방식을 지원합니다.

속성 gitlab-sshd 구성 파일 Admin 영역(베타) OpenSSH 최상위 그룹
CA를 추가하는 위치 config.yml Admin 영역 또는 REST API sshd_config REST API
SSH 서버 gitlab-sshd gitlab-sshd OpenSSH gitlab-sshd
Offering GitLab Self-Managed GitLab Self-Managed GitLab Self-Managed GitLab.com
Tier Free, Premium, Ultimate Free, Premium, Ultimate Free, Premium, Ultimate Premium, Ultimate
범위 인스턴스 전체 인스턴스 전체 인스턴스 전체 최상위 그룹과 그 하위 그룹
사용자 이름 매핑 인증서 KeyId 인증서 KeyId AuthorizedPrincipalsCommand를 통한 인증서 KeyId API를 통한 인증서 ID
엔터프라이즈 사용자 필요 여부 아니요 아니요 아니요 예
문서 신뢰할 수 있는 CA 키 구성 Admin 영역에서 신뢰할 수 있는 CA 키 관리 OpenSSH AuthorizedPrincipalsCommand 그룹 SSH 인증서

사전 요구 사항#

인스턴스 수준 SSH 인증서를 구성하기 전에 다음을 확인합니다.

  • GitLab Self-Managed 인스턴스에서 gitlab-sshd가 활성화되어 있어야 합니다. 자세한 내용은 gitlab-sshd 활성화를 참고합니다.
  • CA 키를 생성하고 config.yml을 편집하려면 서버 파일 시스템에 접근할 수 있어야 합니다.
  • SSH 인증서의 KeyId 필드는 GitLab 사용자 이름과 정확히 일치해야 합니다.

신뢰할 수 있는 CA 키 구성#

인스턴스 수준 SSH 인증서 인증을 구성하는 방법은 다음과 같습니다.

  1. CA 키 쌍을 생성합니다.

    ssh-keygen -t ed25519 -f ssh_user_ca -C "GitLab SSH User CA"
    

    프롬프트가 나타나면 CA 개인 키를 보호할 강력한 패스프레이즈를 입력합니다.

    이 명령은 파일 두 개를 생성합니다.

    • ssh_user_ca: CA 개인 키입니다.
    • ssh_user_ca.pub: CA 공개 키입니다.

    GitLab 서버에는 공개 키만 복사합니다.

    sudo cp ssh_user_ca.pub /etc/gitlab/ssh_user_ca.pub
    

    CA 개인 키는 안전한 위치에 보관하며, GitLab 서버가 아닌 오프라인 시스템에 두는 것이 가장 좋습니다. 개인 키는 사용자 인증서에 서명할 때만 필요합니다.

  2. gitlab-sshd 구성에 CA 공개 키 파일 경로를 추가합니다.

  3. /etc/gitlab/gitlab.rb를 편집합니다.

    gitlab_sshd['trusted_user_ca_keys'] = ['/etc/gitlab/ssh_user_ca.pub']
    
    1. 파일을 저장하고 GitLab을 재구성합니다.

      sudo gitlab-ctl reconfigure
      
  1. CA 공개 키가 담긴 Kubernetes Secret을 생성합니다.

    kubectl create secret generic my-ssh-ca-keys \
      --from-file=ca.pub=ssh_user_ca.pub
    
    1. Helm 값을 내보냅니다.

      helm get values gitlab > gitlab_values.yaml
      
    2. Secret을 참조하도록 gitlab_values.yaml을 편집합니다.

      gitlab:
        gitlab-shell:
          sshDaemon: gitlab-sshd
          config:
            trustedUserCAKeys:
              secret: my-ssh-ca-keys
              keys:
                - ca.pub
      
    3. 파일을 저장하고 새 값을 적용합니다.

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    

    Helm chart 구성에 대한 자세한 내용은 GitLab Shell chart 문서를 참고합니다.

  1. 다음 로그를 확인해 gitlab-sshd가 정상적으로 시작되었는지 검증합니다.

    Loaded trusted user CA keys for instance-level SSH certificates count=1
    

Admin 영역에서 신뢰할 수 있는 CA 키 관리#

히스토리
Feature flag

이 기능의 사용 가능 여부는 기능 플래그로 제어됩니다. 자세한 내용은 히스토리를 참고합니다. 이 기능은 테스트용으로 사용할 수 있으며 프로덕션 환경에서 사용할 준비가 되지 않았습니다.

config.yml의 대안으로 Admin 영역이나 인스턴스 SSH 인증서 API에서 신뢰할 수 있는 CA 키를 추가할 수 있습니다. 변경 사항은 재시작 없이 모든 gitlab-sshd 노드에 즉시 적용됩니다.

두 방식을 동시에 사용할 수 있습니다. gitlab-sshd는 config.yml의 CA 키를 먼저 확인하고, 서명한 CA가 config.yml에 없을 때에만 Admin 영역에서 추가한 CA 키를 확인합니다.

사전 요구 사항:

신뢰할 수 있는 CA 키를 추가하려면 다음을 수행합니다.

  1. 신뢰할 수 있는 CA 키 구성에 설명된 대로 CA 키 쌍을 생성합니다. 공개 키를 GitLab 서버에 복사할 필요는 없습니다.
  2. 오른쪽 위 모서리에서 Admin을 선택합니다.
  3. 왼쪽 사이드바에서 Access > Certificate authorities를 선택합니다.
  4. Add certificate authority를 선택합니다.
  5. Title에 CA의 이름을 입력합니다.
  6. Public key에 CA 공개 키 파일(예: ssh_user_ca.pub)의 내용을 붙여넣습니다.
  7. Add certificate authority를 선택합니다.

GitLab은 FIPS가 활성화된 인스턴스의 더 엄격한 기본값을 포함해, 인스턴스의 SSH 키 제한을 충족하지 않는 CA 공개 키를 거부합니다.

신뢰할 수 있는 CA 키를 삭제하려면 다음을 수행합니다.

  1. 오른쪽 위 모서리에서 Admin을 선택합니다.
  2. 왼쪽 사이드바에서 Access > Certificate authorities를 선택합니다.
  3. CA 옆에서 More actions(⋮) > Delete certificate authority를 선택합니다.
  4. 확인 대화 상자에서 Delete certificate authority를 선택합니다.

CA를 삭제하면 GitLab은 신뢰를 즉시 해제하며, 해당 CA가 서명한 인증서는 더 이상 작동하지 않습니다.

GitLab Premium과 Ultimate에서는 CA를 추가하거나 삭제할 때 GitLab이 감사 이벤트를 기록합니다.

사용자에게 SSH 인증서 발급#

신뢰할 수 있는 CA 키를 구성한 다음에는 사용자에게 인증서를 발급합니다.

  1. 사용자의 SSH 공개 키를 확보합니다 (예: id_ed25519.pub).

  2. -I(identity/KeyId) 플래그를 사용자의 정확한 GitLab 사용자 이름으로 설정해 CA로 사용자의 공개 키에 서명합니다.

    ssh-keygen -s ssh_user_ca -I <gitlab-username> -V +1d user-key.pub
    

    이 명령은 하루 동안 유효한 인증서 파일 (예: user-key-cert.pub)을 생성합니다.

    유효 기간을 더 길게 설정하려면 -V 플래그를 조정합니다. 예를 들어 30 일은 -V +30d, 1 년은 -V +52w로 지정합니다.

  3. 사용자에게 인증서 파일을 배포합니다.

  4. 사용자는 인증서로 연결합니다.

    ssh git@gitlab.example.com
    

    인증서 파일이 기본 명명 규칙(<key> 옆에 <key>-cert.pub)을 따르면 SSH가 자동으로 사용합니다. 그렇지 않으면 인증서를 명시적으로 지정합니다.

    ssh -o CertificateFile=~/.ssh/id_ed25519-cert.pub git@gitlab.example.com
    

여러 인증 기관 사용#

CA 교체나 다중 CA 구성을 위해 CA 공개 키 파일을 여러 개 지정할 수 있습니다.

  1. /etc/gitlab/gitlab.rb를 편집합니다.

    gitlab_sshd['trusted_user_ca_keys'] = [
      '/etc/gitlab/ssh_user_ca_current.pub',
      '/etc/gitlab/ssh_user_ca_next.pub'
    ]
    
  2. 파일을 저장하고 GitLab을 재구성합니다.

    sudo gitlab-ctl reconfigure
    
  1. CA 공개 키 두 개가 모두 담긴 Kubernetes Secret을 생성합니다.

    kubectl create secret generic my-ssh-ca-keys \
      --from-file=ca_current.pub=ssh_user_ca_current.pub \
      --from-file=ca_next.pub=ssh_user_ca_next.pub
    
  2. Helm 값을 내보냅니다.

    helm get values gitlab > gitlab_values.yaml
    
  3. Secret을 참조하도록 gitlab_values.yaml을 편집합니다.

    gitlab:
      gitlab-shell:
        sshDaemon: gitlab-sshd
        config:
          trustedUserCAKeys:
            secret: my-ssh-ca-keys
            keys:
              - ca_current.pub
              - ca_next.pub
    
  4. 파일을 저장하고 새 값을 적용합니다.

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    

하나의 파일에 CA 공개 키를 한 줄에 하나씩 여러 개 담을 수도 있습니다. gitlab-sshd는 파일 전체에서 키 중복을 자동으로 제거합니다.

보안 고려 사항#

인스턴스 수준 SSH 인증서는 CA 개인 키를 가진 모든 사람에게 인증 권한을 부여합니다. 배포하기 전에 다음 보안 고려 사항을 검토합니다.

Warning

CA 개인 키에 접근할 수 있는 사람은 인스턴스의 모든 GitLab 사용자에 대한 인증서에 서명할 수 있습니다. 제한적인 파일 권한, 하드웨어 보안 모듈(HSM), 오프라인 환경 등 적절한 접근 제어로 CA 개인 키를 보호합니다.

인증서 해지 없음#

gitlab-sshd에는 내장된 인증서 해지 메커니즘이 없습니다. 인증서나 CA 키가 손상되면 trusted_user_ca_keys 구성에서 해당 CA를 제거하고 새 CA로 인증서를 재발급합니다. 노출 기간을 최소화하려면 단기 인증서(예: 24 시간)를 사용합니다.

CA 구성 변경에 대한 감사 이벤트 없음#

GitLab은 config.yml의 trusted_user_ca_keys 변경을 감사 이벤트로 기록하지 않습니다. 인프라 모니터링 도구로 이 구성 파일의 변경을 모니터링합니다.

gitlab-sshd는 SSH 인증서 인증의 성공 및 실패 시도를 ssh_user, public_key_fingerprint, signing_ca_fingerprint, certificate_identity, certificate_username 필드와 함께 로그에 기록합니다.

클러스터 배포#

gitlab-sshd 노드가 여러 개인 환경에서는 모든 노드에 걸쳐 구성과 CA 공개 키 파일을 동기화합니다. 구성이 일치하지 않으면 간헐적인 인증 실패가 발생할 수 있습니다. Helm chart 배포에서는 Kubernetes Secret 이 Pod 전체에 자동으로 공유됩니다.

문제 해결#

CA 키 추가 후 gitlab-sshd 시작 실패#

CA 키 파일을 읽을 수 없거나 유효하지 않은 내용이 들어 있으면 gitlab-sshd가 시작되지 않습니다. 로그 출력에 다음과 같은 오류 메시지가 있는지 확인합니다.

certificate rejected: not a user certificate#

인증서가 사용자 인증서가 아니라 호스트 인증서로 생성되었습니다. ssh-keygen으로 서명할 때는 -h 플래그를 사용하지 않습니다.

certificate KeyId does not match GitLab username format#

인증서의 KeyId가 GitLab 사용자 이름 규칙을 따르지 않습니다. 서명할 때 사용한 -I 값이 GitLab 사용자 이름과 정확히 일치하는지 확인합니다.

ssh: cert has expired#

인증서 유효 기간이 지났습니다. -V 플래그를 사용해 적절한 유효 기간으로 새 인증서를 발급합니다.