How to set up external authentication in Rancher with GitHub
Like any other Kubernetes management platform, Rancher supports local authentication – the ability to manage user credentials and permissions within Rancher itself. But integrating rancher environments with external authentication services like GitHub can streamline user management.
External authentication simplifies the management of user credentials, especially in large Kubernetes environments shared by multiple users. Find out why IT teams should use external authentication with Rancher, then use GitHub as an example to learn how to configure external authentication.
What is rancher?
Rancher is a Kubernetes management platform developed by Rancher Labs, which SUSE acquired in 2020. It includes a Kubernetes distribution and tools to help IT teams create and manage Kubernetes environments.
Local vs. External Authentication in Rancher
Rancher supports two main approaches to authentication and authorization – the process of signing in users and granting permissions to control what actions they can perform.
The first – and default – option is local authentication, which stores credentials in Rancher. When a user tries to log in, the local Kubernetes environment decides whether the login request is valid and what 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 allows IT teams to manage user credentials through a third-party service rather than locally. As of August 2022, Rancher supports nearly a dozen external authentication options, 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 ranchers 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 preconfigured accounts in an external service.
- User sharing across environments. With external authentication, IT teams running multiple Rancher-based Kubernetes environments can share user accounts across environments. In contrast, local authentication requires separate users to be configured for each cluster.
- Ability to create user groups. Because Rancher Local Authentication does not currently support group creation or management at the time of release, external authentication is required to set up groups.
Given these benefits, external authentication is typically the best approach for ranchers. In fact, Rancher recommends using external authentication in most cases. Managing regular users with an external service simplifies administration—although it’s a good idea to also set up a few local users to ensure users can sign in when the external authentication service isn’t available.
How to use GitHub for rancher authentication
Configuring external authentication is easy to do in the Rancher console. Although the process will vary somewhat depending on the service you choose, it usually involves five steps. Here we use GitHub as an example.
Follow these steps to configure Rancher to use GitHub for external authentication:
- Log in to Rancher as a local user with the Administrator role.
- Navigate to the Security > Management menu.
- press the GitHub Button to instruct ranchers to authenticate via GitHub.
- In the Rancher Console, enter your Client ID and GitHub Client Secrets. To find this information, log in to GitHub and navigate to Settings > Developer Settings > OAuth Apps.
- click Authenticate to GitHub to complete the configuration process.
Any user configured in the linked GitHub account can now also work as a user in Rancher.
How to configure permissions for GitHub users in Rancher
In most cases, not every GitHub user should have full access to an organization’s rancher environment. Administrators can use the site access options in the Rancher console to manage specific permissions granted to each GitHub user or group.
In the Rancher Console, choose from the following GitHub user access permissions options:
- Allow any GitHub user to login to Rancher. In general, 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 into Rancher.
Configuring Rancher to use a service like GitHub for external authentication makes it easy to manage user logins and permissions—and if you’ve already configured an external authentication service, the setup process only takes a few minutes. However, keep at least one local user account as a backup in case external authentication fails.