Set up social login with GitHub via GitHub App

Integrate GitHub App to enable Sign-in with GitHub, account linking, and secure access to GitHub APIs with fine-grained permissions and refresh tokens.

astuce:

This guide assumes you have basic understanding of Logto Connectors. For those unfamiliar, please refer to the Connectors guide to get started.

GitHub App vs OAuth App

GitHub offers two types of apps for authentication and API access: GitHub Apps and OAuth Apps. Here's a comparison to help you choose:

Feature	GitHub App	OAuth App
Permissions	Fine-grained permissions — request access to specific resources only	Broad scopes — often grants more access than needed
Permission management	Configured in GitHub dashboard only; Logto's Scope field can be empty	Configured via scopes in Logto connector
Refresh tokens	Always issued during OAuth flow	Not supported — tokens never expire unless revoked
Token expiration	Access tokens expire after 8 hours; refresh tokens valid for 6 months	Access tokens never expire
User control	Users can choose which repositories the app can access	Access to all repositories the user has access to
Rate limits	Higher rate limits that scale with installations	Lower rate limits (5,000 requests/hour per user)
Installation	Installed on accounts/organizations with granular repository access	Authorized by users with broad access
Webhooks	Built-in centralized webhook support	Must be configured separately for each repository
Acting independently	Can act on its own behalf (server-to-server)	Always acts on behalf of a user

When to use GitHub App:

• You need fine-grained control over permissions and repository access
• You want refresh tokens for long-term API access with enhanced security
• You need higher API rate limits
• You want to perform automated tasks independent of user sessions

When to use OAuth App:

• Simple sign-in integration with minimal API access
• You need tokens that don't expire (for legacy integrations)
• You need to access enterprise-level resources (GitHub Apps don't yet support enterprise-level permissions)

astuce:

GitHub recommends GitHub Apps over OAuth Apps for most use cases due to their enhanced security features and fine-grained permissions. Learn more about the differences between GitHub Apps and OAuth Apps.

Get started

The GitHub App connector enables OAuth 2.0 integration to let your application:

• Add "Sign-in with GitHub" authentication
• Link user accounts to GitHub identities
• Sync user profile info from GitHub
• Access GitHub APIs through secure token storage in Logto Secret Vault for automation tasks (e.g., creating GitHub issues, managing repositories from your app)
• Use refresh tokens (always issued by GitHub Apps) to maintain long-term API access without requiring users to re-authenticate

To set up these authentication features, create a GitHub connector in Logto first:

1. Go to Logto console > Connector > Social connector.
2. Click Add social connector, select GitHub App, click Next, and follow the step-by-step tutorial to complete the integration.

Step 1: Create a GitHub App

Before you can use GitHub as an authentication provider, you must create a GitHub App on GitHub to obtain OAuth 2.0 credentials.

1. Go to GitHub and sign in with your account, or create a new account if needed.
2. Navigate to Settings > Developer settings > GitHub Apps.
3. Click New GitHub App to register a new application:
   • GitHub App name: Enter a unique name for your app. The name cannot be longer than 34 characters and must be unique across GitHub.
   • Homepage URL: Enter your application's homepage URL.
   • Callback URL: Copy the Callback URI from your Logto GitHub connector and paste it here. You can add multiple callback URLs if needed. After users sign in with GitHub, they'll be redirected here with an authorization code that Logto uses to complete authentication.
   • Expire user authorization tokens: Keep this checked (recommended). This enables token expiration and refresh tokens for enhanced security.
   • Request user authorization (OAuth) during installation: Optionally check this to prompt users to authorize your app during installation.
   • Webhook: Uncheck Active if you don't need webhook events. For authentication-only use cases, webhooks are typically not required.
4. Under Permissions, configure the permissions your app needs (see Step 2 below for details).
5. Under Where can this GitHub App be installed?, select Any account if you want users from any GitHub account to use your app for authentication.
6. Click Create GitHub App to create the GitHub App.

remarque:

Unlike OAuth Apps, GitHub Apps use fine-grained permissions instead of broad scopes. You configure permissions in the GitHub dashboard during app creation, and users grant access to specific repositories during authorization.

For more details on setting up GitHub Apps, see Registering a GitHub App.

Step 2: Configure permissions in GitHub

GitHub Apps use fine-grained permissions instead of OAuth scopes. You must configure permissions in the GitHub dashboard when creating or editing your GitHub App. These permissions determine what data your app can access.

Understanding GitHub App permissions

Permissions are categorized into three types:

• Repository permissions: Access to repository-level resources (code, issues, pull requests, etc.)
• Organization permissions: Access to organization-level resources (members, teams, projects, etc.)
• Account permissions: Access to user account data (email, profile, followers, etc.)

For each permission, you can select:

• No access: The app cannot access this resource
• Read-only: The app can read but not modify this resource
• Read & write: The app can read and modify this resource

Recommended permissions for authentication

For basic "Sign in with GitHub" functionality, configure these minimum Account permissions:

Permission	Access level	Purpose
Email addresses	Read-only	Get user's email address for account creation

astuce:

GitHub Apps have implicit access to read public profile information when acting on behalf of a user. You don't need to explicitly request permission for basic profile data like username, avatar, and public profile URL.

Additional permissions for API access

If your application needs to access GitHub APIs beyond authentication, add the corresponding permissions in the GitHub dashboard. Here are some common examples:

Permission type	Permission	Access level	Use case
Repository	Contents	Read-only / Read & write	Access repository files and code
Repository	Issues	Read & write	Create and manage issues
Repository	Pull requests	Read & write	Create and manage pull requests
Repository	Metadata	Read-only	Access repository metadata (required for many operations)
Organization	Members	Read-only	List organization members
Account	Followers	Read-only	Access user's followers and following

This is not an exhaustive list — GitHub Apps support many more fine-grained permissions. See Permissions required for GitHub Apps for the complete list.

Key difference from OAuth Apps:

Unlike OAuth Apps where you configure scopes in the Logto connector, GitHub App permissions are managed entirely in the GitHub dashboard. You can leave the Scope field empty in your Logto GitHub connector — it's not needed because GitHub Apps don't use traditional OAuth scopes.

Simply configure the permissions you need in GitHub, and users will be prompted to grant access during authorization.

Step 3: Configure your Logto connector

After creating the GitHub App, you'll be redirected to its settings page where you can obtain the credentials.

1. On your GitHub App's settings page, copy the Client ID and paste it into the clientId field in Logto.
2. Under Client secrets, click Generate a new client secret. Copy the generated secret and paste it into the clientSecret field in Logto.
3. Click Save and Done in Logto to connect your identity system with GitHub.

attention:

Keep your Client secret secure and never expose it in client-side code. GitHub client secrets cannot be recovered if lost - you'll need to generate a new one.

remarque:

The Client ID for a GitHub App is different from the App ID. Make sure to use the Client ID (shown as "Client ID" on the settings page), not the App ID.

Step 4: General settings

Here are some general settings that won't block the connection to GitHub but may affect the end-user authentication experience.

Sync profile information

In the GitHub connector, you can configure how profile information is synced from GitHub user info to the Logto user profile, including name, avatar, and email. Choose from the following options:

• Only sync at sign-up: Profile info is fetched once when the user first signs in.
• Always sync at sign-in: Profile info is updated every time the user signs in.

Store tokens to access GitHub APIs (Optional)

If you want to access GitHub APIs and perform actions with user authorization (whether via social sign-in or account linking), enable token storage in Logto:

1. Configure the required permissions in your GitHub App settings (Step 2).
2. Enable Store tokens for persistent API access in the Logto GitHub connector. Logto will securely store both the access token and refresh token in the Secret Vault.

remarque:

Since GitHub Apps always issue refresh tokens, Logto stores both tokens automatically. The access token expires after 8 hours, but Logto can use the refresh token to obtain new access tokens, ensuring uninterrupted API access for up to 6 months.

Step 5: Test your integration (Optional)

Before going live, test your GitHub App integration:

1. Use the connector in a Logto development tenant.
2. Verify that users can sign in with GitHub.
3. Check that users are prompted for the correct permissions during authorization.
4. If you enabled token storage, verify that access tokens (and refresh tokens) are stored correctly.
5. Test API calls using the stored tokens to ensure permissions are working as expected.

GitHub Apps work with any GitHub user account immediately - there's no need for test users or app approval like some other platforms. However, if your app is installed on an organization, organization owners may need to approve the installation.

Utilize the GitHub connector

Once you've created a GitHub connector and connected it to GitHub, you can incorporate it into your end-user flows. Choose the options that match your needs:

Enable "Sign-in with GitHub"

1. In Logto Console, go to Sign-in experience > Sign-up and sign-in.
2. Add the GitHub connector under Social sign-in section to let users authenticate with GitHub.

Learn more about social sign-in experience.

Link or unlink a GitHub account

Use the Account API to build a custom Account Center in your app that lets signed-in users link or unlink their GitHub account. Follow the Account API tutorial

astuce:

It's allowed to enable the GitHub connector only for account linking and API access, without enabling it for social sign-in.

Access GitHub APIs and perform actions

Your application can retrieve stored GitHub tokens from the Secret Vault to call GitHub APIs and automate backend tasks (for example, creating issues, managing repositories, or automating workflows). Refer to the guide on retrieving stored tokens for API access.

Since GitHub Apps always issue refresh tokens during the OAuth flow, Logto stores both access tokens and refresh tokens. Access tokens expire after 8 hours, but Logto automatically uses the refresh token (valid for 6 months) to obtain new access tokens, ensuring uninterrupted API access.

Manage user's GitHub identity

After a user links their GitHub account, admins can manage that connection in the Logto Console:

1. Navigate to Logto console > User management and open the user's profile.
2. Under Social connections, locate the GitHub item and click Manage.
3. On this page, admins can manage the user's GitHub connection, see all profile information granted and synced from their GitHub account, and check the access token and refresh token status.

remarque:

Unlike OAuth Apps that use scopes, GitHub Apps use fine-grained permissions that are configured in the GitHub dashboard. The user access token is limited to the permissions that both your app and the user have. Logto cannot directly display the list of permissions, but your application will have access based on the permissions configured in your GitHub App settings.

Reference

GitHub Developer Documentation - About GitHub Apps

GitHub Developer Documentation - Registering a GitHub App

GitHub Developer Documentation - Generating user access tokens

GitHub Developer Documentation - Refreshing user access tokens

GitHub Apps vs OAuth Apps