SAML configuration reference

About SAML configuration

To use SAML single sign-on (SSO) for authentication to GitHub Enterprise Cloud, you must configure both your external SAML identity provider (IdP) and your enterprise or organization on GitHub.com. In a SAML configuration, GitHub Enterprise Cloud functions as a SAML service provider (SP).

You must enter unique values from your SAML IdP when configuring SAML SSO for GitHub Enterprise Cloud, and you must also enter unique values from GitHub Enterprise Cloud on your IdP. For more information about the configuration of SAML SSO for GitHub Enterprise Cloud, see "Configuring SAML single sign-on for your enterprise" or "Enabling and testing SAML single sign-on for your organization."

SAML metadata

The SP metadata for GitHub Enterprise Cloud is available for either organizations or enterprises with SAML SSO. GitHub Enterprise Cloud uses the urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST binding.

Organizations

You can configure SAML SSO for an individual organization in your enterprise. You can also configure SAML SSO for an organization if you use an individual organization on GitHub Enterprise Cloud and do not use an enterprise account. For more information, see "Managing SAML single sign-on for your organization."

The SP metadata for an organization on GitHub.com is available at https://github.com/orgs/ORGANIZATION/saml/metadata, where ORGANIZATION is the name of your organization on GitHub.com.

Enterprises

The SP metadata for an enterprise on GitHub.com is available at https://github.com/enterprises/ENTERPRISE/saml/metadata, where ENTERPRISE is the name of your enterprise on GitHub.com.

SAML attributes

The following SAML attributes are available for GitHub Enterprise Cloud.

To specify more than one value for an attribute, use multiple <saml2:AttributeValue> elements.

<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 response requirements

GitHub Enterprise Cloud requires that the response message from your IdP fulfill the following requirements.

• Your IdP must provide the <Destination> element on the root response document and match the ACS URL only when the root response document is signed. If your IdP signs the assertion, GitHub Enterprise Cloud will ignore the assertion.

• Your IdP must always provide the <Audience> element as part of the <AudienceRestriction> element. The value must match your EntityId for GitHub Enterprise Cloud.

  • If you configure SAML for an organization, this value is https://github.com/orgs/ORGANIZATION.
  • If you configure SAML for an enterprise, this URL is https://github.com/enterprises/ENTERPRISE.

• Your IdP must protect each assertion in the response with a digital signature. You can accomplish this by signing each individual <Assertion> element or by signing the <Response> element.

• Your IdP must provide a <NameID> element as part of the <Subject> element. You may use any persistent name identifier format.

• Your IdP must include the Recipient attribute, which must be set to the ACS URL. The following example demonstrates the attribute.

  <samlp:Response ...>
    <saml:Assertion ...>
      <saml:Subject>
        <saml:NameID ...>...</saml:NameID>
        <saml:SubjectConfirmation ...>
          <saml:SubjectConfirmationData Recipient="https://github.com/enterprises/ENTERPRISE/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>
  

Session duration and timeout

To prevent a person from authenticating with your IdP and staying authorized indefinitely, GitHub Enterprise Cloud periodically invalidates the session for each user account with access to your enterprise's resources. After invalidation, the person must authenticate with your IdP once again. By default, if your IdP does not assert a value for the SessionNotOnOrAfter attribute, GitHub Enterprise Cloud invalidates a session 24 hours after successful authentication with your IdP.

To customize the session duration, you may be able to define the value of the SessionNotOnOrAfter attribute on your IdP. If you define a value less than 24 hours, GitHub Enterprise Cloud may prompt people to authenticate every time GitHub Enterprise Cloud initiates a redirect.

To prevent authentication errors, we recommend a minimum session duration of 4 hours. For more information, see "Troubleshooting SAML authentication."