GitHub

Overview

The GitHub Enterprise integration enables Veza to authenticate with organizations and discover users, repositories, teams, and other entities, along with searchable metadata (attributes) for these entities. Veza will also map external corporate identities (such as Azure AD Users) to granular GitHub Roles and Permissions.

After configuring the integration you can use Workflows and Search to review access to public and private GitHub repositories within your organization. Built-in Saved Queries for GitHub are available for customization and use in Reports.

This integration supports self-managed and cloud-hosted GitHub environments, including:

• GitHub Cloud (e.g. Organizations on github.com)

• GitHub Enterprise Cloud

• GitHub Enterprise Server

For self-managed GitHub deployments, you should use an Insight Point to enable the connection, or allow traffic from Veza's cloud IPs.

Configuration

To authenticate with GitHub, you will need to create a Github App granting Veza access your organization to gather the necessary information. See the instructions for:

• creating a read-only GitHub App for Veza, and install it into the GitHub organizations to discover.

• adding the integration to Veza with the GitHub App's credentials.

To integrate with several organizations with a single GitHub App and Veza integration configuration, you can:

1. Create the GitHub app.

2. Set it to Public.

3. Install the app into each GitHub organizations to discover.

For more details, see the GitHub documentation Creating GitHub Apps and Making a GitHub App Public or Private.

GitHub setup instructions

To create and register the application within an organization you administer, open GitHub Settings > Organizations. Click Settings next to the name of the organization containing the members, repositories, and permissions to extract.

If you are not an org admin, you can create the app under your personal Developer Settings > GitHub Apps > Add New. Pick Any Account when choosing where to install the app. You will need to Request installation to any organization you are a member of, which an administrator must approve.

1. On the Organization's settings page, click Developer Settings > GitHub Apps > Add New

2. Fill out the following fields:

   • GitHub App name must be unique (e.g. YourOrg-Veza-Integration-01)

   • Homepage URL is not used but required by GitHub. Enter an address such as the URL of your Veza instance (e.g. https://yourorg.vezacloud.com)

   • All other fields are optional

3. Assign the required permissions to the application. Add the following Read-Only permissions:

   • Repository permissions - Administration

   • Repository permissions - Metadata

   • Repository permissions - Repository security advisories

   • Organization permissions - Custom repository roles

     • Support for Custom Repository Roles is only available for Github Enterprise Cloud environments.

   • Organization permissions - Members

   • Organization permissions - Administration

   • Organization permissions - Personal Access Tokens

4. Enter Only on this account for Where can this app be installed?, or enable the app for other accounts by making it Public.

5. Click Create GitHub App to open the app settings page

   • Note the “App ID” towards the top of the screen. Click Generate a private key to download the base64-encoded .pem key file.

6. Finally, install the App into the Organization(s) you want to discover:

   1. Open the app settings page (Settings > Developer settings > GitHub Apps > your-application)

   2. Click Install next to the organization name

   3. Unless you want to exclude specific resources, pick All Repositories

   4. Click Install and approve the permissions

Discovering user email addresses

Github only publishes user emails that belong to a verified or approved domain for the tenant organization. This intentional behavior allows personal accounts to serve as individual developer portfolios that are portable across companies. To filter users by email or configure identity mappings, you will need to ensure that users in your organization have addresses that match a verified/approved domain.

An organization owner must configure verified/approved domains for GitHub. If such a domain already exists, you should request that all users add an email address belonging to the domain. For more information see the Verifying or Approving a Domain for your Organization

Veza setup instructions

To add a GitHub integration, use the navigation bar to open the Integrations page. Click Add New Integration and enter the required information using the App Key and ID from the earlier steps.

• The Enterprise cloud slug is optional. When provided, the ID is used to correlate external identities with GitHub users.

• Leave Server URL empty when connecting to GitHub cloud.

Veza uses the app credentials for the initial connection. Future requests use an access token, which the connector will generate at runtime.

Notes and supported entities

After enabling the integration and connecting to GitHub, Veza will discover entities and attributes for:

• GitHub Organizations

• GitHub Personal Accounts

• GitHub Personal Access Tokens

• GitHub Teams

• GitHub Roles

• GitHub Apps

• GitHub Repositories

Cross-Service Connections: Veza automatically detects relationships between Okta and Azure AD identities and GitHub user accounts. If your organization implements Single-Sign On (SSO) for another Identity Provider (IdP), you can add Custom Identity Mappings to correlate GitHub Personal Accounts with identities from any integrated IdP.

Use the Access Intelligence Overview to review all entities Veza has discovered.

Veza uses some common properties for all GitHub entities:

GitHub Organization

Organizations are shared accounts where teams of users can work together on public and private projects.

GitHub Personal Account

A personal account (GitHub User) can be a member of the organization or an "outside collaborator" (who has some permissions on repositories, but is not an org member).

You can explain effective permissions to show the grouped role permissions assigned to the user.

GitHub Personal Access Token

A Personal Access Token (PAT) is a credential used to authenticate GitHub API requests. It can be either a classic token or a fine-grained token with specific permissions.

Token can be connected to a Github Personal Access Token Permission node representing the effective permissions on GitHub resources.

GitHub Team

Teams represent groups of users. Assigning GitHub Personal Accounts to teams grants the users permissions on the team's repositories.

Possible roles on repositories are: admin, maintain, push, triage, pull.

GitHub App

Apps on GitHub (Non-human service accounts) enable automation, workflows, and integrations for a user or organization. GitHub App permissions are not assigned with roles, but are individually granted, for example "administration":"read","emails":"read","metadata":"read","members":"read","organization_administration":"read".

GitHub Repository

GitHub Role

These roles grant a set of repository permissions to teams or individual users. Roles can also apply to an organization or team.