Using GitHub to Access Kubernetes

July 20, 2019


Marc Boorshtein

Your developers are all in GitHub.  You can control who’s in GitHub.  You can create teams and manage who’s in each team.  You can enforce multi-factor authentication too.  There are several reasons why you might want to use GitHub to authenticate to your cluster and manage access.  There’s one problem, GitHub doesn’t support a standard authentication protocol for SSO.  It has its own OAuth2 based protocol.  OpenUnison supports it now, including loading a user’s teams and organizations making it easy to integrate with your Kubernetes cluster.  We’ll walk through the process in this blog post.

User Flow

When the user tries to access the Orchestra Login Portal they’re redirected to GitHub and asked to authenticate.  Once they’re authenticated, they’ll be asked to authorize access to your application and then send the user back to the login portal where the user’s information is pulled from GitHub.  Next, OpenUnison will sync the user’s data to an object in Kubernetes just-in-time and creates a session object in Kubernetes as well.  Once the authentication process is complete the user can either access the dashboard or use the cli via via the command generated for you by OpenUnison.  When the user is done, they can logout and invalidate both their CLI and dashboard sessions.  This short video (about a minute and half) shows the entire process:

Setup in GitHub

Before deploying the Orchestra Login Portal, we’ll need to do some work in GitHub.  In your organization go to Settings and click on OAuth Apps (on the left hand side bar) and click New OAuth App.  The first three text boxes are for you to fill out.  The final box, Authorization Callback URL, is based on how you plan on deploying the Orchestra Login Portal.  It will be /auth/github on the Orchestra host.  For instance if you plan to run Orchestra at then the value for this text box will be  Once you create the new application, you’ll have the option of uploading a logo and will be presented with a secret and client id.  Save these for the next steps.

Deploy the Orchestra Login Portal

The Orchestra Login Portal deploys using a Kubernetes Job to create the appropriate Deployment objects, the operator and creates a Custom Resource that is used by the operator to deploy OpenUnison.  The operator will also create a certificate for the dashboard for you and will keep it updated so you’ll never have to worry about it expiring.  Follow the instructions from the GitHub README to deploy the login portal, using the client id and secret.  It’s HIGHLY recommended that you supply at least your own organization for GITHUB_TEAMS to limit access.  GitHub has no way to limit who can authenticate to an application, it MUST be managed by the application.  The login portal limits who can authenticate based on both teams and organizations.

Manage Access with RBAC

You don’t really want to give everyone cluster administrator access to your cluster, do you?  Of course not.  You can use GitHub teams and organizations directly in your RBAC policies.  In GitHub you can create teams via your GitHub organization’s page.  Then simply add that team to a ClusterRoleBinding or a RoleBinding.  For instance to allow all members of the team Owners in the Tremolo Security organization use the below ClusterRoleBinding:

-- CODE language-yaml --
kind: ClusterRoleBinding
 name: github-cluster-admins
- kind: Group
 name: TremoloSecurity/Owners
 kind: ClusterRole
 name: cluster-admin

Once this binding is applied, all members of the team will have cluster-admin access.

Pulling It All Together
You’re now able to access your cluster with your GitHub account.  To see everything in action, check out this 7 minute video that shows the entire process, start-to-finish!