그룹 SSH 인증서 관리

요약

SSH 인증서를 사용하여 GitLab.com에 호스팅된 프로젝트 및 그룹에 대한 Git 액세스를 제어하고 관리합니다. SSH 인증서는 사용자의 신원과 권한을 인증하는 암호화 서명된 문서입니다. GitLab Self-Managed 인스턴스 관리자라면 인스턴스 전체 SSH 인증서 접근 방식을 사용할 수 있습니다.

SSH 인증서를 사용하여 GitLab.com에 호스팅된 프로젝트 및 그룹에 대한 Git 액세스를 제어하고 관리합니다.

SSH 인증서는 사용자의 신원과 권한을 인증하는 암호화 서명된 문서입니다. SSH 인증서는 신뢰할 수 있는 인증 기관(CA)에 의해 발급되며 사용자의 신원, 유효 기간 및 권한과 같은 정보를 포함합니다.

GitLab Self-Managed 인스턴스 관리자라면 인스턴스 전체 SSH 인증서 접근 방식을 사용할 수 있습니다. 다음 방법 중 하나를 선택하세요:

gitlab-sshd를 사용한 인스턴스 수준 SSH 인증서: 시스템 OpenSSH sshd_config를 수정하지 않고 gitlab-sshd에서 직접 신뢰할 수 있는 CA 키를 구성합니다.
OpenSSH AuthorizedPrincipalsCommand를 사용한 사용자 조회: 시스템 OpenSSH 데몬을 사용하여 SSH 인증서를 구성합니다.

SSH 인증서 인증의 이점은 다음과 같습니다:

중앙 집중식 액세스 제어: 개별 사용자 관리 SSH 키 대신 중앙 CA를 통해 액세스를 관리할 수 있습니다.
향상된 보안: SSH 인증서는 기존 SSH 키보다 더 안전합니다.
시간 제한 액세스: 특정 기간 후에 만료되도록 인증서를 설정할 수 있습니다.
간소화된 자격 증명 관리: 조직은 리포지터리 액세스를 위해 승인된 SSH 인증서 자격 증명 목록을 유지할 수 있습니다.
사용자 관리 자격 증명과 독립적: 액세스는 사용자의 개인 공개 SSH 키가 아닌 그룹 관리 인증서로 제어됩니다.

SSH 인증서와 SSH 키#

다음 표는 SSH 인증서와 SSH 키를 비교합니다:

기능	SSH 인증서	SSH 키
액세스 제어	그룹 관리 CA를 통해 중앙 집중화.	개별 사용자 계정에 분산.
만료	내장된 만료 기능.	내장된 만료 기능 없음.
자격 증명 관리	그룹 Owner가 관리.	개별 사용자가 관리.
설정 복잡성	초기 설정이 더 복잡.	초기 설정이 더 간단.

인증 흐름#

다음 다이어그램은 인증서 요청부터 리포지터리 액세스까지 GitLab에서 SSH 인증서 인증이 어떻게 작동하는지 보여줍니다:

Mermaid 다이어그램 (16줄)

소스 코드 보기

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: SSH certificate authentication flow
    accDescr: Sequential diagram showing how a user obtains an SSH certificate from a Group Certificate Authority and uses it to access a Git repository through GitLab.
participant User
participant GroupCA as Group Certificate Authority
participant GitLab
participant GitRepo as Git Repository

User-&gt;&gt;GroupCA: Request SSH certificate
GroupCA-&gt;&gt;User: Issue signed SSH certificate
User-&gt;&gt;GitLab: Attempt to access repository via SSH
GitLab-&gt;&gt;GitLab: Verify certificate is valid and issued by Group CA
GitLab-&gt;&gt;GitRepo: Grant access
GitRepo-&gt;&gt;User: Allow repository operations</code></pre></details></div>

인증 프로세스는 리포지터리 액세스를 허용하기 전에 사용자가 유효한 SSH 인증서를 가지고 있는지 확인합니다.
최상위 그룹에 CA 인증서 추가#
히스토리
GitLab 16.4에서 ssh_certificates_rest_endpoints라는 플래그와 함께 도입됨. 기본적으로 비활성화됩니다.
GitLab 16.9에서 GitLab.com에서 활성화됨.
GitLab 17.7에서 일반 공개됨. 기능 플래그 ssh_certificates_rest_endpoints 제거됨.
사전 요구 사항:

