Getty Images/iStockphoto
How to set up external authentication in Rancher with GitHub
Local authentication is the default, but configuring Rancher to use external authentication services makes it easier to manage large, complex Kubernetes environments.
Like any other Kubernetes management platform, Rancher supports local authentication -- the ability to manage user access credentials and permissions within Rancher itself. But integrating Rancher environments with external authentication services such as GitHub can streamline user management.
External authentication simplifies user credential management, especially in large Kubernetes environments shared by multiple users. Find out why IT teams should use external authentication with Rancher, and then learn how to configure external authentication, using GitHub as an example.
What is Rancher?
Rancher is a Kubernetes management platform developed by Rancher Labs, which SUSE acquired in 2020. It includes a Kubernetes distribution as well as tools to help IT teams build and administer Kubernetes environments.
Local vs. external authentication in Rancher
Rancher supports two main approaches for authentication and authorization -- the process to log in users and grant permissions to control which actions they can take.
The first -- and default -- option is local authentication, which stores access credentials in Rancher. When a user attempts to log in, the local Kubernetes environment decides whether the login request is valid and which permissions the user should have.
The second approach is external authentication, in which an authentication proxy interfaces with an external authentication service to manage user logins and permissions. External authentication enables IT teams to manage user credentials through a third-party service rather than locally. As of August 2022, Rancher supports nearly a dozen options for external authentication, including GitHub, Microsoft Active Directory, Google OAuth and Okta.
Why use external authentication in Rancher
There are several reasons to set up external authentication for Rancher instead of relying on the default local authentication service:
- Centralized user management. External authentication eliminates the need to manage multiple accounts for the same users by reusing pre-configured accounts in an external service.
- User sharing across environments. With external authentication, IT teams that maintain multiple Rancher-based Kubernetes environments can share user accounts across all environments. Local authentication, in contrast, requires configuring separate users for each cluster.
- Ability to create user groups. Because Rancher local authentication currently doesn't support group creation or management at time of publication, external authentication is necessary to set up groups.
Given these benefits, external authentication is typically the best approach for Rancher; in fact, Rancher recommends using external authentication in most cases. Managing normal users with an external service simplifies administration -- though it's a good idea to set up a few local users as well to ensure users can log in if the external authentication service becomes unavailable.
How to use GitHub for Rancher authentication
Configuring external authentication is easy to do within the Rancher console. Although the process varies somewhat depending on the selected service, it typically involves five steps. Here, we'll use GitHub as an example.
Follow these steps to configure Rancher to use GitHub for external authentication:
- Sign in to Rancher as a local user with the administrator role.
- Navigate to the Security > Administration menu.
- Click the GitHub button to tell Rancher to authenticate using GitHub.
- In the Rancher console, enter your Client ID and Client Secret data from GitHub. To find this information, log in to GitHub and navigate to Settings > Developer Settings > OAuth Apps.
- Click Authenticate with GitHub to complete the configuration process.
Any user configured in the linked GitHub account can now also operate as a user in Rancher.
How to configure permissions for GitHub users in Rancher
In most cases, not every GitHub user should have unlimited access to an organization's Rancher environment. Admins can manage specific permissions granted to each GitHub user or group using the Site Access options in the Rancher console.
In the Rancher console, choose from the following options for GitHub user access permissions:
- Allow any GitHub user to log in to Rancher. Generally, this is not the best option due to security concerns.
- Allow specific GitHub users or groups to log in to Rancher based on cluster and project membership.
- Allow only authorized users and organizations to log in to Rancher.
Configuring Rancher to use a service like GitHub for external authentication makes it easier to manage user logins and permissions -- and if you already have an external authentication service configured, the setup process takes only a few minutes. But keep at least one local user account on hand as backup in case external authentication fails.
