Configuring authentication and provisioning with PingFederate

You can use PingFederate as an identity provider (IdP) to centrally manage authentication and user provisioning for your GitHub Enterprise Server instance.

Who can use this feature?

Site administrators with admin access to the IdP

In this article

Note

SCIM for GitHub Enterprise Server is currently in public beta and subject to change. GitHub recommends testing with a staging instance first. See "Setting up a staging instance."

When you use an IdP for IAM on GitHub Enterprise Server, SAML SSO controls and secures access to enterprise resources like repositories, issues, and pull requests. SCIM automatically creates user accounts and manages access to your GitHub Enterprise Server instance when you make changes on your IdP. You can also synchronize teams on GitHub Enterprise Server with groups on your IdP. For more information, see "About user provisioning with SCIM on GitHub Enterprise Server."

Overview

This guide will help you to set up both SAML authentication and SCIM provisioning for GitHub Enterprise Server on PingFederate.

Before you start, please note the following:

  • The use of PingFederate as an IdP for GitHub Enterprise Server is in beta. Please contact your account team to provide feedback.
  • This guide is based on PingFederate version 12.1. Instructions may vary for other versions.
  • This guide assumes that you are using an LDAP server as the backing data store. JDBC data stores should work, but the instructions may vary slightly.
  • This guide provides the minimal steps to configure a working setup. Because your identity directory may be connected to PingFederate differently, you’ll need to pick the correct data attributes for SAML and SCIM based on what is available from your backing data store.

Prerequisites

The general prerequisites for using SCIM on GitHub Enterprise Server apply. See the "Prerequisites" section in "Configuring SCIM provisioning to manage users."

In addition:

  • To configure SCIM, you must have completed steps 1 to 4 in "Configuring SCIM provisioning to manage users."
    • You will need the personal access token (classic) created for the setup user to authenticate requests from PingFederate.
  • You must have installed the "GitHub EMU connector" on PingFederate. To download and install the connector, see Install the connector in the PingIdentity documentation.
    • You may need to configure the firewall in PingFederate to allow outbound connections to the https://HOSTNAME/api/v3/scim/v2 endpoint on your GitHub Enterprise Server instance.
  • PingFederate's "provisioner mode" must be set to a value that allows SCIM provisioning. See the "Before you begin" section in PingIdentity's Configuring outbound provisioning settings guide.
  • During this procedure, you will need to upload an X509 certificate to PingFederate. You may want to create and store the certificate before proceeding. You will also need the challenge password for the certificate. See the "Example of creating an X509 certificate" section later in this article.

1. Configure SAML

In this section you will create a SAML connector in PingFederate, set up an LDAP IdP adapter instance, and manage SAML output from your IdP adapter.

  1. Create a SAML adapter
  2. Set up an LDAP IdP adapter instance
  3. Manage SAML output from your IdP adapter

Before starting this section, ensure you have followed steps 1 and 2 in "Configuring SCIM provisioning to manage users."