그룹에 대한 Owner 권한이 있어야 합니다.
그룹은 서브그룹이 아닌 최상위 그룹이어야 합니다.

그룹에 CA 인증서를 추가하려면:


인증 기관 파일로 사용할 SSH 키 쌍을 생성합니다:
ssh-keygen -f CA



그룹 SSH 인증서 API를 사용하여 최상위 그룹에 공개 키를 추가하여 그룹과 해당 서브그룹의 프로젝트에 대한 액세스를 부여합니다.


사용자에게 CA 인증서 발급#
사전 요구 사항:

그룹에 대한 Owner 권한이 있어야 합니다.
사용자 인증서는 최상위 그룹과 해당 서브그룹의 프로젝트에 액세스하는 데만 사용할 수 있습니다.
GitLab 사용자와 사용자 인증서를 연결하려면 사용자의 사용자 이름 또는 기본 이메일(user 또는 user@example.com)을 지정해야 합니다.
사용자는 엔터프라이즈 사용자여야 합니다.

사용자 인증서를 발급하려면 이전에 생성한 쌍에서 프라이빗 키를 사용합니다:
ssh-keygen -s CA -I user@example.com -V +1d user-key.pub

(user-key.pub) 키는 사용자가 SSH 인증에 사용하는 SSH 키 쌍의 공개 키입니다.
SSH 키 쌍은 사용자가 생성하거나 그룹 오너 인프라가 SSH 인증서와 함께 프로비저닝합니다.
만료 날짜(+1d)는 SSH 인증서를 그룹 프로젝트에 액세스하는 데 사용할 수 있는 기간을 식별합니다.
사용자 인증서는 최상위 그룹의 프로젝트에만 액세스하는 데 사용할 수 있습니다.
인증서 주체#
앞의 ssh-keygen 예시에서는 인증서 주체(-n 플래그)를 설정하지 않습니다.
주체가 없으면 OpenSSH는 모든 SSH 로그인 사용자에 대해 인증서를 수락합니다. GitLab은 ID(-I) 값을 가진 사용자에 인증서를 매핑합니다.
인증서에 하나 이상의 주체로 서명하는 경우, 사용자가 SSH를 통해 git 사용자로 GitLab에 인증하기 때문에 목록에 git이 포함되어야 합니다(예: git@gitlab.com):
ssh-keygen -s CA -I user@example.com -n git -V +1d user-key.pub

비어 있지 않은 주체 목록에서 git이 누락된 경우, GitLab은 다음과 유사한 오류로 인증서를 거부합니다:
ssh: principal "git" not in the set of valid principals for given certificate: ["user@example.com"]

SSH 인증서 적용#
히스토리
GitLab 16.7에서 enforce_ssh_certificates_via_settings라는 플래그와 함께 도입됨. 기본적으로 비활성화됩니다.
GitLab 16.9에서 GitLab.com에서 활성화됨.
GitLab 17.7에서 일반 공개됨. 기능 플래그 enforce_ssh_certificates_via_settings 제거됨.
SSH 인증서 사용을 강제하고 사용자가 SSH 키 및 액세스 토큰을 사용하여 인증하는 것을 제한할 수 있습니다.
SSH 인증서가 적용되면:

개별 사용자 계정에만 영향을 줍니다.
서비스 계정, 배포 키 및 기타 유형의 내부 계정에는 적용되지 않습니다.
Owner가 그룹에 추가한 SSH 인증서만 리포지터리 액세스 인증에 사용됩니다.

Note
SSH 인증서를 적용하면 일반 사용자의 HTTPS 액세스가 비활성화됩니다.

사전 요구 사항:

그룹에 대한 Owner 권한이 있어야 합니다.

SSH 인증서 사용을 강제하려면:

상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
Settings > General을 선택합니다.
Permissions and group features 섹션을 펼칩니다.
Enforce SSH Certificates 체크박스를 선택합니다.
Save changes를 선택합니다.


