Skip to main content

GitHub REST

Overview​

GitHub is a cloud-based platform for code hosting and version control using Git. Its REST API enables programmatic interaction with GitHub's features, allowing for custom tool development and automation.

Below you can find the Aembit configuration required to work with the GitHub service as a Server Workload using the GitHub REST API.

Aembit supports multiple authentication/authorization methods for GitHub. This page describes scenarios where the Credential Provider is configured for GitHub via:

Prerequisites

Before proceeding with the configuration, ensure you have the following:

  • A GitHub account
  • A personal access token (API Key Method)
  • A GitHub app (OAuth 2.0 Authorization Code Method)

If you have not created a token or an app before, you can follow the steps outlined in the subsequent sections. For detailed information on authenticating with different flows, please refer to the official GitHub documentation.

OAuth 2.0 Authorization Code​

Server Workload Configuration​

  1. Create a new Server Workload.
  • Name - Choose a user-friendly name.
  1. Configure the service endpoint:
  • Host - api.github.com
  • Application Protocol - HTTP
  • Port - 443 with TLS
  • Forward to Port - 443 with TLS
  • Authentication method - HTTP Authentication
  • Authentication scheme - Bearer

Credential Provider Configuration​

  1. Sign in to your GitHub account.

  2. In the upper-right corner of any page, click your profile photo, then click Settings.

  3. Navigate to Developer settings in the left-hand menu, and choose Github Apps.

  4. On the right side, click on the New GitHub App button.

Create New Github App

  1. Provide a name for your app, and optionally type a description of your app.

  2. For the Homepage URL, enter the full URL of your Aembit tenant (e.g., https://xyz.aembit.io,).

  3. Switch to the Aembit UI to create a new Credential Provider, selecting the OAuth 2.0 Authorization Code credential type. After setting up the Credential Provider, copy the auto-generated Callback URL.

  4. Return to GitHub and under Callback URL, paste the copied URL.

  5. Check the Request user authorization box and uncheck the webhook.

  6. Under the Permissions section, expand the drop-down menus and select the permissions (scopes) for your application depending on your needs.

  7. Choose the installation area for this app, then click on Create Github App.

  8. Copy the Client ID, then click Generate a new client secret, and copy the Client Secret. Securely store the token for later use in the configuration on the tenant.

GitHub App Copy Client ID and Client Secret

  1. Edit the existing Credential Provider created in the previous steps.
  • Name - Choose a user-friendly name.
  • Credential Type - OAuth 2.0 Authorization Code
  • Callback URL (Read-Only) - An auto-generated Callback URL from Aembit Admin.
  • Client Id - Provide the Client ID copied from GitHub.
  • Client Secret - Provide the Secret copied from GitHub.
  • Scopes - You can leave this field empty by entering a single whitespace, as GitHub will default to your selected scopes for the app.
  • OAuth URL - https://github.com
  • Authorization URL - https://github.com/login/oauth/authorize
  • Token URL - https://github.com/login/oauth/access_token
  • PKCE Required - Off (PKCE is not supported by Github, so leave this field unchecked).
  • Lifetime - 6 Months

  1. Click Save to save your changes on the Credential Provider.

  2. In the Aembit UI, click the Authorize button. You are be directed to a page where you can review the access request. Click Authorize to complete the OAuth 2.0 Authorization Code flow. You should see a success page and be redirected to Aembit automatically. You can also verify your flow is complete by checking the State value in the Credential Provider. After completion, it should be in a Ready state.

Credential Provider - Ready State

warning

Once the set lifetime ends, the retrieved credential will expire and no longer be active. Aembit will notify you before this happens. Please ensure you reauthorize your credential before it expires.

API Key​

Server Workload Configuration​

  1. Create a new Server Workload.
  • Name - Choose a user-friendly name.
  1. Configure the service endpoint:
  • Host - api.github.com
  • Application Protocol - HTTP
  • Port - 443 with TLS
  • Forward to Port - 443 with TLS
  • Authentication method - HTTP Authentication
  • Authentication scheme - Bearer

Credential Provider Configuration​

  1. Sign in to your GitHub account.

  2. In the upper-right corner of any page, click your profile photo, then click Settings.

  3. Navigate to Developer settings in the left-hand menu.

  4. Under Personal access tokens, choose Fine-grained tokens.

  5. On the right side, click on the Generate new token button.

Generate new fine-grained token

  1. Provide a name, expiration date, and description for your token. Choose the resource owner and repository access type.

  2. Under the Permissions section, expand the drop-down menu and select the permissions (scopes) for your application depending on your needs.

  3. After making all of your selections, click on Generate Token.

  4. Click Copy to clipboard and securely store the token for later use in the configuration on the tenant.

Copy fine-grained token

note

The following configuration steps also work with classic personal access tokens; however, fine-grained tokens are recommended as they offer more granular permissions and improved security.

  1. Create a new Credential Provider.
  • Name - Choose a user-friendly name.
  • Credential Type - API Key
  • API Key - Paste the token copied from GitHub.

Client Workload Configuration​

Aembit now handles the credentials required to access the Server Workload, eliminating the need for you to manage them directly. You can safely remove any previously used credentials from the Client Workload.

If you access the Server Workload through an SDK or library, it is possible that the SDK/library may still require credentials to be present for initialization purposes. In this scenario, you can provide placeholder credentials. Aembit will overwrite these placeholder credentials with the appropriate ones during the access process.

Access Policy​

  • Create an Access Policy for a Client Workload to access the GitHub REST API Server Workload. Assign the newly created Credential Provider to this Access Policy.

Required Features​

  • You will need to configure the TLS Decrypt feature to work with the GitHub REST API Server Workload.