How To Create A New GitHub Organization With An OAuth App Setup
Suppose a new developer has joined your team. How to make sure that the developer gets proper access to all the needed GitHub repositories. One way is to add the developer in each GitHub repository as a collaborator.
But that’s time consuming, repetitive, and does not supply any control mechanisms across the entire organization code repositories.
It would be great to simply add the developer to a group. A group that already has access to all the required GitHub repositories in that organization and follows the policies and procedures the organization designed.
Here comes GitHub Organizations. With GitHub Organizations it is possible to define a logical boundary to what are the repositories an organization owns, set up policies, manage employee and third-party application access, gain visibility and insights across the entire organization code base, among many other features. In this article, we will describe how to set up a GitHub Organization and explore its OAuth App functionality. Read on as we cover:
- What are GitHub Organizations?
- Steps to Create a New GitHub Organization
- What is an OAuth App?
- Creating a new OAuth App in a GitHub Organization
What are GitHub Organizations?
GitHub can be easily adopted by any developer to collaborate across multiple code repositories (e.g., open-source projects). However, only by setting up a GitHub Organization can we aggregate repositories and people that belong to the same organization (e.g., an enterprise or startup). Using GitHub Organizations enables advanced functionalities and allows administrators to set up governance mechanisms that allow people to collaborate and contribute to the same organization.
In a GitHub Organization a person can have the role of either Owner or Member. An Owner has full control over the organization and can do any action, such as access to organization level APIs (Application Programming Interfaces) and removing the entire organization codebase.
The Member role does not have access to the organization settings and is limited to accessing a specific repository, or to whatever default organization “base permissions” were set up by the organization Owners.
A few examples of actions that an organization Owner can do (depending on the plan chosen) are:
- Access to billing and plans
- Set private self-hosted runners for GitHub Actions usage
- Curate an allow list/deny list of GitHub Actions from the Marketplace
- Enable 2-factor authentication
- Store organization level secrets
- Check the audit logs from API (Application Programming Interfaces) calls within the GitHub Organization
- Set up 3rd party apps integration or OAuth app permissions
Steps to Create a New GitHub Organization
Start by visiting the GitHub portal and (if you haven’t already) create a new user account. To create a new GitHub Organization, select the “New organization” choice in the upper right corner dropdown menu (the plus icon near the profile picture).
In the next panel you will be asked to choose from the different GitHub organization plan options. For this guide, the free plan is sufficient, but take note of the features available in each plan.
Once the organization is created, you can set up your first GitHub team. A team corresponds to a logical group of users. In a GitHub organization the users can belong to multiple teams.
Select the choice “Teams” and fill in the team’s name (e.g., doet-admins). Keep the other options with their default values and press the “Create team” button.
In our recently created organization (i.e.: DevOps-Engineers-Team), the team will appear on the list.
By assigning users to teams, GitHub Organization administrators can easily manage permissions according to the individual profile and role within the organization.
When thinking about creating the organization “base permissions”, a good practice is to use only “read” permissions, following a policy of least privileges, meaning that one should only be granted the necessary minimum access level while also promoting transparency and cross-team collaboration within the organization.
What is an OAuth App?
A GitHub OAuth App enables 3rd party applications to integrate with your GitHub organization by supplying the ability to act as a regular GitHub authorized user. A common misconception is that GitHub Apps and OAuth Apps are the same but in fact there are significant differences between the two. A GitHub user can authorize an OAuth App to have the ability to act as themselves. This enables the OAuth App to impersonate the user and for example, access and read all notifications that were issued to them. At any point in time, the user can choose to revoke the permissions it gave to the OAuth App.
When an OAuth App is created, Client ID and Client Secret tokens are generated. These tokens follow the OAuth open standard and can be used by a 3rd party or custom application to authenticate in the GitHub Organization.
Creating a new OAuth App in a GitHub Organization
To create a new OAuth App, navigate to the Organization settings section found under Developer Settings. Press the New OAuth App button to start the process.
In this example we are going to create an OAuth App to allow the GitHub Organization users to log into a custom ArgoCD application deployment — a popular continuous delivery solution for Kubernetes — using it’s Dex server capability.
Start by filling in the application name (e.g., argocd-demo), the application homepage URL (e.g., https://argocd.witold-demo.com), a high-level description of the application and last, an Authorization callback URL (e.g., https://argocd.witold-demo.com/api/dex/callback).
The two most important fields in the configuration are the Homepage URL and Authorization callback URL. The first one is the host domain from where the authentication requests towards GitHub will originate, while the latter is the destination URL to where GitHub should redirect the user once the authentication process is finished.
Once the OAuth App is creating two important keys are generated: OAuth Client Id and OAuth Client Secret. These keys enable your applications (e.g., ArgoCD) to authenticate and interact with GitHub. Therefore, it is crucial that you store and handle them in an equivalent manner to any user passwords or application secrets.
A common best practice is to use a secret management service such as AWS Secret Manager, AWS SSM Parameter Store or Hashicorp Vault. In the case of AWS SSM Parameter Store, you could create two parameters named /secrets/core-infra/develop/argocd_oauth_client_id and /secrets/core-infra/develop/argocd_oauth_client_secret, to encrypt and store the two generated keys. This would make it possible for an application to programmatically retrieve and decrypt them on demand via an API by just referencing the parameter name. For example, the get-parameter method in AWS SSM Parameter Store API can be used both via the AWS UI console or programmatically with AWS CLI (Command Line Interface), AWS SDK (Software Development Kit), Terraform data blocks, etc.
Regardless of what secret management tool you choose the most important thing is that you have a method to store these sensitive keys. Your application doesn’t need to (or shouldn’t) hardcode and remember these values. The keys generated per OAuth App enable anyone who has them to authenticate against your GitHub Organization from anywhere in the world.
In the enterprise world, you can easily find GitHub Organizations that have several OAuth Apps. Therefore, it is crucial for the organization GitHub Owners, usually people in DevOps and SysOps roles, to show a strict process for their daily operations that restrict who has access to these secrets and how to store them. These practices make the developer experience easy for any GitHub user to rely on secret management services to retrieve the keys rather than sharing plain-texted values.
Conclusion
As we covered, combining GitHub Organization with OAuth Apps supplies a secure centralized solution for authenticating custom applications. This setup can be easily extended further with added functionalities such as enabling two factor authentication and fine-grained application permissions to retrieve OAuth keys from a secret management service.
Using OAuth Apps in a GitHub Organization enable platform engineering teams to integrate their multi-vendor tools, such as the ArgoCD application, and set up a fully programmatic GitOps experience with their application codebase, processes and infrastructure (e.g., AWS Elastic Kubernetes Service).
About the Author:
Witold Sławko, DevOps Engineer at Fortum