Docs/GitLab/User/Group/Ssh_certificates
그룹 SSH 인증서 관리
Tier: Premium, Ultimate
Offering: GitLab.com
원문 보기
번역일: 2026-05-22
요약
SSH 인증서를 사용하여 GitLab.com에 호스팅된 프로젝트 및 그룹에 대한 Git 액세스를 제어하고 관리합니다. SSH 인증서는 사용자의 신원과 권한을 인증하는 암호화 서명된 문서입니다. GitLab Self-Managed 인스턴스 관리자라면 인스턴스 전체 SSH 인증서 접근 방식을 사용할 수 있습니다.
SSH 인증서를 사용하여 GitLab.com에 호스팅된 프로젝트 및 그룹에 대한 Git 액세스를 제어하고 관리합니다.
SSH 인증서는 사용자의 신원과 권한을 인증하는 암호화 서명된 문서입니다. SSH 인증서는 신뢰할 수 있는 인증 기관(CA)에 의해 발급되며 사용자의 신원, 유효 기간 및 권한과 같은 정보를 포함합니다.
GitLab Self-Managed 인스턴스 관리자라면 인스턴스 전체 SSH 인증서 접근 방식을 사용할 수 있습니다. 다음 방법 중 하나를 선택하세요:


gitlab-sshd를 사용한 인스턴스 수준 SSH 인증서:
시스템 OpenSSH sshd_config를 수정하지 않고 gitlab-sshd에서 직접 신뢰할 수 있는 CA 키를 구성합니다.


OpenSSH AuthorizedPrincipalsCommand를 사용한 사용자 조회:
시스템 OpenSSH 데몬을 사용하여 SSH 인증서를 구성합니다.


SSH 인증서 인증의 이점은 다음과 같습니다:

중앙 집중식 액세스 제어: 개별 사용자 관리 SSH 키 대신 중앙 CA를 통해 액세스를 관리할 수 있습니다.
향상된 보안: SSH 인증서는 기존 SSH 키보다 더 안전합니다.
시간 제한 액세스: 특정 기간 후에 만료되도록 인증서를 설정할 수 있습니다.
간소화된 자격 증명 관리: 조직은 리포지터리 액세스를 위해 승인된 SSH 인증서 자격 증명 목록을 유지할 수 있습니다.
사용자 관리 자격 증명과 독립적: 액세스는 사용자의 개인 공개 SSH 키가 아닌 그룹 관리 인증서로 제어됩니다.

SSH 인증서와 SSH 키#
다음 표는 SSH 인증서와 SSH 키를 비교합니다:



기능
SSH 인증서
SSH 키




액세스 제어
그룹 관리 CA를 통해 중앙 집중화.
개별 사용자 계정에 분산.


만료
내장된 만료 기능.
내장된 만료 기능 없음.


자격 증명 관리
그룹 Owner가 관리.
개별 사용자가 관리.


설정 복잡성
초기 설정이 더 복잡.
초기 설정이 더 간단.



인증 흐름#
다음 다이어그램은 인증서 요청부터 리포지터리 액세스까지 GitLab에서 SSH 인증서 인증이 어떻게 작동하는지 보여줍니다:
Mermaid 다이어그램 (16줄)
소스 코드 보기
%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
    accTitle: SSH certificate authentication flow
    accDescr: Sequential diagram showing how a user obtains an SSH certificate from a Group Certificate Authority and uses it to access a Git repository through GitLab.
participant User
participant GroupCA as Group Certificate Authority
participant GitLab
participant GitRepo as Git Repository

User-&gt;&gt;GroupCA: Request SSH certificate
GroupCA-&gt;&gt;User: Issue signed SSH certificate
User-&gt;&gt;GitLab: Attempt to access repository via SSH
GitLab-&gt;&gt;GitLab: Verify certificate is valid and issued by Group CA
GitLab-&gt;&gt;GitRepo: Grant access
GitRepo-&gt;&gt;User: Allow repository operations</code></pre></details></div>

인증 프로세스는 리포지터리 액세스를 허용하기 전에 사용자가 유효한 SSH 인증서를 가지고 있는지 확인합니다.
최상위 그룹에 CA 인증서 추가#
히스토리
GitLab 16.4에서 ssh_certificates_rest_endpoints라는 플래그와 함께 도입됨. 기본적으로 비활성화됩니다.
GitLab 16.9에서 GitLab.com에서 활성화됨.
GitLab 17.7에서 일반 공개됨. 기능 플래그 ssh_certificates_rest_endpoints 제거됨.
사전 요구 사항:

