gitea-admin/gh-christianlouis-leagueledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add NetID OAuth provider integration and update login UI

Browse Source 
- Implemented NetID OAuth provider in app/auth/oauth.py
- Added styles for NetID login button in app/static/css/styles.css
- Updated login.html to include NetID login option with custom button
- Modified docker-compose.yml to include NetID client credentials
- Enhanced social login setup documentation to include NetID instructions
- Created demo environment configuration file (.env.demo) for easier setup
- Updated .env.template to include NetID configuration options
- Added comprehensive README.md with project features and setup instructions
This commit is contained in:
Christian Krakau-Louis
2025-04-15 14:28:14 +02:00
parent 6306abf6d9
commit 6d796c95ff
8 changed files with 863 additions and 179 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/social_login_setup.md
+138 -152
View File
@@ -1,54 +1,17 @@
# Setting Up Social Login in LeagueLedger
# Social Login Setup
LeagueLedger supports multiple social login (OAuth) providers to give your users various options for authentication. This document explains how to set up each supported provider.
This guide provides instructions for setting up various social login providers for LeagueLedger.
## Table of Contents
1. [General Setup](#general-setup)
2. [Callback URLs](#callback-urls)
3. [Provider-Specific Instructions](#provider-specific-instructions)
- [Google](#google)
- [GitHub](#github)
- [Facebook](#facebook)
- [Microsoft](#microsoft)
- [Discord](#discord)
- [LinkedIn](#linkedin)
- [Authentik](#authentik)
4. [Troubleshooting](#troubleshooting)
- [Google OAuth Setup](#google-oauth-setup)
- [Facebook Login Setup](#facebook-login-setup)
- [GitHub OAuth Setup](#github-oauth-setup)
- [LinkedIn OAuth Setup](#linkedin-oauth-setup)
- [Microsoft OAuth Setup](#microsoft-oauth-setup)
- [Discord OAuth Setup](#discord-oauth-setup)
- [NetID OAuth Setup](#netid-oauth-setup)
## General Setup
To enable social login in LeagueLedger, you need to:
1. Register your application with the desired OAuth provider(s)
2. Obtain client ID and client secret credentials
3. Add these credentials to your environment variables or `.env` file
4. Restart the application
Only providers with valid credentials will appear on the login page.
## Callback URLs
Each OAuth provider requires you to configure a **Redirect URI** (also known as a callback URL). This is where the provider redirects users after they authenticate.
For LeagueLedger, use the following pattern:
```
https://your-domain.com/auth/oauth-callback/{provider_id}
```
Replace:
- `your-domain.com` with your actual domain
- `{provider_id}` with one of: `google`, `github`, `facebook`, `microsoft`, `discord`, `linkedin`, or `authentik`
For local development, use:
```
http://localhost:8000/auth/oauth-callback/{provider_id}
```
**Important:** Most OAuth providers require exact URL matches, including protocol (http/https), domain, path, and any query parameters. Make sure to register the exact URL as shown above.
## Provider-Specific Instructions
### Google
## Google OAuth Setup
1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
@@ -68,26 +31,7 @@ http://localhost:8000/auth/oauth-callback/{provider_id}
GOOGLE_CLIENT_SECRET=your-client-secret
```
### GitHub
1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
2. Click "New OAuth App"
3. Fill in your application details:
- Application name: "LeagueLedger"
- Homepage URL: Your app's URL or `http://localhost:8000`
- Authorization callback URL:
```
http://localhost:8000/auth/oauth-callback/github
```
4. Click "Register application"
5. Generate a new client secret
6. Add to your `.env` file:
```
GITHUB_CLIENT_ID=your-client-id
GITHUB_CLIENT_SECRET=your-client-secret
```
### Facebook
## Facebook Login Setup
1. Go to [Facebook Developers](https://developers.facebook.com/)
2. Create a new app (choose "Consumer" or "Business" type)
@@ -103,48 +47,56 @@ http://localhost:8000/auth/oauth-callback/{provider_id}
FACEBOOK_CLIENT_SECRET=your-app-secret
```
### Microsoft
## GitHub OAuth Setup
1. Go to [Azure Portal](https://portal.azure.com/)
2. Navigate to "App registrations"
3. Click "New registration"
4. Enter a name for your application
5. For "Supported account types," choose an option based on your needs
(typically "Accounts in any organizational directory and personal Microsoft accounts")
6. Add the following Redirect URI (type: Web):
```
http://localhost:8000/auth/oauth-callback/microsoft
```
7. Click "Register"
8. Note the Application (client) ID
9. Create a client secret: Navigate to "Certificates & secrets" > "New client secret"
10. Add to your `.env` file:
```
MICROSOFT_CLIENT_ID=your-client-id
MICROSOFT_CLIENT_SECRET=your-client-secret
MICROSOFT_TENANT=common
```
Note: Use `common` for multi-tenant apps, or your specific tenant ID
### 1. Create a GitHub OAuth App
### Discord
1. Go to your GitHub account settings
2. Click on "Developer settings" in the left sidebar
3. Click on "OAuth Apps" and then "New OAuth App"
4. Fill out the form:
- **Application name**: LeagueLedger
- **Homepage URL**: Your site's URL (e.g. https://leagueledger.com)
- **Application description**: (Optional) A description of your app
- **Authorization callback URL**: Your callback URL (e.g. https://leagueledger.com/auth/oauth-callback/github)
5. Click "Register application"
6. You'll receive a Client ID
7. Click "Generate a new client secret" to create your Client Secret
8. Save both the Client ID and Client Secret safely
1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
2. Click "New Application"
3. Enter a name and click "Create"
4. Go to the "OAuth2" section in the left sidebar
5. Note the Client ID and generate a Client Secret
6. Add the following redirect URL:
```
http://localhost:8000/auth/oauth-callback/discord
```
7. In the "OAuth2 URL Generator" section, select the "identify" and "email" scopes
8. Add to your `.env` file:
```
DISCORD_CLIENT_ID=your-client-id
DISCORD_CLIENT_SECRET=your-client-secret
```
### 2. Configure Environment Variables
### LinkedIn
Add the following variables to your `.env` file:
```
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
```
### 3. Security Considerations
- **Never commit your Client Secret to version control**
- Store your Client Secret securely in environment variables or a secret management system
- In production, update the callback URL to use your production domain
- Consider implementing additional security measures like CSRF protection
### 4. Testing GitHub Login
After configuration:
1. Ensure the server is running with the environment variables loaded
2. Navigate to the login page
3. Click the "Login with GitHub" button
4. You should be redirected to GitHub's authorization page
5. After authorizing, you should be redirected back to your application and logged in
### 5. Troubleshooting GitHub OAuth
- **Invalid callback URL**: Ensure the callback URL registered in GitHub matches exactly what your application uses
- **Rate limiting**: GitHub has API rate limits that might affect your OAuth flow
- **Scope issues**: If you're not receiving email information, ensure you've requested the `user:email` scope
- **Token refresh**: If tokens expire, implement a refresh flow
## LinkedIn OAuth Setup
1. Go to the [LinkedIn Developer Portal](https://www.linkedin.com/developers/)
2. Click "Create app"
@@ -171,63 +123,97 @@ http://localhost:8000/auth/oauth-callback/{provider_id}
LINKEDIN_CLIENT_SECRET=your-client-secret
```
### Authentik
## Microsoft OAuth Setup
1. Access your Authentik admin interface
2. Go to "Applications" > "Providers" > "Create"
3. Select "OAuth2/OIDC Provider"
4. Configure the provider:
- Name: LeagueLedger
- Client Type: Confidential
- Redirect URIs:
```
http://localhost:8000/auth/oauth-callback/authentik
```
- Signing Key: Select an appropriate key or create one
5. Save the provider
6. Create an application:
- Go to "Applications" > "Applications" > "Create"
- Name: LeagueLedger
- Slug: leagueledger
- Provider: Select the provider you just created
7. Save the application
8. Note the Client ID and Client Secret
9. Add to your `.env` file:
1. Go to [Azure Portal](https://portal.azure.com/)
2. Navigate to "App registrations"
3. Click "New registration"
4. Enter a name for your application
5. For "Supported account types," choose an option based on your needs
(typically "Accounts in any organizational directory and personal Microsoft accounts")
6. Add the following Redirect URI (type: Web):
```
AUTHENTIK_CLIENT_ID=your-client-id
AUTHENTIK_CLIENT_SECRET=your-client-secret
AUTHENTIK_CONFIG_URL=https://your-authentik-domain/application/o/leagueledger/.well-known/openid-configuration
http://localhost:8000/auth/oauth-callback/microsoft
```
7. Click "Register"
8. Note the Application (client) ID
9. Create a client secret: Navigate to "Certificates & secrets" > "New client secret"
10. Add to your `.env` file:
```
MICROSOFT_CLIENT_ID=your-client-id
MICROSOFT_CLIENT_SECRET=your-client-secret
MICROSOFT_TENANT=common
```
Note: Use `common` for multi-tenant apps, or your specific tenant ID
## Discord OAuth Setup
1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
2. Click "New Application"
3. Enter a name and click "Create"
4. Go to the "OAuth2" section in the left sidebar
5. Note the Client ID and generate a Client Secret
6. Add the following redirect URL:
```
http://localhost:8000/auth/oauth-callback/discord
```
7. In the "OAuth2 URL Generator" section, select the "identify" and "email" scopes
8. Add to your `.env` file:
```
DISCORD_CLIENT_ID=your-client-id
DISCORD_CLIENT_SECRET=your-client-secret
```
## Troubleshooting
## NetID OAuth Setup
### Common Issues:
### 1. Create a NetID Service
1. **Provider not showing on login page**
- Check that client ID and secret are correctly set in your environment/`.env` file
- Verify that values are not empty strings
- Check application logs for initialization errors
1. Go to the [NetID Developer Zone](https://developer.netid.de/)
2. Create an account or log in with your existing credentials
3. Go to "Services" in the menu and click "Add service"
4. Fill in the required details:
- **Service domain**: Your site's domain (e.g., leagueledger.com)
- **URL privacy policy**: Link to your privacy policy
- **URL terms of usage**: Link to your terms of service
- Click "Add service"
2. **Authentication Error after provider login**
- Verify that the redirect URI is exactly as registered with the provider
- Check for protocol mismatch (http vs https)
- Ensure all required scopes have been granted
### 2. Create a NetID Client
3. **"Can't retrieve user email" errors**
- Ensure you've requested the email scope from the provider
- Some providers (like GitHub) require special permissions for email access
1. In your service's detail view, click "Add client"
2. Select the application type:
- For web application: select "Website"
- For mobile apps: select "Native / Mobile App (PKCE)"
3. Fill out the required fields:
- **Name**: "LeagueLedger"
- **Callback URL**: Your callback URL (e.g., https://leagueledger.com/auth/oauth-callback/netid)
- **Token signing**: Select "RS256" (recommended)
4. Save the client configuration
5. Note the Client ID and Client Secret
### Checking Provider Status:
### 3. Configure Environment Variables
You can check which providers are correctly configured by examining the login page:
- Only providers with valid credentials will appear as login options
- Look at application logs during startup for provider initialization messages
Add the following variables to your `.env` file:
### Provider-Specific Tips:
```
NETID_CLIENT_ID=your_netid_client_id
NETID_CLIENT_SECRET=your_netid_client_secret
```
- **Google**: Ensure the Google+ API is enabled in your Google Cloud project
- **GitHub**: For private email addresses, request the `user:email` scope
- **Discord**: Discord applications might need to be verified if you have a large user base
- **Microsoft**: Ensure the Microsoft Graph API permissions include User.Read
### 4. Testing
For more help, check the [official documentation](https://example.com/leagueledger/docs) or open an issue on the project repository.
During development, you'll need to:
1. Add test users to your service in the NetID Developer Zone
2. Use these test users when testing the login functionality
3. Request production approval once your integration is ready
### 5. Requesting Production Approval
When ready for production:
1. Go to your service's details in the NetID Developer Zone
2. Click "Request service release"
3. NetID will review your integration and approve it for production use
### 6. Helpful Resources
- [NetID Technical Documentation](https://developer.netid.de/single-sign-on-integration/technical-details/)
- [NetID Styleguide](https://developer.netid.de/single-sign-on-integration/styleguide/) for button styling requirements