GitLab Self-Managed 인스턴스의 기본 SSH 인증은 사용자가 SSH 전송을 사용하기 전에 SSH 공개 키를 업로드해야 합니다.

기업 환경과 같은 중앙 집중식 환경에서는 이 요구 사항이 운영 오버헤드를 만들 수 있습니다. 이는 발급 후 24시간 후에 만료되는 키와 같이 SSH 키가 임시적인 경우에 특히 그렇습니다.

이러한 설정에서는 외부 자동화 프로세스가 GitLab에 새 키를 지속적으로 업로드해야 합니다.

OpenSSH 대신 gitlab-sshd를 사용하는 경우 OpenSSH 구성 없이 gitlab-sshd 구성 파일에서 직접 인스턴스 수준 SSH 인증서 인증을 구성할 수 있습니다. 자세한 내용은 gitlab-sshd를 사용한 인스턴스 수준 SSH 인증서를 참조하세요.

GitLab.com 그룹 소유자인 경우 대신 OpenSSH 구성이 필요 없고 GitLab SSH 서버를 사용하는 그룹 범위의 SSH 인증서 기능을 사용해야 합니다. 자세한 내용은 그룹 SSH 인증서 관리를 참조하세요.

OpenSSH 인증서를 사용하는 이유#

OpenSSH 인증서를 사용하면 어떤 GitLab 사용자가 키를 소유하는지에 대한 정보가 키 자체에 인코딩됩니다. 사용자는 프라이빗 CA 서명 키에 액세스해야 하므로 이 정보를 위조할 수 없습니다.

올바르게 설정하면 OpenSSH 인증서는 사용자 SSH 키를 GitLab에 업로드할 필요를 없앱니다.

GitLab Shell을 통한 SSH 인증서 조회 설정#

SSH 인증서의 전체 설정은 이 페이지의 범위를 벗어납니다. SSH 인증서의 작동 방식은 OpenSSH PROTOCOL.certkeys 명세를 참조하고, OpenSSH 인증서 인증에 대한 Red Hat 문서를 참조하세요.

시작하기 전에 이미 SSH 인증서를 설정하고 sshd_config에 CA의 TrustedUserCAKeys를 추가했는지 확인하세요. 예를 들어:

TrustedUserCAKeys /etc/security/mycompany_user_ca.pub

일반적으로 TrustedUserCAKeys는 GitLab 서버 자체에 대한 시스템 로그인에도 사용될 것이기 때문에 이러한 설정에서 Match User git 아래에 범위가 지정되지 않지만, 설정에 따라 다를 수 있습니다. CA가 GitLab에만 사용되는 경우 아래에 설명된 Match User git 섹션에 이를 배치하는 것을 고려하세요.

해당 CA에서 발급한 각 SSH 인증서는 사용자의 GitLab 사용자 이름에 해당하는 "key ID"를 반드시 가져야 합니다. AuthorizedPrincipalsCommand는 이 key ID를 GitLab 사용자 이름에 매핑하므로, GitLab은 공개 키와 사용자 이름 매핑에 의존하는 대신 인증서에서 사용자 이름을 추출합니다. GitLab과 함께 제공되는 기본 명령은 key ID와 GitLab 사용자 이름 간에 1:1 매핑을 가정합니다.

다음 예시는 key ID가 aearnfjord인 인증서를 보여줍니다(간략하게 일부 출력 생략):

$ ssh-add -L | grep cert | ssh-keygen -L -f -

(stdin):1:
        Type: ssh-rsa-cert-v01@openssh.com user certificate
        Public key: RSA-CERT SHA256:[...]
        Signing CA: RSA SHA256:[...]
        Key ID: "aearnfjord"
        Serial: 8289829611021396489
        Valid: from 2018-07-18T09:49:00 to 2018-07-19T09:50:34
        Principals:
                sshUsers
                [...]
        [...]

key ID가 GitLab 사용자 이름과 직접 일치할 필요는 없습니다. 예를 들어, 서버에 prod-aearnfjord 사용자로 로그인하는 사용자는 prod-aearnfjord key ID를 가질 수 있습니다. 이 경우 기본값을 사용하는 대신 해당 매핑을 수행하는 자체 AuthorizedPrincipalsCommand를 제공해야 합니다.

다음으로, sshd_config에서 git 사용자에 대한 AuthorizedPrincipalsCommand를 설정합니다. 대부분의 경우 GitLab과 함께 제공되는 기본 명령을 사용할 수 있습니다:

Match User git
    AuthorizedPrincipalsCommandUser root
    AuthorizedPrincipalsCommand /opt/gitlab/embedded/service/gitlab-shell/bin/gitlab-shell-authorized-principals-check %i sshUsers

