mirror of https://github.com/requarks/wiki
Merge 03ad44357b into 407aacfa19
ss033
2 weeks ago
committed by
GitHub
commit
538f3cc677
@ -0,0 +1,257 @@
|
||||
# OAuth2 Setup Guide for Google and GitHub
|
||||
|
||||
This guide will help you set up OAuth2 authentication with Google and GitHub for Wiki.js.
|
||||
|
||||
## Overview
|
||||
|
||||
Wiki.js already includes built-in OAuth2 support for both Google and GitHub. This guide will walk you through:
|
||||
1. Setting up OAuth2 applications on Google and GitHub
|
||||
2. Configuring the authentication strategies in Wiki.js
|
||||
3. Troubleshooting common issues
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- A running Wiki.js instance
|
||||
- Admin access to your Wiki.js installation
|
||||
- A Google account (for Google OAuth)
|
||||
- A GitHub account (for GitHub OAuth)
|
||||
|
||||
---
|
||||
|
||||
## Google OAuth2 Setup
|
||||
|
||||
### Step 1: Create a Google OAuth2 Application
|
||||
|
||||
1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
|
||||
2. Create a new project or select an existing one
|
||||
3. Navigate to **APIs & Services** > **Credentials**
|
||||
4. Click **Create Credentials** > **OAuth client ID**
|
||||
5. If prompted, configure the OAuth consent screen:
|
||||
- Choose **External** (unless you have a Google Workspace account)
|
||||
- Fill in the required information (App name, User support email, Developer contact)
|
||||
- Add scopes: `profile`, `email`, `openid`
|
||||
- Save and continue
|
||||
6. Create the OAuth client:
|
||||
- Application type: **Web application**
|
||||
- Name: `Wiki.js` (or your preferred name)
|
||||
- Authorized redirect URIs: `https://your-wiki-domain.com/login/{strategy-key}/callback`
|
||||
- Replace `{strategy-key}` with the actual strategy key you'll use (e.g., `google-oauth`)
|
||||
- Example: `https://wiki.example.com/login/google-oauth/callback`
|
||||
- Click **Create**
|
||||
7. **Important**: Copy the **Client ID** and **Client Secret** - you'll need these in Wiki.js
|
||||
|
||||
### Step 2: Configure Google OAuth in Wiki.js
|
||||
|
||||
1. Log in to your Wiki.js admin panel
|
||||
2. Navigate to **Administration** > **Authentication**
|
||||
3. Click **Add Strategy** and select **Google**
|
||||
4. Fill in the configuration:
|
||||
- **Display Name**: `Google` (or your preferred name)
|
||||
- **Client ID**: Paste the Client ID from Google Cloud Console
|
||||
- **Client Secret**: Paste the Client Secret from Google Cloud Console
|
||||
- **Hosted Domain** (optional): If you want to restrict login to a specific Google Workspace domain (e.g., `example.com`), enter it here
|
||||
5. Configure additional settings:
|
||||
- **Self Registration**: Enable if you want new users to be automatically created
|
||||
- **Domain Whitelist**: Add allowed email domains (optional)
|
||||
- **Auto Enroll Groups**: Select groups to automatically assign to new users
|
||||
6. Click **Save**
|
||||
|
||||
### Step 3: Test Google OAuth
|
||||
|
||||
1. Log out of Wiki.js
|
||||
2. Go to the login page
|
||||
3. You should see a **Google** option in the authentication providers list
|
||||
4. Click on it and complete the OAuth flow
|
||||
5. You should be redirected back to Wiki.js and logged in
|
||||
|
||||
---
|
||||
|
||||
## GitHub OAuth2 Setup
|
||||
|
||||
### Step 1: Create a GitHub OAuth Application
|
||||
|
||||
1. Go to your GitHub account settings
|
||||
2. Navigate to **Developer settings** > **OAuth Apps** (or go directly to [GitHub OAuth Apps](https://github.com/settings/developers))
|
||||
3. Click **New OAuth App**
|
||||
4. Fill in the application details:
|
||||
- **Application name**: `Wiki.js` (or your preferred name)
|
||||
- **Homepage URL**: `https://your-wiki-domain.com`
|
||||
- **Authorization callback URL**: `https://your-wiki-domain.com/login/{strategy-key}/callback`
|
||||
- Replace `{strategy-key}` with the actual strategy key you'll use (e.g., `github-oauth`)
|
||||
- Example: `https://wiki.example.com/login/github-oauth/callback`
|
||||
5. Click **Register application**
|
||||
6. **Important**: Copy the **Client ID** and generate a **Client Secret** - you'll need these in Wiki.js
|
||||
|
||||
### Step 2: Configure GitHub OAuth in Wiki.js
|
||||
|
||||
1. Log in to your Wiki.js admin panel
|
||||
2. Navigate to **Administration** > **Authentication**
|
||||
3. Click **Add Strategy** and select **GitHub**
|
||||
4. Fill in the configuration:
|
||||
- **Display Name**: `GitHub` (or your preferred name)
|
||||
- **Client ID**: Paste the Client ID from GitHub
|
||||
- **Client Secret**: Paste the Client Secret from GitHub
|
||||
- **Use GitHub Enterprise**: Enable only if you're using GitHub Enterprise Server
|
||||
- **GitHub Enterprise Domain**: Only if using Enterprise (e.g., `github.company.com`)
|
||||
- **GitHub Enterprise User Endpoint**: Only if using Enterprise (e.g., `https://api.github.com/user`)
|
||||
5. Configure additional settings:
|
||||
- **Self Registration**: Enable if you want new users to be automatically created
|
||||
- **Domain Whitelist**: Add allowed email domains (optional)
|
||||
- **Auto Enroll Groups**: Select groups to automatically assign to new users
|
||||
6. Click **Save**
|
||||
|
||||
### Step 3: Test GitHub OAuth
|
||||
|
||||
1. Log out of Wiki.js
|
||||
2. Go to the login page
|
||||
3. You should see a **GitHub** option in the authentication providers list
|
||||
4. Click on it and complete the OAuth flow
|
||||
5. You should be redirected back to Wiki.js and logged in
|
||||
|
||||
---
|
||||
|
||||
## GitHub Enterprise Setup
|
||||
|
||||
If you're using GitHub Enterprise Server, follow these additional steps:
|
||||
|
||||
1. In Wiki.js, enable **Use GitHub Enterprise**
|
||||
2. Enter your **GitHub Enterprise Domain** (e.g., `github.company.com`)
|
||||
3. Enter your **GitHub Enterprise User Endpoint** (typically `https://github.company.com/api/v3/user`)
|
||||
4. Create an OAuth application in your GitHub Enterprise instance:
|
||||
- Go to your GitHub Enterprise instance
|
||||
- Navigate to **Settings** > **Developer settings** > **OAuth Apps**
|
||||
- Create a new OAuth app with the callback URL pointing to your Wiki.js instance
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### "Redirect URI mismatch" Error
|
||||
|
||||
**Problem**: The redirect URI in your OAuth app doesn't match the one Wiki.js is using.
|
||||
|
||||
**Solution**:
|
||||
1. Check the callback URL in your OAuth application settings
|
||||
2. The format should be: `https://your-domain.com/login/{strategy-key}/callback`
|
||||
3. Make sure the strategy key matches exactly (case-sensitive)
|
||||
4. Ensure there are no trailing slashes or extra characters
|
||||
|
||||
#### "Email address is required" Error
|
||||
|
||||
**Problem**: The OAuth provider isn't providing an email address.
|
||||
|
||||
**Solutions**:
|
||||
- **Google**: Make sure you've requested the `email` scope in your OAuth consent screen
|
||||
- **GitHub**:
|
||||
- Ensure your GitHub account has a verified email address
|
||||
- Make sure the `user:email` scope is granted (Wiki.js requests this automatically)
|
||||
- Check that the email isn't set to private in GitHub settings
|
||||
|
||||
#### "Authentication failed" Error
|
||||
|
||||
**Problem**: Generic authentication failure.
|
||||
|
||||
**Solutions**:
|
||||
1. Check the Wiki.js server logs for detailed error messages
|
||||
2. Verify your Client ID and Client Secret are correct
|
||||
3. Ensure your OAuth application is not disabled
|
||||
4. Check that the callback URL is correctly configured
|
||||
5. For Google: Verify the hosted domain setting if you're using one
|
||||
|
||||
#### Strategy Not Appearing on Login Page
|
||||
|
||||
**Problem**: The OAuth strategy doesn't show up on the login page.
|
||||
|
||||
**Solutions**:
|
||||
1. Make sure the strategy is **enabled** in the admin panel
|
||||
2. Check that the strategy has a valid configuration (Client ID and Secret)
|
||||
3. Restart Wiki.js if you just added the strategy
|
||||
4. Clear your browser cache
|
||||
|
||||
#### Domain Restriction Issues (Google)
|
||||
|
||||
**Problem**: Users from other domains can't log in when using hosted domain.
|
||||
|
||||
**Solution**:
|
||||
- This is expected behavior when `hostedDomain` is configured
|
||||
- Only users from the specified domain will be able to authenticate
|
||||
- Remove the hosted domain setting if you want to allow all Google accounts
|
||||
|
||||
### Debugging Tips
|
||||
|
||||
1. **Check Server Logs**: Wiki.js logs detailed information about OAuth authentication attempts. Look for messages starting with "Google OAuth:" or "GitHub OAuth:"
|
||||
|
||||
2. **Verify OAuth App Settings**: Double-check all settings in your OAuth application match what's configured in Wiki.js
|
||||
|
||||
3. **Test with Different Accounts**: Try authenticating with different Google/GitHub accounts to isolate the issue
|
||||
|
||||
4. **Check Network**: Ensure your Wiki.js server can reach the OAuth provider's servers (googleapis.com for Google, github.com for GitHub)
|
||||
|
||||
5. **HTTPS Requirement**: OAuth2 requires HTTPS in production. Make sure your Wiki.js instance is accessible via HTTPS
|
||||
|
||||
---
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. **Keep Secrets Secure**: Never commit Client Secrets to version control
|
||||
2. **Use HTTPS**: Always use HTTPS in production for OAuth callbacks
|
||||
3. **Restrict Domains**: Use domain whitelisting if you only want specific email domains
|
||||
4. **Regular Rotation**: Periodically rotate your OAuth Client Secrets
|
||||
5. **Monitor Logs**: Regularly check authentication logs for suspicious activity
|
||||
6. **Limit Scopes**: Only request the minimum required OAuth scopes
|
||||
|
||||
---
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Multiple OAuth Strategies
|
||||
|
||||
You can configure multiple instances of the same OAuth provider (e.g., multiple Google strategies) with different settings:
|
||||
- Different display names
|
||||
- Different domain restrictions
|
||||
- Different auto-enroll groups
|
||||
|
||||
### Self-Registration vs Manual User Creation
|
||||
|
||||
- **Self-Registration Enabled**: New users are automatically created when they first authenticate
|
||||
- **Self-Registration Disabled**: Only existing users can authenticate (they must be created manually first)
|
||||
|
||||
### Domain Whitelisting
|
||||
|
||||
You can restrict authentication to specific email domains:
|
||||
1. Enable **Self Registration**
|
||||
2. Add domains to **Domain Whitelist** (e.g., `example.com`, `company.org`)
|
||||
3. Only users with emails from these domains will be able to authenticate
|
||||
|
||||
### Auto-Enroll Groups
|
||||
|
||||
Automatically assign new users to specific groups:
|
||||
1. Enable **Self Registration**
|
||||
2. Select groups in **Auto Enroll Groups**
|
||||
3. New users will be automatically added to these groups upon first login
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
If you encounter issues not covered in this guide:
|
||||
|
||||
1. Check the [Wiki.js Documentation](https://docs.requarks.io)
|
||||
2. Review the [GitHub Issues](https://github.com/requarks/wiki/issues)
|
||||
3. Join the [Wiki.js Discord Community](https://discord.gg/wiki-js)
|
||||
|
||||
---
|
||||
|
||||
## Recent Enhancements
|
||||
|
||||
The OAuth2 implementations have been enhanced with:
|
||||
- ✅ Better error handling and user-friendly error messages
|
||||
- ✅ Comprehensive logging for debugging
|
||||
- ✅ Improved email validation
|
||||
- ✅ Enhanced profile handling
|
||||
- ✅ Better domain validation for Google hosted domains
|
||||
|
||||
These improvements make it easier to troubleshoot authentication issues and provide better feedback to users.
|
||||
|
||||
Loading…
Reference in new issue