WorkOS Docs Homepage
DashboardSign In

GitHub OAuth

Learn how to set up OAuth with GitHub.

To configure your global GitHub OAuth setup, you’ll need three pieces of information: a Redirect URI, a GitHub Client ID, and a GitHub Client Secret.

WorkOS provides the Redirect URI, an allowlisted callback URL. It indicates the location to return an authorized user to after both an authorization code is granted, and the authentication process is complete.

Open your WorkOS Dashboard and browse to the Authentication section on the left hand navigation bar. Scroll down to the GitHub OAuth section and click Edit.

A screenshot showing the GitHub OAuth section in the WorkOS Dashboard.

In the modal, you'll see the Redirect URI as well as the fields you'll populate later with information from GitHub. This URI will be used as part of the registration process later in the GitHub developer settings page.

A screenshot showing the GitHub OAuth configuration modal in the WorkOS Dashboard.

WorkOS provides a default GitHub Client ID/GitHub Client Secret combination, which allows you to quickly enable and test GitHub OAuth. WorkOS will automatically use the default credentials, until you add your own GitHub Client ID and GitHub 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 GitHub 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 GitHub Client Secret for the OAuth flow, you will have the opportunity to customize the app, including its name, logo, etc.

In order to integrate you’ll need the GitHub Client ID and the GitHub Client Secret.

These are a pair of credentials provided by GitHub that you’ll use to authenticate your application via the OAuth protocol. To obtain them:

Log in to your GitHub account and go to the Developer Settings page in your GitHub settings dashboard and click on Register a new application.

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.

A screenshot showing the GitHub page to register a new OAuth application.

Start by filling out the form with relevant details about your application, like the application name and description.

For Authorization callback URL, use the Redirect URI in the GitHub OAuth configuration modal in the WorkOS Dashboard.

A screenshot showing the GitHub form to create a new OAuth application.

Finally, click on Register application.

On the next page, you will see the GitHub Client ID for your new OAuth application.

Click on 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.

A screenshot showing OAuth client credentials in the GitHub developer settings

In the next step, you will provide both the GitHub Client ID and Client Secret to the WorkOS dashboard.

Go back to the Authentication section in the WorkOS Dashboard, and click on Edit under GitHub OAuth.

Toggle Enabled on and provide the client credentials from GitHub that you generated in the previous step.

Finally, click Save.

A screenshot showing GitHub client credentials entered in the WorkOS dashboard

You are now ready to start authenticating with GitHub OAuth. Your users will see the option to sign-in with GitHub when visiting your AuthKit domain. Or, you can initiate sign-in with GitHub through the standalone SSO API by passing GitHubOAuth as the provider.