GitHub

Configure PingFederate for provisioning and SSO

Configure a service provider (SP) connection in PingFederate to manage outbound provisioning and single sign-on (SSO) to GitHub.

About this task

Outbound provisioning details are managed within an SP connection and can be added to an existing SP connection.

The SCIM API requires that you have GitHub Enterprise Cloud with SAML SSO enabled for the enterprise. For more information, see .github.com/en/enterprise-cloud@latest/rest/enterprise-admin/scim?apiVersion=2022-11-28//[About SCIM] in the GitHub documentation.

Steps

  1. In the PingFederate administrative console, configure the datastore that PingFederate will use as the source of user data.

    For configuration instructions, see Datastores in the PingFederate documentation.

    On the Data Store Type tab, you must select Directory (LDAP) as the Type. GitHub EMU enterprises require SCIM provisioning, and Directory (LDAP) is the only datastore type supported for PingFederate SCIM provisioning.

  2. Create a new SP connection or select an existing SP connection from the SP Connections page.

  3. On the Connection Template tab, select Use a template for this connection.

  4. In the Connection Template list, select GitHub EMU Connector.

    You must select GitHub EMU Connector, not GitHub Connector. This integration only supports the EMU connector.

    If this selection isn’t available, verify the connector installation and restart PingFederate.
    Screen capture of the connection template tab showing the Use a Template for This Connection option selected and the GitHub EMU Connector selected in the Connection Template field.

  5. In the Metadata File section, import one of the following metadata files.

    Choose from:

    • The enterprise’s SAML metadata, which you can download at the following URL: https://github.com/enterprises/<enterprise_slug>/saml/metadata

    • The sample metadata file that’s packaged with the GitHub EMU Connector: github-emu-saml-metadata.xml

  6. On the Connection Type tab, ensure that both the Outbound Provisioning and Browser SSO Profiles check boxes are selected.

  7. On the General Info tab, enter your corresponding enterprise name in the Partner’s Entity ID (Connection ID) field, then click Next.

    The default values on the General Info tab are from the metadata file that you selected previously.

    Screen capture of the General Info tab with the Partner’s Entity ID, Connection Name, and Base URL fields populated.

  8. On the Browser SSO tab, configure your browser SSO settings.

    For more information on configuring browser SSO, see the following sections under Identity provider SSO configuration:

    • Managing IdP adapters

    • Configure IdP Browser SSO

      1. Click Configure Browser SSO.

      2. On the Assertion Creation tab, click Next.

      3. On the Protocol Settings tab, click Configure Protocol Settings.

      4. On the Summary tab, click Assertion Consumer Service URL, edit the existing entry on the Assertion Consumer Service URL page, and enter the Endpoint URL corresponding to your enterprise name.

        Example:

        https://github.com/enterprises/<enterprise slug>/saml/consume

      5. Click Update and Done, then click Done on the Protocol Settings tab.

  9. On the Credentials tab, click Configure Credentials, then go to the Digital Signature Settings tab, select the signing certificate, and click Done, then Next.

  10. On the Outbound Provisioning tab, click Configure Provisioning.

  11. On the Target tab, enter the Base URL and Access Token values.

    Do not change any of the default Provisioning Options for this integration. Make sure that User Create, User Update, and User Disable/Delete are selected and that Remove User Action is set to Disable.
    Screen capture of the Target tab with the default provisioning options configured.

    See the following table for instructions on how to configure the required values.

    Field Name Description

    Base URL

    The base URL for GitHub. For example:https://api.github.com/scim/v2/enterprises/<enterprise slug>

    To determine your enterprise name, see Accessing an enterprise in the GitHub documentation.

    Access Token

    The access token that the provisioner uses to make authenticated API calls to GitHub.

    Provisioning Options

    User Create
    True (default)

    Users will be created in GitHub.

    Make sure that User Create is selected for this integration.
    False

    Users will not be created in GitHub.

    The provisioner.log will display a warning within the create user workflow that the user was not created in GitHub.

    User Update
    True (default)

    Users will be updated in GitHub.

    Make sure that User Update is selected for this integration.
    False

    Users will not be updated in GitHub.

    The provisioner.log will display a warning within the update user workflow that the user was not updated in GitHub.

    Enabling a previously suspended user in GitHub will trigger a create and as such, users can be enabled when User Update is not selected.

    User Disable/Delete
    True (default)

    Users will be suspended or disabled in GitHub.

    Make sure that User Disable/Delete is selected for this integration.
    False

    Users will not be suspended or disabled in GitHub.

    The provisioner.log will display a warning indicating that the user was not suspended in GitHub.

    Remove User Action
    Disable (default)

    PingFederate disables the user in GitHub.

    Make sure that Disable is selected for this integration.
    Delete

    PingFederate suspends the user in GitHub.

    The Remove User Action applies when User Disable/Delete is selected, and:

    • a previously-provisioned user no longer meets the condition set on the Source Location tab, or

    • a user has been disabled or deleted from the datastore.

  12. Click Next.

  13. Configure a channel and complete the provisioning configuration.

    If you aren’t ready to complete the provisioning configuration, you can click Save and return to the configuration page later. To return to the configuration page, select the connection from Identity Provider → SP Connections → Manage All.

    For more information, see the following sections under Outbound provisioning for IdPs in the PingFederate documentation:

    The LDAP attribute must contain one of the following string values:

    • enterprise_owner

    • billing_manager

    • user

    • guest_collaborator

      1. Click Done.

      2. After you finish mapping attributes, click Next.

      3. In the Channel Status section of the Activation and Summary tab, click Active.

      4. Click Done.

  14. Link users authenticating through SAML to their provisioned SCIM identities in the GitHub enterprise.

    The SAML NameID and SCIM userName values must match for each user. Otherwise, a PingFederate user attempting to access their EMU account through SAML authentication might get a 404 error and an error message such as:

    +

    Enterprise Managed Users must be provisioned via SCIM

    To make sure that these values match in PingFederate:

    1. On the Attribute Contract Fulfillment tab, make sure that the Value of the SAML_SUBJECT contract attribute is sAMAccountName if you are using Active Directory as the LDAP datastore, or username if you are using another LDAP datastore like PingDirectory.

    To find the Attribute Contract Fulfillment tab:

    1. On the Browser SSO tab, click Configure Browser SSO.

    2. Go to the Assertion Creation tab and click Configure Assertion Creation.

    3. Go to the Authentication Source Mapping tab, click Map New Adapter Instance, and then go to the Attribute Contract Fulfillment tab.

      1. On the Attribute Mapping tab, make sure that the Username field is mapped to the same attribute value that the SAML_SUBJECT contract attribute is mapped to on the Attribute Contract Fulfillment tab. For example, this value might be sAMAccountName if you are using Active Directory, or username if you are using PingDirectory.

  15. Optional: Configure the Synchronization Frequency of your outbound provisioning channels.

    By default, PingFederate attempts to process user, group, and group member updates and send these updates to GitHub every 60 seconds. This interval is controlled by the Synchronization Frequency value, which affects all outbound provisioning channels.

    To update this value:

    1. Go to System → Server → Protocol Settings and select the Outbound Provisioning tab.

    2. Enter a new Synchronization Frequency value, then click Save.

    Screen capture of the Outbound Provisioning tab of the Protocol Settings page with the Synchronization Frequency field highlighted.