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

요약

GitLab Self-Managed 인스턴스에서 gitlab-sshd를 사용하는 경우, 인스턴스 수준 SSH 인증서 인증을 구성할 수 있습니다. 인증 기관(Certificate Authority, CA) 인증서를 사용하여 SSH 인증을 중앙에서 관리할 수 있습니다.

히스토리

GitLab 18.11에서 도입됨.

GitLab Self-Managed 인스턴스에서 gitlab-sshd를 사용하는 경우, 인스턴스 수준 SSH 인증서 인증을 구성할 수 있습니다.

인증 기관(Certificate Authority, CA) 인증서를 사용하여 SSH 인증을 중앙에서 관리할 수 있습니다.
Rails API 호출이나 데이터베이스 변경이 필요하지 않습니다.

이 방식은 OpenSSH의 TrustedUserCAKeys 지시어와 동등한 gitlab-sshd 방식으로, OpenSSH 기반 SSH 인증서 설정의 대안입니다.

gitlab_sshd 인증 워크플로#

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

관리자가 CA 키 쌍을 생성합니다.
관리자가 config.yml의 sshd.trusted_user_ca_keys 아래에 CA 공개 키 파일 경로를 추가합니다.
관리자가 CA 개인 키로 사용자의 SSH 공개 키에 서명합니다. 인증서의 KeyId는 사용자의 GitLab 사용자 이름으로 설정됩니다.
사용자가 인증서로 연결하면:

gitlab-sshd가 인증서 서명과 만료 여부를 검증합니다.
- gitlab-sshd가 KeyId를 추출하고 이를 GitLab 사용자 이름으로 사용합니다.
- 표준 GitLab 접근 확인이 진행됩니다(사용자 존재 여부, 프로젝트 권한).

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

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

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

기능	인스턴스 수준 (gitlab-sshd)	인스턴스 수준 (OpenSSH)	그룹 수준
구성 위치	config.yml	sshd_config	GitLab API/UI
SSH 서버	gitlab-sshd	OpenSSH	gitlab-sshd
Offering	GitLab Self-Managed	GitLab Self-Managed	GitLab.com
Tier	Free, Premium, Ultimate	Free, Premium, Ultimate	Premium, Ultimate
범위	인스턴스 전체(네임스페이스 제한 없음)	인스턴스 전체(네임스페이스 제한 없음)	최상위 그룹
사용자 이름 매핑	인증서 KeyId	AuthorizedPrincipalsCommand를 통한 인증서 Key ID	API를 통한 인증서 ID
엔터프라이즈 사용자 필요 여부	아니요	아니요	예
문서	이 페이지	OpenSSH AuthorizedPrincipalsCommand	그룹 SSH 인증서

사전 요구 사항#

인스턴스 수준 SSH 인증서를 구성하기 전에 다음을 확인하세요:

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

신뢰할 수 있는 CA 키 구성#

인스턴스 수준 SSH 인증서 인증을 구성하려면:

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 서버가 아닌 오프라인 시스템에 보관하는 것이 이상적입니다. 개인 키는 사용자 인증서에 서명할 때만 필요합니다.
gitlab-sshd 구성에 CA 공개 키 파일 경로를 추가합니다.

::Tabs

:::TabTitle Linux 패키지 (Omnibus)

/etc/gitlab/gitlab.rb를 편집합니다:
```
gitlab_sshd['trusted_user_ca_keys'] = ['/etc/gitlab/ssh_user_ca.pub']
```
1. 파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```
:::TabTitle Helm chart (Kubernetes)
1. CA 공개 키가 포함된 Kubernetes Secret을 생성합니다:
```
kubectl create secret generic my-ssh-ca-keys \
  --from-file=ca.pub=ssh_user_ca.pub
```
2. Helm values를 내보냅니다:
```
helm get values gitlab > gitlab_values.yaml
```
3. gitlab_values.yaml을 편집하여 Secret을 참조합니다:
```
gitlab:
  gitlab-shell:
    sshDaemon: gitlab-sshd
    config:
      trustedUserCAKeys:
        secret: my-ssh-ca-keys
        keys:
          - ca.pub
```
4. 파일을 저장하고 새 값을 적용합니다:
```
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```
Helm chart 구성에 대한 자세한 내용은 GitLab Shell chart 문서를 참조하세요.

::EndTabs
다음 로그를 확인하여 gitlab-sshd가 성공적으로 시작되었는지 검증합니다:
```
Loaded trusted user CA keys for instance-level SSH certificates count=1
```

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

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

사용자의 SSH 공개 키(예: id_ed25519.pub)를 가져옵니다.
-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로 설정합니다.
사용자에게 인증서 파일을 배포합니다.
사용자는 인증서를 사용하여 연결합니다:
```
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 공개 키 파일을 지정할 수 있습니다.

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

gitlab_sshd['trusted_user_ca_keys'] = [
  '/etc/gitlab/ssh_user_ca_current.pub',
  '/etc/gitlab/ssh_user_ca_next.pub'
]

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

두 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

Helm values를 내보냅니다:

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml을 편집하여 Secret을 참조합니다:

gitlab:
  gitlab-shell:
    sshDaemon: gitlab-sshd
    config:
      trustedUserCAKeys:
        secret: my-ssh-ca-keys
        keys:
          - ca_current.pub
          - ca_next.pub

파일을 저장하고 새 값을 적용합니다:

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

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

보안 고려 사항#

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

CA 개인 키에 접근할 수 있는 사람은 누구나 인스턴스의 모든 GitLab 사용자에 대한 인증서에 서명할 수 있습니다. 제한적인 파일 권한, HSM(Hardware Security Module), 또는 오프라인 환경과 같은 적절한 접근 제어로 CA 개인 키를 보호하세요.

인증서 해지 없음#

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

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

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

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

클러스터 배포#

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

문제 해결#

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

CA 키 파일을 읽을 수 없거나 유효하지 않은 콘텐츠가 포함된 경우 gitlab-sshd가 시작되지 않습니다. 다음과 같은 오류 메시지가 있는지 로그 출력을 확인하세요:

failed to load trusted user CA keys: 파일을 읽을 수 없습니다. 파일이 존재하고 올바른 권한이 있는지 확인하세요(git 사용자가 읽을 수 있어야 함).
failed to parse trusted user CA key in file: 파일 콘텐츠가 유효한 SSH 공개 키가 아닙니다. 파일에 OpenSSH 형식의 유효한 공개 키가 포함되어 있는지 확인하세요.
trusted_user_ca_keys configured but no valid CA keys were loaded: 구성에 CA 키 파일이 나열되어 있지만 유효한 키가 없습니다.

인증서 거부됨: 사용자 인증서가 아님#

인증서가 사용자 인증서 대신 호스트 인증서로 생성되었습니다. ssh-keygen으로 서명할 때 -h 플래그를 사용하지 마세요.

인증서 KeyId가 GitLab 사용자 이름 형식과 일치하지 않음#

인증서의 KeyId가 GitLab 사용자 이름 규칙을 따르지 않습니다. 서명 중에 사용된 -I 값이 정확한 GitLab 사용자 이름과 일치하는지 확인하세요.

ssh: cert has expired#

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