---
title: Configure GitHub App
---

<head> 
  <link rel="canonical" href="https://ranchermanager.docs.rancher.com/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-github-app"/>
</head>

In environments using GitHub, you can configure the new GitHub App authentication provider in Rancher, which allows users to authenticate against a GitHub Organization account using a dedicated [GitHub App](https://docs.github.com/en/apps/overview). This new provider runs alongside the existing standard GitHub authentication provider, offering increased security and better management of permissions based on GitHub Organization teams.

## Prerequisites

:::warning

The GitHub App authentication provider only works with [GitHub Organization accounts](https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#organization-accounts). It does not function with individual [GitHub User accounts](https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#user-accounts).

:::

Before configuring the provider in Rancher, you must first create a GitHub App for your organization, generate a client secret for your GitHub App and generate a private key for your GitHub App. Refer to [Registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) for details.

### Create GitHub App

1. Open your [GitHub organization settings](https://github.com/settings/organizations).
1. To the right of the organization, select **Settings**.
1. In the left sidebar, click **Developer settings** > **GitHub Apps**.
1. Click **New Github App**.
1. Fill in the GitHub App configuration form with these values:

    - **GitHub App name**: Anything you like, e.g. `My Rancher`.
    - **Application description**: Optional, can be left blank.
    - **Homepage URL**: `https://localhost:8443`.
    - **Callback URL**: `https://localhost:8443/verify-auth`.

1. Select **Create Github App**.

### Generate a Client Secret

Generate a [client secret](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api#using-basic-authentication) on the settings page for your app.

1. Go to your GitHub App.
1. Next to **Client Secrets**, select **Generate a new client secret**.

### Generate a Private Key

Generate a [private key](https://docs.github.com/en/enterprise-server/apps/creating-github-apps/authenticating-with-a-github-app/managing-private-keys-for-github-apps#generating-private-keys) on the settings page for your app.

1. Go to your GitHub App.
1. Next to **Private Keys**, click **Generate a private key**.

## GitHub App Auth Provider Configuration

To set up the GitHub App Auth Provider in Rancher, follow these steps:

1. Navigate to the **Users & Authentication** section in the Rancher UI.
1. Select **Auth Providers**.
1. Select the **GitHub App** tile.
1. Gather and enter the details of your GitHub App into the configuration form fields.

    | Field Name | Description |
    | ---------- | ----------- |
    | **Client ID** (Required) | The client ID of your GitHub App. |
    | **Client Secret** (Required) | The client secret of your GitHub App. |
    | **GitHub App ID** (Required) | The numeric ID associated with your GitHub App. |
    | **Installation ID** (Optional) | If you want to restrict authentication to a single installation of the App, provide its specific numeric Installation ID. |
    | **Private Key** (Required) | The contents of the Private Key file (in PEM format) generated by GitHub for your App. |

  :::note

  A GitHub App can be installed across multiple Organizations, and each installation has a unique Installation ID. If you want to restrict authentication to a single App installation and GitHub Organization, provide the Installation ID during configuration. If you do not provide an Installation ID, the user's permissions are aggregated across all installations.

  :::

1. Select **Enable**. Rancher attempts to validate the credentials and, upon success, activates the GitHub App provider.

After it is enabled, users logging in via the GitHub App provider are automatically identified and you can leverage your GitHub Organization's teams and users to configure Role-Based Access Control (RBAC) and to assign permissions to projects and clusters.

:::note

Ensure that the users and teams you intend to use for authorization exist within the GitHub organization managed by the App.

:::

- **Users**: Individual GitHub users who are members of the GitHub Organization where the App is installed can log in.
- **Groups**: GitHub Organization teams are mapped to Rancher Groups, allowing you to assign entire teams permissions within Rancher projects and clusters.