Create a SAML adapter

  1. Open the PingFederate administrative console.

  2. Click Applications in the header, then click SP Connections in the left sidebar.

  3. Click Use a template for this connection, then select the "GitHub EMU Connector" from the "Connection Template" dropdown.

    Note

    If you don't see this option, the GitHub EMU Connector has not been installed. If you need assistance, contact your Ping representative.

  4. In a new tab, sign in to your GitHub Enterprise Server instance as the built-in setup user, then navigate to https://HOSTNAME/saml/metadata. Download the page as an XML file.

  5. On the PingFederate "SP Connection" page, upload the file from the previous step as the metadata file. Ensure you do this within 5 minutes of downloading the file.

  6. Go to the "Connection Type" tab.

  7. Select Browser SSO Profiles, and deselect Outbound provisioning (this will be enabled later).

  8. Click Next.

  9. On the "Connection Options" tab, ensure only Browser SSO is selected.

  10. Click Next.

  11. On the "General Info" tab, enter the following details.

    • "Partner’s Entity ID": your GitHub Enterprise Server host URL (https://HOSTNAME.com)
    • "Connection Name": A descriptive name for your SP connection within PingFederate
    • "Base URL": your GitHub Enterprise Server host URL (https://HOSTNAME.com)
    • "Transaction Logging": Standard
    • All other fields may be left blank.

  12. Click Next.

  13. Click Configure Browser SSO.

  14. Click Configure Assertion Creation.

  15. On the "Authentication Source Mapping" tab, click Map New Adapter Instance.

  16. On the "Adapter Instance" Tab, click Manage Adapter Instances.

  17. Click Create New Instance.

Set up an LDAP IdP adapter instance

Note

This section applies if you use an LDAP server. If you don't use LDAP, you will need to connect to your adapter using the appropriate settings for your requirements.

  1. On the "Create Adapter Instance" page on PingFederate, on the "Type" tab, enter the following details.

    • "Instance Name": A name to identify the instance, such as pfghadapter
    • "Instance ID": An ID for the instance, such as pfghadapter
    • "Type": HTML Form IDP Adaptor
    • "Parent Instance": None

  2. Click Next.

  3. On the "IDP Adapter" tab, at the bottom of the page, click Manage Password Credential Validators.

  4. Click Create New Instance.

  5. On the "Type" tab, enter the following details.

    • "Instance Name": A name to identify the instance, such as pfghdocscv
    • "Instance ID": An ID for the instance, such as pfghdocscv
    • "Type": LDAP Username Password Credential Validator
    • "Parent Instance": None

  6. Click Next.

  7. On the "Instance Configuration" tab, click Manage Data Stores.

  8. Click Add New Data Store.

  9. On the "Data Store Type" tab, enter the following details.

    • "Instance Name": Any unique value, such as pfghdocsds
    • "Type": Directory (LDAP)
    • "Mask Values In Log": Deselected

  10. Click Next.

  11. On the "LDAP Configuration" tab, configure your LDAP server details.

  12. Click Test Connection. You should see "Connectivity test was successful."

  13. At the bottom of the page, click Advanced.

  14. Click the "LDAP Binary Attributes" tab, and add guidAttribute and objectGUID as attributes.

  15. Click Done. You should be back on the "LDAP Configuration" tab.

  16. Click Next, then Save.

  17. On the "Manage Data Stores" tab, click Done.

  18. On the "Instance Configuration" tab, enter the following details.

    • "LDAP Datastore": The name of the data store you created above
    • "Search Base": The location in the directory where you want LDAP searches to begin
    • "Search Filter": A filter that ensures the username the user enters when signing in matches a field in the LDAP server (for example: sAMAccountName=${username})
    • "Scope of Search": Subtree
    • "Case-Sensitive Matching": Selected

  19. Click Next, Next again, then Save.

Manage SAML output from your IdP adapter

  1. On the "Manage Password Credential Validators" page, click Done.

  2. On the "IDP Adapter" tab, enter the following details.

    • "Password Credential Validator Instance": The name of the validator instance you created above (for example pfghdocscv). Click Update to finalize your selection.
    • All other fields can be left as the defaults, or modified to your requirements.

  3. Click Next, then Next again.

  4. On the "Adapter Attributes" tab, enter the following details.

    • "Unique User Key Attribute": username

    • Next to the username attribute, select "Pseudonym".

    Note

    This step is important. The adapter attribute is used to uniquely identify a user on your instance during SCIM provisioning.

  5. Click Next, then Next again.

  6. Review your settings on the summary page, then click Save.

  7. On the "IdP Adapters" tab, you should see the adapter you just created. Click Done.

  8. On the "Adapter Instance" tab, in the "Adapter Instance" dropdown, select the adapter you just created.

  9. Click Next.

  10. On the "Mapping Method" tab, select Use only the Adapter Contract Values in the SAML Assertion (other selections may work, but have not been confirmed).

  11. Click Next.

  12. On the "Attribute Contract Fulfillment" tab, map the SAML_SUBJECT to "Adapter" as the source and username as the value.

    Note

    This step is important. The normalized SAML_SUBJECT will need to match the normalized usernames of users provisioned by SCIM.

  13. Click Next, Next again, then Done.

  14. You should be back on the "Authentication Source Mapping" tab, and the "Adapter Instance Name" section should contain the adapter instance that you just created.

  15. Click Next and Done until you reach the "Credentials" tab.

  16. On the "Credentials" tab, click Configure Credentials, then click Manage Certificates.

  17. On the "Certificate Management" page, click Import, then upload an X509 certificate (for help, see the "Example of creating an X509 certificate" section).

  18. For the "Password," use the challenge password for the certificate.

  19. Click Next, then Save.

  20. On the "Certificate Management" tab, you should see the certificate you just imported. Click Done.

  21. On the "Digital Signature Settings" tab:

    • Select the certificate you just created for the "Signing Certificate."
    • You can leave the secondary certificate blank and the "Include the certificate in the signature" checkbox deselected.
    • The signing algorithm should be "RSA SHA256."

  22. Click Next, then Done, then Next.

  23. On the "Summary" tab, enable the toggle for "SSO Application Endpoint."

  24. Click Save. You should be taken back to the list of SP connections, where you should see your newly created SP connection.

Collect information for your SAML configuration

You will need some details from PingFederate to configure SAML on GitHub.

  1. On the "SP Connections" page, in the row for your new connection, click Select Action, then Export Metadata.
  2. On the "Metadata Signing" tab, in the row for your new connection, select the signing certificate you created above. To download the certificate, click Next, then click Export.
  3. On PingFederate, click System in the header, then Server, then Protocol Settings. Check that the SAML 2.0 ENTITY ID is defined. Make a note of this, as you will need it for the “Issuer” field in GitHub's SAML settings.
  4. Open the metadata file you downloaded, and have it ready for the next steps.

Configure GitHub Enterprise Server

  1. Sign in to your GitHub Enterprise Server instance as a user with access to the Management Console.

  2. Navigate to the "Authentication" section of the Management Console, then enable SAML. See "Configuring SAML single sign-on for your enterprise."

  3. Enter the following values from the metadata file you downloaded in the previous section.

    • For the "Single sign-on URL," use the location value of the <md: SingleSignOnService> field. This should be a URL ending /idp/SSO.saml2.
    • For the "Issuer," use the entityId value of the <md: EntityDescriptor> field (a URL).

  4. For the "Verification certificate," upload the X509 certificate file that you created earlier.

  5. Click Save settings.

2. Configure SCIM

In this section, you'll configure SCIM settings and attribute mapping on PingFederate.

  1. Configure SCIM settings
  2. Map LDAP fields to SCIM
  3. Finish configuration and test

Before starting this section, ensure you have followed steps 1 to 4 in "Configuring SCIM provisioning to manage users."

Configure SCIM settings

  1. Go back to the "SP Connections" page on PingFederate, and select the SP connection you created earlier.

  2. Click the "Connection Type" tab.

  3. Select Outbound Provisioning.

  4. Ensure Browser SSO Profiles is selected.

  5. Click Next until you reach the "Outbound Provisioning" tab, then click Configure Provisioning.

  6. On the "Target" tab, enter the following details.

    • "Base URL": https://HOSTNAME/api/v3/scim/v2/
    • "Access Token": The personal access token (classic) created for the built-in setup user

  7. Click Next.

  8. On the "Manage Channel" tab, click Create, then enter a unique channel name, such as pfghscim.

  9. Click Next.

  10. On the "Source" tab, choose the data store that you created earlier.

  11. Click Next.

  12. On the "Source Settings" tab, you can keep all default settings. Other settings are likely to work, but have not been confirmed.

  13. Click Next.

  14. On the "Source Location" tab, configure where in your LDAP server you would like provisioned users to come from. This will vary depending on your setup and needs. After configuring, click Next.

Map LDAP fields to SCIM

On the "Attribute Mapping" tab, you will need to map fields from your LDAP server to SCIM fields. See the following list for GitHub's supported SCIM fields and the values expected in each one.

  • Username: This will be normalized and used as the GitHub username for the provisioned user. See "Username considerations for external authentication." This must match the normalization of the subject sent with the SAML assertion that you configured with the SAML_SUBJECT property in PingFederate.
  • Email: A field containing the user's email address.
  • Display Name: A human-readable name for the user.
  • Formatted Name: The user's full name, including all middle names, titles, and suffixes, formatted for display.
  • First Name: The first name of the user.
  • Last Name: The last name of the user.
  • External ID: This identifier is generated by an IdP provider.
  • Roles: This field should contain a string that represents the user's intended role on GitHub. Valid roles are enterprise_owner and user.

When you have finished configuring these settings, click Next.

Finish configuration and test

  1. On the "Activation & Summary" tab, for the "Channel Status," select Active.
  2. On the "Manage Channels" tab, click Done.
  3. On the "Outbound Provisioning" tab, click Save. SCIM is now configured and enabled.
  4. Wait a few minutes for provisioning to run, then open a new private browser window and navigate to your instance at https://HOSTNAME/login.
  5. Click Sign in with SAML. You should be redirected to the PingFederate login page.
  6. You should be able to sign in with the credentials for a user in the LDAP server that has been provisioned to GitHub Enterprise Server.

PingFederate provisioning handles users and groups independently. Users must be assigned directly in order to be provisioned. Users who are in an assigned group but not directly assigned will not be provisioned.

When you have finished configuring SCIM, you may want to disable some SAML settings you enabled for the configuration process. See "Configuring SCIM provisioning to manage users."

Example of creating an X509 certificate

There are multiple ways to create an X509 certificate. Here is an example that may work for your requirements.

  1. In a terminal window, check that OpenSSL is installed by running openssl version. If it's not installed, install it.

  2. Generate the private key using the following command.

    Shell
    openssl req -nodes -sha256 -newkey rsa:2048 -keyout MyPrivateKey.key -out MyCertificateRequest.csr

    Enter the required information, and take note of the challenge password you create.

  3. To ensure the key was created, run the following command. A file named MyPrivateKey.key should be listed in the command output.

    Shell
    ls | grep MyPrivateKey.key

  4. Generate the certificate using the following command.

    Shell
    openssl x509 -req -days 365 -sha256 -in MyCertificateRequest.csr -signkey MyPrivateKey.key -out pfgh256.crt

  5. To ensure the certificate was created, run the following command. A file named pfgh256.crt should be listed in the command output.

    Shell
    ls | grep pfgh256.crt

  6. Export a PKCS #12 file using the following command. This is the file you should upload to PingFederate.

    Shell
    openssl pkcs12 -export -in pfgh256.crt -inkey MyPrivateKey.key -out pfgh256.p12

  7. To ensure the file was exported, run the following command. A file named pfgh256.p12 should be listed in the command output.

    Shell
    ls | grep pfgh256.p12