그룹에 대한 Owner 권한이 있어야 합니다.
그룹은 서브그룹이 아닌 최상위 그룹이어야 합니다.

그룹에 CA 인증서를 추가하려면:


인증 기관 파일로 사용할 SSH 키 쌍을 생성합니다:
ssh-keygen -f CA



그룹 SSH 인증서 API를 사용하여 최상위 그룹에 공개 키를 추가하여 그룹과 해당 서브그룹의 프로젝트에 대한 액세스를 부여합니다.


사용자에게 CA 인증서 발급#
사전 요구 사항:

그룹에 대한 Owner 권한이 있어야 합니다.
사용자 인증서는 최상위 그룹과 해당 서브그룹의 프로젝트에 액세스하는 데만 사용할 수 있습니다.
GitLab 사용자와 사용자 인증서를 연결하려면 사용자의 사용자 이름 또는 기본 이메일(user 또는 user@example.com)을 지정해야 합니다.
사용자는 엔터프라이즈 사용자여야 합니다.

사용자 인증서를 발급하려면 이전에 생성한 쌍에서 프라이빗 키를 사용합니다:
ssh-keygen -s CA -I user@example.com -V +1d user-key.pub

(user-key.pub) 키는 사용자가 SSH 인증에 사용하는 SSH 키 쌍의 공개 키입니다.
SSH 키 쌍은 사용자가 생성하거나 그룹 오너 인프라가 SSH 인증서와 함께 프로비저닝합니다.
만료 날짜(+1d)는 SSH 인증서를 그룹 프로젝트에 액세스하는 데 사용할 수 있는 기간을 식별합니다.
사용자 인증서는 최상위 그룹의 프로젝트에만 액세스하는 데 사용할 수 있습니다.
인증서 주체#
앞의 ssh-keygen 예시에서는 인증서 주체(-n 플래그)를 설정하지 않습니다.
주체가 없으면 OpenSSH는 모든 SSH 로그인 사용자에 대해 인증서를 수락합니다. GitLab은 ID(-I) 값을 가진 사용자에 인증서를 매핑합니다.
인증서에 하나 이상의 주체로 서명하는 경우, 사용자가 SSH를 통해 git 사용자로 GitLab에 인증하기 때문에 목록에 git이 포함되어야 합니다(예: git@gitlab.com):
ssh-keygen -s CA -I user@example.com -n git -V +1d user-key.pub

비어 있지 않은 주체 목록에서 git이 누락된 경우, GitLab은 다음과 유사한 오류로 인증서를 거부합니다:
ssh: principal "git" not in the set of valid principals for given certificate: ["user@example.com"]

SSH 인증서 적용#
히스토리
GitLab 16.7에서 enforce_ssh_certificates_via_settings라는 플래그와 함께 도입됨. 기본적으로 비활성화됩니다.
GitLab 16.9에서 GitLab.com에서 활성화됨.
GitLab 17.7에서 일반 공개됨. 기능 플래그 enforce_ssh_certificates_via_settings 제거됨.
SSH 인증서 사용을 강제하고 사용자가 SSH 키 및 액세스 토큰을 사용하여 인증하는 것을 제한할 수 있습니다.
SSH 인증서가 적용되면:

개별 사용자 계정에만 영향을 줍니다.
서비스 계정, 배포 키 및 기타 유형의 내부 계정에는 적용되지 않습니다.
Owner가 그룹에 추가한 SSH 인증서만 리포지터리 액세스 인증에 사용됩니다.

Note
SSH 인증서를 적용하면 일반 사용자의 HTTPS 액세스가 비활성화됩니다.

사전 요구 사항:

그룹에 대한 Owner 권한이 있어야 합니다.

SSH 인증서 사용을 강제하려면:

상단 바에서 Search or go to를 선택하고 그룹을 찾습니다.
Settings > General을 선택합니다.
Permissions and group features 섹션을 펼칩니다.
Enforce SSH Certificates 체크박스를 선택합니다.
Save changes를 선택합니다.
목차
SSH 인증서와 SSH 키인증 흐름최상위 그룹에 CA 인증서 추가사용자에게 CA 인증서 발급인증서 주체SSH 인증서 적용