Github

Overview

Identity Intelligence can connect to Github Enterprise tenants and provide insights into user identities and activity on that platform.

This document will walk you through the process of setting up access from Identity Intelligence to Github Enterprise.

Requirements

The following requirements are necessary for the Github integration -

1. Github Enterprise subscription

2. A Github Enterprise admin account capable of creating Personal Access Tokens (classic)

3. SSO from your Identity Provider to each Github org is set to "Enforced" (mandatory) and not "Configured" (optional), otherwise Identity Intelligence cannot retrieve the emails for users in the "configured" org and they will not merge with their own record in the "enforced" org

Github API Permission Structure

Enterprise vs. Org

Identity Intelligence has chosen to connect to Github environments at the Enterprise level rather than per Organization. This allows for the use of one API token for an entire customer environment, instead of an API token being required for each Org.

Therefore, an Enterprise Admin account or a Enterprise service account is required.

Excluding Specific Github Orgs

You may want to collect identity data for only certain orgs under your Github Enterprise tenant. To do that, you will need to follow this approach:

1. Create an Identity Intelligence service account at the Enterprise level

2. Make it a member of the orgs where you want Identity Intelligence to ingest data

3. Do NOT make the account a member or give it access to orgs where you do not want Identity Intelligence to collect data

4. Create PAT as described below

5. Authorize SSO for the PAT to the desired orgs

Fine-grained vs Classic PAT

Identity Intelligence leverages the Audit Log API methods to obtain necessary information. At this time, this portion of the API is only available when using PAT (classic) tokens. (Github article)

These endpoints only support authentication using a personal access token (classic). For more information, see "Managing your personal access tokens."

Compatible Checks

Currently, 11 security posture and threat detection Checks are compatible with the Github integration. Identity Intelligence is continuously adding to this list, based on customer requests and also new and emerging identity-based threats for Github.

Github Configuration Steps

1. Login to Github with an Enterprise admin account. If you navigate to github.com/settings/enterprises, it should look something like the following:

   
2. Enable displaying IP addresses in the Github Audit Log for your enterprise tenant as described in this article

3. Follow the steps for creating a classic PAT as outlined in this Github article - https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic

4. In step 8 of Github's PAT Creation docs, grant the following scopes to the token: read:audit_log read:enterprise read:org repo:invite user:email

5. Click Generate Token and copy it to a secure location for use in upcoming set up steps

6. Important - Ensure that the PAT has SSO authorization to all of the Github orgs under your Enterprise tenant, if SSO is in use.

   

   1. If at any point, you update the scopes associated with the token, be sure to reauthorize the token for the SSO enabled orgs within the enterprise tenant.

   
7. Note the slug for your Enterprise Github tenant. This can be found under your entprise profile tab.

   

Identity Intelligence Configuration Steps

Sign in to your Identity Intelligence tenant and perform the following steps:

1. From the Integrations page, click Add Integration and select Github

2. Enter a display name for the integration, such as Github customername.

3. Enter the value of your Github Enterprise slug, obtained in Step 7 above

4. Enter the Github PAT value and click Connect to test the configuration connection

   
5. Once the configuration connection is successful, go back to the main Integrations page, click the 3-dot menu on the Github integration and select Collect Now. Collection may take some time, depending on the size of the environment.

   

Updating the PAT

If the PAT is due to expire or needs to be rotated, follow these steps:

1. After creating the new PAT (classic) with the necessary scopes, login to your Identity Intelligence tenant

2. In the Identity Intelligence console, go to the Integrations page, click the 3-dot menu for the Github integration and select Edit Settings

3. Click Reset Credentials. Then enter the new PAT value and click Save.

   
4. Go back to the Integrations page, click the 3-dot menu for the Github Integration and select Test Connectivity to ensure a successful connection