GitHub OAuth
Learn how to set up OAuth with GitHub
The GitHub OAuth integration allows your users to authenticate using their GitHub credentials.
The configuration process involves creating an OAuth application in GitHub and configuring the client credentials in the WorkOS Dashboard.
WorkOS provides a default GitHub Client ID and Client Secret combination, which allows you to quickly enable and test GitHub OAuth. Use the WorkOS API to initiate SSO, setting the provider parameter to GitHubOAuth, and WorkOS will automatically use the default credentials until you add your own GitHub Client ID and Client Secret to the configuration in the WorkOS Dashboard.
The default credentials are only intended for testing and therefore only available in the Staging environment. For your production environment, please follow the steps below to create and specify your own GitHub Client ID and Client Secret.
Please note that when you are using WorkOS default credentials, GitHub’s authentication flow will display WorkOS’ name, logo, and other information to users. Once you register your own application and use its GitHub Client ID and Client Secret for the OAuth flow, you will have the opportunity to customize the app, including its name, logo, contact email, etc.
When setting up GitHub OAuth, WorkOS provides one key piece of information that needs to be configured in your GitHub OAuth application:
- Redirect URI: The endpoint where GitHub will send authentication responses after successful login
The Redirect URI is available in the WorkOS Dashboard. In the left navigation menu, select the Authentication tab and the OAuth providers sub-tab. Locate the GitHub section.
Click Manage. The GitHub OAuth configuration dialog will open. Locate the Redirect URI.
The Redirect URI serves as the destination for authentication responses and must be configured in your GitHub OAuth application as the authorization callback URL.
You will need to obtain two pieces of information from a GitHub OAuth application:
- GitHub Client ID: Application identifier from GitHub
- GitHub Client Secret: Authentication secret for the application
The following sections will guide you through creating an OAuth application in your GitHub account and generating these credentials.
Sign in to GitHub and navigate to Developer settings. Select OAuth Apps. Create a new OAuth app.
You can also register a new application under a GitHub Organization, which may be more appropriate if it is maintained by a team of developers. You can also transfer ownership of your GitHub OAuth application to a GitHub organization later.
Fill out the OAuth application form. For the Authorization callback URL input, enter the Redirect URI from the WorkOS Dashboard.
Click Register application.
You’ll be given a Client ID. Note this value as you’ll need it for the WorkOS configuration.
Click Generate a new client secret to generate a new GitHub Client Secret. Note that this value is only temporarily available, so make sure to save it before proceeding.
Now that you have the GitHub Client ID and GitHub Client Secret from the previous step return to the WorkOS Dashboard.
In the GitHub OAuth configuration dialog, select Your app’s credentials. Paste the credentials from GitHub into their respective fields in the WorkOS Dashboard.
Click Save to complete the configuration.
You’re now able to authenticate users with GitHub OAuth. You will use the provider query parameter in the Get Authorization URL API endpoint to support global GitHub OAuth for any domain. The provider query parameter should be set to GitHubOAuth.
How is the WorkOS GitHub OAuth integration different from implementing regular GitHub OAuth flow?
It’s the same GitHub OAuth flow as you could build yourself, but it’s encapsulated within WorkOS SSO. This means you don’t need to build it yourself. In addition to GitHub OAuth, you can use WorkOS SSO to support other identity providers, all with a single integration.
What is the provider query parameter and how is it used in the GitHub OAuth integration?
You can use the provider query parameter in the Get Authorization URL API endpoint to support global GitHub OAuth for any domain. The provider query parameter should be set to GitHubOAuth.