이 명령은 다음과 같은 출력을 생성합니다:

command="/opt/gitlab/embedded/service/gitlab-shell/bin/gitlab-shell username-{KEY_ID}",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty {PRINCIPAL}

여기서 {KEY_ID}는 스크립트에 전달된 %i 인수(예: aeanfjord)이고, {PRINCIPAL}은 전달된 주체(예: sshUsers)입니다.

sshUsers 부분을 사용자 정의해야 합니다. GitLab에 로그인할 수 있는 모든 사용자의 키에 보장적으로 포함된 일부 주체이거나, 사용자에게 하나가 있는 주체 목록을 제공해야 합니다. 예를 들어:

    [...]
    AuthorizedPrincipalsCommand /opt/gitlab/embedded/service/gitlab-shell/bin/gitlab-shell-authorized-principals-check %i sshUsers windowsUsers

주체와 보안#

원하는 만큼 많은 주체를 제공할 수 있습니다. 각 주체는 sshd_config(5)의 AuthorizedPrincipalsFile에 대해 설명된 대로 별도의 authorized_keys 출력 줄이 됩니다.

OpenSSH에서 AuthorizedKeysCommand의 주체는 일반적으로 해당 서버에 로그인이 허용된 "그룹"입니다. GitLab은 이 OpenSSH 요구 사항을 충족하기 위해서만 주체를 사용하며, 중요한 것은 key ID가 올바른지 여부입니다. GitLab은 key ID를 추출한 후 해당 사용자에 대한 자체 액세스 제어를 적용합니다(예: 사용자가 접근할 수 있는 프로젝트).

수락하는 주체에 관대해도 됩니다. 예를 들어, 사용자가 GitLab에 액세스 권한이 없는 경우 유효하지 않은 사용자 오류로 인증이 실패합니다.

authorized_keys 파일과의 상호작용#

SSH 인증서는 authorized_keys 파일과 함께 작동하며, authorized_keys 파일은 폴백 역할을 합니다.

AuthorizedPrincipalsCommand가 사용자를 인증할 수 없으면 OpenSSH는 ~/.ssh/authorized_keys 파일 확인 또는 AuthorizedKeysCommand 사용으로 되돌아갑니다. 따라서 SSH 인증서와 함께 데이터베이스에서 인증된 SSH 키의 빠른 조회를 사용해야 할 수도 있습니다.

대부분의 사용자의 경우 AuthorizedPrincipalsCommand가 인증을 처리하며, authorized_keys 파일은 배포 키와 같은 특정 경우에만 사용됩니다. 설정에 따라 일반 사용자에게는 AuthorizedPrincipalsCommand만으로 충분할 수 있으며, 이 경우 authorized_keys 파일은 자동화된 배포 키 액세스용으로 남습니다.

authorized_keys 폴백을 유지할지 결정하려면, 일반 사용자의 키 수(특히 자주 갱신되는 키)를 배포 키 수와 비교하여 따져보세요.

기타 보안 주의 사항#

사용자는 SSH 공개 키를 프로필에 수동으로 업로드하고 ~/.ssh/authorized_keys 폴백에 의존하여 SSH 인증서 인증을 우회할 수 있습니다. 배포 키가 아닌 SSH 키를 사용자가 업로드하지 못하도록 하는 설정이 이슈 23260에서 제안되었습니다.

이 제한을 직접 적용하려면 사용자 정의 AuthorizedKeysCommand를 제공하세요. 이 명령은 gitlab-shell-authorized-keys-check에서 반환된 key ID가 배포 키인지 확인하고, 모든 비배포 키를 거부합니다.

SSH 키가 없는 사용자에 대한 전역 경고 비활성화#

기본적으로 GitLab은 프로필에 SSH 키를 업로드하지 않은 사용자에게 "프로필에 SSH 키를 추가할 때까지 SSH를 통해 리포지터리를 pull하거나 push할 수 없습니다" 경고를 표시합니다. 이 경고는 SSH 인증서를 사용할 때 역효과를 냅니다. 사용자가 자신의 키를 업로드하지 않아도 되기 때문입니다.

이 경고를 전역적으로 비활성화하려면:

• 오른쪽 상단에서 Admin을 선택하세요.

• 왼쪽 사이드바에서 Settings > General을 선택하세요.

• Account and limit 섹션에서 Inform users without uploaded SSH keys that they can't push over SSH until one is added 체크박스를 선택 해제하세요.

이 설정은 SSH 인증서와 함께 사용하기 위해 특별히 추가되었습니다. SSH 인증서를 사용하지 않고도 다른 이유로 경고를 숨기기 위해 이 설정을 끌 수 있습니다.