16.9 Understanding and Configuring REST GitHub Templates

Identity Governance provides the following templates for GitHub:

  • REST GitHub Account

  • REST GitHub Organization Permission

  • REST GitHub Repository Permission

  • REST GitHub Team Permission

  • REST GitHub Fulfillment

For additional information about configuring REST GitHub and Generic templates, see the following sections:

16.9.1 Required Minimum Rights for Integration with GitHub

To access all GitHub endpoints, you must use the credentials of a GitHub Enterprise Administrator, also known as the Site Administrator, for the authentication types.

16.9.2 Understanding REST GitHub Authentication Methods

NOTE:Identity Governance supports Cloud Bridge only in Identity Governance as a Service deployments.

If you use Cloud Bridge to collect data from your on-premises data centers, you must specify ordinals for the respective authentication method in the Cloud Bridge user interface (http://localhost (CBA IP address or DNS name):8080).

The GitHub account and permission collector supports two authentication types: Basic Auth and Access Token. The collector collects all organizations.

NOTE:You must have installed Cloud Bridge 1.10 to collect with the Rest connector 1.0.2.0000 version.

Log in to the Cloud Bridge URL, then specify the ordinal when adding credentials.

Ordinal

Authentication Type

Credential Set

3

Basic Auth

  • User Name

  • Password

4

Access Token

  • Access Token Header

  • Access Token

IMPORTANT:For the access token, the user provides the token to connect to the target application, whereas, for the bearer token, the connector generates the token. When the access token expires, replace it with a new access token.

16.9.3 About REST GitHub Collectors

NOTE:Identity Governance currently supports GitHub Enterprise on-premises edition, version 3.8.3.

Like the other Identity Governance collectors, the REST GitHub collectors map accounts and permissions to identities by association or other attributes. To successfully map accounts and permissions to identities, identities must be collected using the identity source that is configured in the GIT server. The REST GitHub permission collector collects all organizations, teams, repositories, the permission to permission association, and also the holder association. The collector has a batch size limit of 100 records.

The REST GitHub collector template includes mandatory attribute mappings suitable for the target application. However, you can configure other attributes and then edit the transform script to build the required payload. For example, for GitHub accounts, if you want to map ‘email’ for the Account-User Mapping attribute, you need to map Account-User Mapping with user and write the script as follows to parse the email from the user JSON:

var user = JSON.parse(inputValue) outputValue = user['email'];

Apart from the mapped attributes, you can add other attributes for organization by parsing the values from the organization JSON. For teams, you can parse the values from the teams JSON and for repository from the repository JSON.

If you use Cloud Bridge to collect data from your on-premises data centers, you must specify ordinals for the respective authentication method in the Cloud Bridge user interface (http://localhost (CBA IP address or DNS name):8080).

NOTE:You must be using Identity Governance 4.2 or Cloud Bridge 1.10 to collect using the latest version of REST GibHub collector.

16.9.4 About REST GitHub Fulfillment

Identity Governance uses the REST GitHub fulfiller to add or remove members from an organization, or a team, or add or remove a collaborator from a repository. When a user is added to an organization or a team the default role assigned is of a “member”, and for a repository, it is “read”. However, members can log in to the GitHub application and change their roles as needed.

Users can get access to a repository directly as collaborators, or when they are members of an organization or a team. As members, they automatically inherit the permission to access the organization and team repositories. So, when you want to remove a collaborator from a repository, or a member from a team, ensure that the repository permission is not inherited from an organization or a team. For the fulfillment verification to be successful, you must remove the member from the parent organization or team so the member loses the child permission, which means the repository permission.

NOTE:The term “collaborator” is specific to GitHub and it refers to a user who is given access to a repository directly. For more information, see the GitHub Docs.

The REST GitHub fulfiller supports the following change requests:

  • ADD PERMISSION TO USER

  • REMOVE PERMISSION ASSIGNMENT

  • REMOVE PERMISSION FROM ACCOUNT

For the fulfillment to process successfully, you must add these mandatory attributes to the Fulfillment Context attribute area. The following table provides the list of attributes.

Fulfillment Context Attributes

Attributes

Account

  • Account ID from Source

  • Account Disabled

  • Account Aliases

Permission

  • Permission ID from Source

  • Permission Type

  • Permission Name