SAML 구성 참조

SAML 구성 정보

GitHub에 대한 인증에 SAML SSO(Single Sign-On)를 사용하려면 외부 SAML IdP(ID 공급자)와 GitHub Enterprise Server 인스턴스 모두를 구성해야 합니다. SAML 구성에서 GitHub는 SAML SP(Service Provider)로 작동합니다. 엔터프라이즈 인증에 대한 자세한 내용은 ID 및 액세스 관리 정보을(를) 참조하세요.

GitHub는 SAML 2.0 사양에 따라 통합을 제공합니다. 자세한 내용은 OASIS 웹 사이트의 SAML Wiki를 참조하세요.

GitHub에 SAML SSO를 구성할 때는 SAML IdP의 고유한 값을 입력해야 하며, IdP의 GitHub에 있는 고유한 값도 입력해야 합니다.

SAML 메타데이터

GitHub Enterprise Server 인스턴스의 SP 메타데이터는 http(s)://HOSTNAME/saml/metadata에서 사용할 수 있습니다. 여기서 HOSTNAME은 인스턴스의 호스트 이름입니다. GitHub Enterprise Server는 urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST 바인딩을 사용합니다.

값	기타 이름	설명	예시
SP 엔터티 ID	SP URL, 대상 그룹 제한	GitHub Enterprise Server 인스턴스의 최상위 URL	`http(s)://HOSTNAME`
SP 어설션 소비자 서비스(ACS) URL	회신, 수신자 또는 대상 URL	IdP가 SAML 응답을 보내는 URL	`http(s)://HOSTNAME/saml/consume`
SP SSO(Single Sign-On) URL
IdP가 SSO로 시작하는 URL	`http(s)://HOSTNAME/sso`

SAML 특성

다음은 GitHub에 사용할 수 있는 SAML 특성입니다. 관리 콘솔에서 특성 이름을 변경할 수 있습니다(administrator 특성은 제외). 자세한 내용은 관리 웹 UI에서 인스턴스 등록을(를) 참조하세요.

속성	필수	설명
`NameID`		영구 사용자 식별자입니다. 영구 이름 식별자 형식을 사용할 수 있습니다. 대체 어설션 중 하나가 제공되지 않는 한 GitHub는 사용자 이름으로 사용할 `NameID` 요소를 정규화합니다. 자세한 내용은 외부 인증에 대한 사용자 이름 고려 사항을(를) 참조하세요. > [!NOTE] 사람이 읽을 수 있는 영구 식별자를 사용하는 것이 중요합니다. 임시 식별자 형식(예:`urn:oasis:names:tc:SAML:2.0:nameid-format:transient`)을 사용하면 로그인할 때마다 계정이 다시 연결되므로 권한 부여 관리에 악영향을 미칠 수 있습니다.
`SessionNotOnOrAfter`		GitHub에서 연결된 세션을 무효화하는 날짜입니다. 무효화 후 GitHub Enterprise Server 인스턴스에 액세스하려면 사용자는 다시 인증해야 합니다. 자세한 내용은 세션 기간 및 시간 제한을 참조하세요.
`administrator`		값이 `true`인 경우 GitHub에서는 사용자를 사이트 관리자로 자동으로 승격합니다. 값이 비어 있지 않은 한 이 특성을 `true` 이외의 값으로 설정하면 강등됩니다. 이 특성을 생략하거나 값을 비워 두면 사용자의 역할이 변경되지 않습니다.
`username`		의 사용자 이름입니다.
`full_name`		사용자의 프로필 페이지에 표시되는 사용자의 전체 이름입니다.
`emails`		사용자의 이메일 주소입니다. 복수의 주소를 지정할 수 있습니다. GitHub Enterprise Server와 GitHub Enterprise Cloud 사이에 라이선스 사용을 동기화한 경우, GitHub Connect에서는 `emails`를 사용하여 여러 제품에서 고유한 사용자를 식별합니다. 자세한 내용은 GitHub Enterprise Server와 GitHub Enterprise Cloud 간의 라이선스 사용량 동기화을(를) 참조하세요.
`public_keys`		사용자의 일반 SSH 키입니다. 복수의 키를 지정할 수 있습니다.
`gpg_keys`		사용자의 GPG 키입니다. 복수의 키를 지정할 수 있습니다.

특성에 대해 둘 이상의 값을 지정하려면 여러 <saml2:AttributeValue> 요소를 사용합니다.

<saml2:Attribute FriendlyName="public_keys" Name="urn:oid:1.2.840.113549.1.1.1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml2:AttributeValue>ssh-rsa LONG KEY</saml2:AttributeValue>
    <saml2:AttributeValue>ssh-rsa LONG KEY 2</saml2:AttributeValue>
</saml2:Attribute>

SAML 응답 요구 사항

GitHub에서는 IdP의 응답 메시지가 다음 요구 사항을 충족할 것을 요구합니다.

