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 사용자가 키를 소유하는지에 대한 정보가 키 자체에 인코딩됩니다. OpenSSH는 사용자가 프라이빗 CA 서명 키에 액세스해야 하기 때문에 이를 위조할 수 없음을 보장합니다.

올바르게 설정하면 사용자 SSH 키를 GitLab에 업로드할 필요가 전혀 없어집니다.

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

SSH 인증서를 완전히 설정하는 방법은 이 문서의 범위를 벗어납니다. 작동 방식은 OpenSSH의 PROTOCOL.certkeys를 참조하고, 예시는 RedHat의 문서를 참조하세요.

이미 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"를 반드시 가져야 합니다. 예를 들어(간략하게 일부 출력 생략):

$ 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
                [...]
        [...]

기술적으로 이것이 반드시 사실은 아닙니다. 예를 들어, 서버에 prod-aearnfjord 사용자로 로그인하는 SSH 인증서의 경우 prod-aearnfjord일 수 있지만, 그 경우 제공된 기본값을 사용하는 대신 해당 매핑을 수행하는 자체 AuthorizedPrincipalsCommand를 지정해야 합니다.

중요한 점은 기본 명령이 둘 사이에 1=1 매핑이 있다고 가정하기 때문에 AuthorizedPrincipalsCommand가 "key ID"에서 GitLab 사용자 이름으로 매핑할 수 있어야 한다는 것입니다. 이 전체 목적은 기본 공개 키와 사용자 이름 매핑 같은 것에 의존하는 대신 키 자체에서 GitLab 사용자 이름을 추출할 수 있도록 하는 것입니다.

그런 다음 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은 해당 사용자에 대한 자체 ACL을 적용합니다(예: 사용자가 접근할 수 있는 프로젝트).

따라서 수락하는 것에 지나치게 관대해도 괜찮습니다. 예를 들어, 사용자가 GitLab에 액세스 권한이 없는 경우, 유효하지 않은 사용자에 대한 메시지와 함께 오류가 생성됩니다.

authorized_keys 파일과의 상호작용#

이전에 설명한 대로 SSH 인증서가 설정된 경우 authorized_keys 파일과 함께 사용할 수 있으므로 authorized_keys 파일이 폴백으로 제공됩니다.

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

대부분의 사용자에 대해 SSH 인증서는 AuthorizedPrincipalsCommand를 사용하여 인증을 처리하며, ~/.ssh/authorized_keys 파일은 주로 배포 키와 같은 특정 경우의 폴백으로 사용됩니다. 그러나 설정에 따라 일반 사용자에게만 AuthorizedPrincipalsCommand를 독점적으로 사용하는 것으로 충분할 수 있습니다. 이러한 경우 authorized_keys 파일은 자동화된 배포 키 액세스 또는 기타 특정 시나리오에만 필요합니다.

일반 사용자(특히 자주 갱신되는 경우)와 배포 키의 키 수 사이의 균형을 고려하여 환경에 authorized_keys 폴백을 유지하는 것이 필요한지 결정합니다.

기타 보안 주의 사항#

사용자는 SSH 공개 키를 프로필에 수동으로 업로드하여 SSH 인증서 인증을 우회할 수 있으며, ~/.ssh/authorized_keys 폴백을 사용하여 인증할 수 있습니다.

사용자가 배포 키가 아닌 SSH 키를 업로드하지 못하도록 하는 설정을 추가하는 열린 이슈가 있습니다.

이 제한을 적용하는 자체 검사를 구축할 수 있습니다. 예를 들어, gitlab-shell-authorized-keys-check에서 반환된 발견된 key-ID가 배포 키인지 여부를 확인하는 사용자 정의 AuthorizedKeysCommand를 제공합니다(모든 비배포 키는 거부되어야 합니다).

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

기본적으로 GitLab은 프로필에 SSH 키를 업로드하지 않은 사용자에게 "SSH를 통해 프로젝트 코드를 pull하거나 push할 수 없습니다" 경고를 표시합니다.

SSH 인증서를 사용할 때 사용자는 자신의 키를 업로드하지 않아도 되므로 이것은 역효과입니다.

이 경고를 전역적으로 비활성화하려면 "애플리케이션 설정 -> 계정 및 제한 설정"으로 이동하여 "사용자에게 SSH 키 추가 메시지 표시" 설정을 비활성화합니다.

이 설정은 SSH 인증서와 함께 사용하기 위해 특별히 추가되었지만, 다른 이유로 경고를 숨기고 싶다면 SSH 인증서를 사용하지 않고도 비활성화할 수 있습니다.