Skip to content

Commit f6b97be

Browse files
author
Rany
authored
chore: merge pull request #1327 from logto-io/rany-integrate-github-app
refactor: add github app guide
2 parents 569cc50 + 6f55ba1 commit f6b97be

3 files changed

Lines changed: 254 additions & 4 deletions

File tree

‎docs/integrations/social/github-app/README.mdx‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
slug: /integrations/github-app
3+
sidebar_label: GitHub (GitHub App)
4+
sidebar_custom_props:
5+
darkLogoFilename: 'github-dark.svg'
6+
description: GitHub is an online community for software development and version control.
7+
tutorial_config_name: GitHub (GitHub App)
8+
---
9+
10+
import GuideTip from '../../fragments/_guide-tip.mdx';
11+
12+
import Integration from './_integration.mdx';
13+
14+
# Set up social login with GitHub via GitHub App
15+
16+
Integrate GitHub App to enable Sign-in with GitHub, account linking, and secure access to GitHub APIs with fine-grained permissions and refresh tokens.
17+
18+
<GuideTip />
19+
20+
## GitHub App vs OAuth App \{#github-app-vs-oauth-app}
21+
22+
GitHub offers two types of apps for authentication and API access: **GitHub Apps** and **OAuth Apps**. Here's a comparison to help you choose:
23+
24+
| Feature | GitHub App | OAuth App |
25+
| ------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------- |
26+
| **Permissions** | Fine-grained permissions — request access to specific resources only | Broad scopes — often grants more access than needed |
27+
| **Permission management** | Configured in GitHub dashboard only; Logto's `Scope` field can be empty | Configured via scopes in Logto connector |
28+
| **Refresh tokens** | Always issued during OAuth flow | Not supported — tokens never expire unless revoked |
29+
| **Token expiration** | Access tokens expire after 8 hours; refresh tokens valid for 6 months | Access tokens never expire |
30+
| **User control** | Users can choose which repositories the app can access | Access to all repositories the user has access to |
31+
| **Rate limits** | Higher rate limits that scale with installations | Lower rate limits (5,000 requests/hour per user) |
32+
| **Installation** | Installed on accounts/organizations with granular repository access | Authorized by users with broad access |
33+
| **Webhooks** | Built-in centralized webhook support | Must be configured separately for each repository |
34+
| **Acting independently** | Can act on its own behalf (server-to-server) | Always acts on behalf of a user |
35+
36+
**When to use GitHub App:**
37+
38+
- You need fine-grained control over permissions and repository access
39+
- You want refresh tokens for long-term API access with enhanced security
40+
- You need higher API rate limits
41+
- You want to perform automated tasks independent of user sessions
42+
43+
**When to use OAuth App:**
44+
45+
- Simple sign-in integration with minimal API access
46+
- You need tokens that don't expire (for legacy integrations)
47+
- You need to access enterprise-level resources (GitHub Apps don't yet support enterprise-level permissions)
48+
49+
:::tip
50+
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](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps).
51+
:::
52+
53+
## Get started \{#get-started}
54+
55+
The GitHub App connector enables OAuth 2.0 integration to let your application:
56+
57+
- Add "Sign-in with GitHub" authentication
58+
- Link user accounts to GitHub identities
59+
- Sync user profile info from GitHub
60+
- Access GitHub APIs through secure token storage in Logto Secret Vault for automation tasks (e.g., creating GitHub issues, managing repositories from your app)
61+
- Use **refresh tokens** (always issued by GitHub Apps) to maintain long-term API access without requiring users to re-authenticate
62+
63+
To set up these authentication features, create a GitHub connector in Logto first:
64+
65+
1. Go to <CloudLink to="/connectors/social">Logto console > Connector > Social connector</CloudLink>.
66+
2. Click **Add social connector**, select **GitHub App**, click **Next**, and follow the step-by-step tutorial to complete the integration.
67+
68+
<Integration />
69+
70+
## Utilize the GitHub connector \{#utilize-the-github-connector}
71+
72+
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:
73+
74+
### Enable "Sign-in with GitHub" \{#enable-sign-in-with-github}
75+
76+
1. In Logto Console, go to <CloudLink to="/sign-in-experience/sign-up-and-sign-in">Sign-in experience > Sign-up and sign-in</CloudLink>.
77+
2. Add the GitHub connector under **Social sign-in** section to let users authenticate with GitHub.
78+
79+
Learn more about [social sign-in experience](/end-user-flows/sign-up-and-sign-in/social-sign-in).
80+
81+
### Link or unlink a GitHub account \{#link-or-unlink-a-github-account}
82+
83+
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](/end-user-flows/account-settings/by-account-api#link-a-new-social-connection)
84+
85+
:::tip
86+
It's allowed to enable the GitHub connector only for account linking and API access, without enabling it for social sign-in.
87+
:::
88+
89+
### Access GitHub APIs and perform actions \{#access-github-apis-and-perform-actions}
90+
91+
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.
92+
93+
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.
94+
95+
## Manage user's GitHub identity \{#manage-user-s-github-identity}
96+
97+
After a user links their GitHub account, admins can manage that connection in the Logto Console:
98+
99+
1. Navigate to <CloudLink to="/users">Logto console > User management</CloudLink> and open the user's profile.
100+
2. Under **Social connections**, locate the GitHub item and click **Manage**.
101+
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.
102+
103+
:::note
104+
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.
105+
:::
106+
107+
## Reference \{#reference}
108+
109+
<Url href="https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps">
110+
GitHub Developer Documentation - About GitHub Apps
111+
</Url>
112+
113+
<Url href="https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app">
114+
GitHub Developer Documentation - Registering a GitHub App
115+
</Url>
116+
117+
<Url href="https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app">
118+
GitHub Developer Documentation - Generating user access tokens
119+
</Url>
120+
121+
<Url href="https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens">
122+
GitHub Developer Documentation - Refreshing user access tokens
123+
</Url>
124+
125+
<Url href="https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps">
126+
GitHub Apps vs OAuth Apps
127+
</Url>

‎docs/integrations/social/github-app/_integration.mdx‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
## Step 1: Create a GitHub App \{#step-1-create-a-github-app}
2+
3+
Before you can use GitHub as an authentication provider, you must create a GitHub App on GitHub to obtain OAuth 2.0 credentials.
4+
5+
1. Go to [GitHub](https://github.com/) and sign in with your account, or create a new account if needed.
6+
2. Navigate to [Settings > Developer settings > GitHub Apps](https://github.com/settings/apps).
7+
3. Click **New GitHub App** to register a new application:
8+
- **GitHub App name**: Enter a unique name for your app. The name cannot be longer than 34 characters and must be unique across GitHub.
9+
- **Homepage URL**: Enter your application's homepage URL.
10+
- **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.
11+
- **Expire user authorization tokens**: Keep this **checked** (recommended). This enables token expiration and refresh tokens for enhanced security.
12+
- **Request user authorization (OAuth) during installation**: Optionally check this to prompt users to authorize your app during installation.
13+
- **Webhook**: Uncheck **Active** if you don't need webhook events. For authentication-only use cases, webhooks are typically not required.
14+
4. Under **Permissions**, configure the permissions your app needs (see Step 2 below for details).
15+
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.
16+
6. Click **Create GitHub App** to create the GitHub App.
17+
18+
:::note
19+
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.
20+
21+
For more details on setting up GitHub Apps, see [Registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app).
22+
:::
23+
24+
## Step 2: Configure permissions in GitHub \{#step-2-configure-permissions-in-github}
25+
26+
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.
27+
28+
### Understanding GitHub App permissions \{#understanding-github-app-permissions}
29+
30+
Permissions are categorized into three types:
31+
32+
- **Repository permissions**: Access to repository-level resources (code, issues, pull requests, etc.)
33+
- **Organization permissions**: Access to organization-level resources (members, teams, projects, etc.)
34+
- **Account permissions**: Access to user account data (email, profile, followers, etc.)
35+
36+
For each permission, you can select:
37+
38+
- **No access**: The app cannot access this resource
39+
- **Read-only**: The app can read but not modify this resource
40+
- **Read & write**: The app can read and modify this resource
41+
42+
### Recommended permissions for authentication \{#recommended-permissions-for-authentication}
43+
44+
For basic "Sign in with GitHub" functionality, configure these minimum **Account permissions**:
45+
46+
| Permission | Access level | Purpose |
47+
| ------------------- | ------------ | --------------------------------------------- |
48+
| **Email addresses** | Read-only | Get user's email address for account creation |
49+
50+
:::tip
51+
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.
52+
:::
53+
54+
### Additional permissions for API access
55+
56+
If your application needs to access GitHub APIs beyond authentication, add the corresponding permissions in the GitHub dashboard. Here are some common examples:
57+
58+
| Permission type | Permission | Access level | Use case |
59+
| ---------------- | ------------- | ------------------------ | --------------------------------------------------------- |
60+
| **Repository** | Contents | Read-only / Read & write | Access repository files and code |
61+
| **Repository** | Issues | Read & write | Create and manage issues |
62+
| **Repository** | Pull requests | Read & write | Create and manage pull requests |
63+
| **Repository** | Metadata | Read-only | Access repository metadata (required for many operations) |
64+
| **Organization** | Members | Read-only | List organization members |
65+
| **Account** | Followers | Read-only | Access user's followers and following |
66+
67+
This is not an exhaustive list — GitHub Apps support many more fine-grained permissions. See [Permissions required for GitHub Apps](https://docs.github.com/en/rest/overview/permissions-required-for-github-apps) for the complete list.
68+
69+
:::tip[Key difference from OAuth Apps]
70+
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.
71+
72+
Simply configure the permissions you need in GitHub, and users will be prompted to grant access during authorization.
73+
:::
74+
75+
## Step 3: Configure your Logto connector \{#step-3-configure-your-logto-connector}
76+
77+
After creating the GitHub App, you'll be redirected to its settings page where you can obtain the credentials.
78+
79+
1. On your GitHub App's settings page, copy the **Client ID** and paste it into the `clientId` field in Logto.
80+
2. Under **Client secrets**, click **Generate a new client secret**. Copy the generated secret and paste it into the `clientSecret` field in Logto.
81+
3. Click **Save and Done** in Logto to connect your identity system with GitHub.
82+
83+
:::warning
84+
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.
85+
:::
86+
87+
:::note
88+
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.
89+
:::
90+
91+
## Step 4: General settings \{#step-4-general-settings}
92+
93+
Here are some general settings that won't block the connection to GitHub but may affect the end-user authentication experience.
94+
95+
### Sync profile information \{#sync-profile-information}
96+
97+
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:
98+
99+
- **Only sync at sign-up**: Profile info is fetched once when the user first signs in.
100+
- **Always sync at sign-in**: Profile info is updated every time the user signs in.
101+
102+
### Store tokens to access GitHub APIs (Optional) \{#store-tokens-to-access-github-apis-optional}
103+
104+
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:
105+
106+
1. Configure the required permissions in your GitHub App settings (Step 2).
107+
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.
108+
109+
:::note
110+
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.
111+
:::
112+
113+
## Step 5: Test your integration (Optional) \{#step-5-test-your-integration-optional}
114+
115+
Before going live, test your GitHub App integration:
116+
117+
1. Use the connector in a Logto development tenant.
118+
2. Verify that users can sign in with GitHub.
119+
3. Check that users are prompted for the correct permissions during authorization.
120+
4. If you enabled token storage, verify that access tokens (and refresh tokens) are stored correctly.
121+
5. Test API calls using the stored tokens to ensure permissions are working as expected.
122+
123+
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.

‎docs/integrations/social/github/README.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
11
---
22
slug: /integrations/github
3-
sidebar_label: GitHub
3+
sidebar_label: GitHub (OAuth App)
44
sidebar_custom_props:
55
darkLogoFilename: 'github-dark.svg'
66
description: GitHub is an online community for software development and version control.
7-
tutorial_config_name: GitHub OAuth app
7+
tutorial_config_name: GitHub OAuth App
88
---
99

1010
import GuideTip from '../../fragments/_guide-tip.mdx';
1111

1212
import Integration from './_integration.mdx';
1313

14-
# Set up social login with GitHub
14+
# Set up social login with GitHub via OAuth App
1515

16-
Integrate GitHub OAuth app to enable Sign-in with GitHub, account linking, and secure access to GitHub APIs.
16+
Integrate GitHub OAuth App to enable Sign-in with GitHub, account linking, and secure access to GitHub APIs.
1717

1818
<GuideTip />
1919

0 commit comments

Comments
 (0)