IdP는 루트 응답 문서의 <Destination> 요소에서 제공되고 루트 응답 문서에 서명된 경우에만 ACS URL과 일치해야 합니다. IdP가 어설션에 서명하면 GitHub는 어설션을 무시합니다.
IdP는 항상 <Audience> 요소를 <AudienceRestriction> 요소의 일부로 제공해야 합니다. 값은 GitHub의 EntityId와 일치해야 합니다. 이 값은 GitHub에 액세스하는 URL(예: http(s)://HOSTNAME)입니다.
IdP에서 디지털 서명을 사용하여 응답에 있는 단일 어설션을 제공해야 합니다. <Assertion> 요소에 서명하거나 <Response> 요소에 서명하여 디지털 서명으로 보호할 수 있습니다.
IdP에서 <NameID> 요소를 <Subject> 요소의 일부로 제공해야 합니다. 모든 영구 이름 식별자 형식을 사용할 수 있습니다.

IdP에는 ACS URL로 설정해야 하는 Recipient 특성이 포함되어야 합니다. 다음 예제에서는 이 특성을 확인할 수 있습니다.

<samlp:Response ...>
  <saml:Assertion ...>
    <saml:Subject>
      <saml:NameID ...>...</saml:NameID>
      <saml:SubjectConfirmation ...>
        <saml:SubjectConfirmationData Recipient="https://HOSTNAME/saml/consume" .../>
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:AttributeStatement>
      <saml:Attribute FriendlyName="USERNAME-ATTRIBUTE" ...>
        <saml:AttributeValue>monalisa</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

AuthnRequests의 SAML 서명 인증서

GitHub Enterprise Server를 처음 설정하고 인스턴스를 시작하면 IdP의 SAML 인증서와는 별도로 자체 서명된 SAML 서명 인증서가 생성됩니다. 이 인증서는 IdP로 전송된 SAML AuthnRequests에 서명하는 데 사용되며 10년 동안 유효합니다. /data/user/common/saml-sp.p12에 저장되며 http(s)://HOSTNAME/saml/metadata에서 base64로 인코딩된 형식으로 세부 정보를 볼 수 있습니다.

IdP가 SAML 서명 인증서의 유효성을 검사하거나 SAML 암호화 어설션을 사용하는 경우 인증서가 만료되면 인증 문제가 발생할 수 있습니다. 만료 날짜를 확인하기 위해 GitHub Enterprise Server 관리자는 SSH를 통해 서버에 연결하고 아래 명령을 실행할 수 있습니다. SSH를 통해 관리 셸에 연결을 참조하세요.

sudo openssl pkcs12 -in /data/user/common/saml-sp.p12 -clcerts -nokeys -password pass: | sudo openssl x509 -noout -enddate

SAML SP 서명 인증서가 만료되어 IdP 또는 암호화된 어설션에 필요한 경우, 이 SAML SP 서명 인증서를 다시 생성하려면 GitHub Enterprise Server 관리자가 GitHub Enterprise Server SSH 세션에서 아래 명령을 실행할 수 있습니다.

Note

nomad 명령은 github-unicorn 서비스가 다시 시작될 때 사용자에게 잠시 중단됩니다.

# Backup the old certificate
sudo cp /data/user/common/saml-sp.p12 /data/user/common/saml-sp.p12-$(date +%d%m%Y_%H%M%S)

saml_tempdir=$(sudo mktemp -d)
sudo openssl req -new -newkey rsa:4096 -days 3650 -nodes -x509 -sha256 -subj "/CN=github_enterprise" -keyout $saml_tempdir/saml.key -out $saml_tempdir/saml.crt
sudo openssl pkcs12 -export -inkey $saml_tempdir/saml.key -in $saml_tempdir/saml.crt -nodes -password pass: -out /data/user/common/saml-sp.p12
sudo rm -rf $saml_tempdir

sudo nomad stop github-unicorn
sudo nomad run -hcl1 /etc/nomad-jobs/github/unicorn.hcl

세션 기간 및 시간 제한

사용자가 IdP를 사용하여 인증하면 권한이 무기한 유지되는 일을 방지하기 위해 GitHub에서는 GitHub Enterprise Server 인스턴스에 액세스할 수 있는 각 사용자 계정에 대한 세션을 주기적으로 무효화합니다. 무효화되면 사용자는 IdP를 다시 한 번 인증해야 합니다.

기본적으로 IdP에서 SessionNotOnOrAfter 특성에 대한 값을 어설션하지 않는 경우 GitHub에서는 IdP를 사용해 인증에 성공한 후 1주일이 지나면 세션을 무효화합니다.

GitHub는 IdP에서 SessionNotOnOrAfter 특성 및 값을 구성하는 옵션을 제공하고, 이 특성이 SAML 응답에 포함된 경우 사용자 지정된 세션 기간을 지원합니다. IdP에서 SessionNotOnOrAfter 특성을 허용하지 않는 경우 사이트 관리자는 관리 셸에서 ghe-config saml.default-session-expiration [seconds] 명령을 사용하여 인스턴스의 모든 사용자에 대해 사용자 지정 SAML 세션 시간 제한을 구성할 수 있습니다.

사용자 지정 세션 기간 값을 24시간 미만으로 정의할 경우 GitHub가 GitHub에서 리디렉션을 시작할 때마다 인증 메시지를 표시할 수 있습니다.

인스턴스에서 사용되는 인증 방법과 관계없이 GitHub Enterprise Server는 2주간의 연속 비활성 상태 후 사용자 세션을 종료합니다.