Configure GitHub App

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. 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

危险

The GitHub App authentication provider only works with GitHub Organization accounts. It does not function with individual GitHub 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 for details.

Create GitHub App

1. Open your GitHub organization settings.

2. To the right of the organization, select Settings.

3. In the left sidebar, click Developer settings > GitHub Apps.

4. Click New Github App.

5. 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.

6. Select Create Github App.

Generate a Client Secret

Generate a client secret on the settings page for your app.

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

Generate a Private Key

Generate a private key on the settings page for your app.

1. Go to your GitHub App.
2. 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.

2. Select Auth Providers.

3. Select the GitHub App tile.

4. 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.

   备注

   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.

5. 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.

备注

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.