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. Learn more in About SCIM in the GitHub documentation. |
Steps
-
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.
-
Create a new SP connection or select an existing SP connection from the SP Connections page.
-
On the Connection Template tab, select Use a template for this connection.
-
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.
-
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
-
-
On the Connection Type tab, ensure that both the Outbound Provisioning and Browser SSO Profiles check boxes are selected.
-
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.
-
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:
-
-
Click Configure Browser SSO.
-
On the Assertion Creation tab, click Next.
-
On the Protocol Settings tab, click Configure Protocol Settings.
-
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
-
Click Update and Done, then click Done on the Protocol Settings tab.
-
-
On the Credentials tab, click Configure Credentials, then go to the Digital Signature Settings tab, select the signing certificate, and click Done, then Next.
-
On the Outbound Provisioning tab, click Configure Provisioning.
-
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.
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.
-
Click Next.
-
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:
-
Credentials will be verified when the channel and SP connection is set to Active and provisioning is initiated.
-
Go to the Manage Channels tab and select the name of a channel to edit it.
-
On the Attribute Mapping tab, edit the Roles field by clicking Edit in the Action column.
-
After the Attribute Mapping window for the Roles field opens, map the Roles field to an LDAP attribute containing the value for the GitHub enterprise role that the user will have when they are provisioned.
The LDAP attribute must contain one of the following string values:
-
enterprise_owner
-
billing_manager
-
user
-
guest_collaborator
-
-
Click Done.
-
After you finish mapping attributes, click Next.
-
In the Channel Status section of the Activation and Summary tab, click Active.
-
Click Done.
-
-
Link users authenticating through SAML to their provisioned SCIM identities in the GitHub enterprise.
The SAML
NameID
and SCIMuserName
values must match for each user. Otherwise, a PingFederate user attempting to access their EMU account through SAML authentication might get a404
error and an error message such as:Enterprise Managed Users must be provisioned via SCIM
To make sure that these values match in PingFederate:
-
On the Attribute Contract Fulfillment tab, make sure that the Value of the
SAML_SUBJECT
contract attribute issAMAccountName
if you are using Active Directory as the LDAP datastore, orusername
if you are using another LDAP datastore like PingDirectory.To find the Attribute Contract Fulfillment tab:
-
On the Browser SSO tab, click Configure Browser SSO.
-
Go to the Assertion Creation tab and click Configure Assertion Creation.
-
Go to the Authentication Source Mapping tab, click Map New Adapter Instance, and then go to the Attribute Contract Fulfillment tab.
-
-
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 besAMAccountName
if you are using Active Directory, orusername
if you are using PingDirectory.
-
-
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:
-
Go to System → Server → Protocol Settings and select the Outbound Provisioning tab.
-
Enter a new Synchronization Frequency value, then click Save.
-