Custom Social Login with GitHub

When you sign in with GitHub with Descope by default, the GitHub sign-in page will not be personalized to your website domain by default. In order to get that to work, you'll need to configure GitHub as a social login provider.

This guide provides a detailed walkthrough for setting up GitHub as a social login provider, covering both GitHub Apps and OAuth Apps.

Differences Between GitHub Apps and OAuth Apps

GitHub offers two types of applications for integrations: GitHub Apps and OAuth Apps.

The primary difference lies in the permission granularity and installation flow. GitHub Apps offer more granular permissions and are installed on a specific part of the user's GitHub account, whereas OAuth Apps are simpler and are authorized by the user for specific scopes.

For Descope to function properly with GitHub Apps, permissions to read the user's email are required. This guide will cover the setup process for both application types.

Creating the GitHub Application

For OAuth Apps

1. Create a New OAuth App: Go to your GitHub settings, navigate to the Developer settings, and create a new OAuth application.
2. Configure Callback Url: Set https://api.descope.com/v1/oauth/callback as the redirect URI. If you're using a Custom Domain, then you can find this in the GitHub configuration page in the Descope Console, under Github -> Use my own account:

3. Generate Client Secret: Select Generate a new client secret, and copy the secret value for use in the Descope Console.
4. Note Client ID: After creation, note the client ID for use in the Descope Console.

For GitHub Apps

1. Create a New GitHub App: In your GitHub settings, under Developer settings, create a new GitHub App.
2. Set Permissions: Ensure you set the read permission for the user's email.

3. Configure Callback Url: Similar to OAuth Apps, use https://api.descope.com/v1/oauth/callback. If you're using a Custom Domain, then you can find this in the GitHub configuration page in the Descope Console, under Github -> Use my own account:

4. Generate Client Secret: Select Generate a new client secret, and copy the secret value for use in the Descope Console.
5. Note Client ID: After creation, note the client ID for use in the Descope Console.

Configuring GitHub as a Social Login Provider in Descope

To configure GitHub apps or OAuth in Descope, the process is the same. Simply head to Social Login (OAuth / OIDC), under Authentication Methods, and then select GitHub -> Use my own account.

Then under the configuration page, do the following:

Authentication Account

• Set Provider Name to GitHub OAuth.
• Enter the Client ID and Client Secret from the GitHub OAuth App settings.
• Configure scopes as needed (e.g., user:email for email access). More information about scopes supported can be found on GitHub's documentation page.

Advanced Settings

Configure additional options such as token management, and redirect URLs as per your application's requirements.