From 784bf6eabbb2cb4f57beb0a5deb39eb092b60b23 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 5 Oct 2025 15:56:39 +0000 Subject: [PATCH 1/3] Initial plan From aa8a106ea6792cb90edaf4bd1b9bcfd8518d1c36 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 5 Oct 2025 16:09:14 +0000 Subject: [PATCH 2/3] Add comprehensive provider configuration documentation Co-authored-by: csharpfritz <78577+csharpfritz@users.noreply.github.com> --- user-docs/README.md | 81 +++++ .../Apple-OAuth-Configuration.md | 196 ++++++++++ .../GitHub-OAuth-Configuration.md | 341 +++++++++++++++++ .../Google-OAuth-Configuration.md | 106 ++++++ .../LinkedIn-OAuth-Configuration.md | 119 ++++++ .../Microsoft-OAuth-Configuration.md | 300 +++++++++++++++ .../Twitch-OAuth-Configuration.md | 91 +++++ .../providers/content/Blazot-Configuration.md | 340 +++++++++++++++++ .../content/Bluesky-Configuration.md | 258 +++++++++++++ .../content/Mastodon-Configuration.md | 234 ++++++++++++ .../content/TwitchChat-Configuration.md | 294 +++++++++++++++ .../content/Twitter-Configuration.md | 179 +++++++++ .../content/YouTubeChat-Configuration.md | 342 ++++++++++++++++++ 13 files changed, 2881 insertions(+) create mode 100644 user-docs/providers/authentication/Apple-OAuth-Configuration.md create mode 100644 user-docs/providers/authentication/GitHub-OAuth-Configuration.md create mode 100644 user-docs/providers/authentication/Google-OAuth-Configuration.md create mode 100644 user-docs/providers/authentication/LinkedIn-OAuth-Configuration.md create mode 100644 user-docs/providers/authentication/Microsoft-OAuth-Configuration.md create mode 100644 user-docs/providers/authentication/Twitch-OAuth-Configuration.md create mode 100644 user-docs/providers/content/Blazot-Configuration.md create mode 100644 user-docs/providers/content/Bluesky-Configuration.md create mode 100644 user-docs/providers/content/Mastodon-Configuration.md create mode 100644 user-docs/providers/content/TwitchChat-Configuration.md create mode 100644 user-docs/providers/content/Twitter-Configuration.md create mode 100644 user-docs/providers/content/YouTubeChat-Configuration.md diff --git a/user-docs/README.md b/user-docs/README.md index 72d2c5ea..4152666e 100644 --- a/user-docs/README.md +++ b/user-docs/README.md @@ -4,6 +4,8 @@ This folder contains documentation for TagzApp. ## Available Documentation +### User Manuals + - **[Moderator User Manual](Moderator_User_Manual.md)** - Comprehensive guide for content moderators - Interface overview and navigation - Moderation actions and workflows @@ -11,6 +13,85 @@ This folder contains documentation for TagzApp. - User management and blocking - Real-time features and troubleshooting +### Content Provider Configuration Guides + +These guides explain how to obtain API credentials and configure social media content providers: + +- **[Twitter/X Configuration](providers/content/Twitter-Configuration.md)** - Configure Twitter/X for hashtag monitoring + - Twitter Developer account setup + - Creating Twitter applications + - Obtaining Bearer Tokens + - Rate limits and best practices + +- **[Mastodon Configuration](providers/content/Mastodon-Configuration.md)** - Configure Mastodon federation monitoring + - Understanding Mastodon federation + - Choosing Mastodon instances + - No API keys required + - Public API access + +- **[Bluesky Configuration](providers/content/Bluesky-Configuration.md)** - Configure Bluesky (AT Protocol) monitoring + - Understanding the AT Protocol + - Public API access + - No credentials required + - Decentralized social networking + +- **[Twitch Chat Configuration](providers/content/TwitchChat-Configuration.md)** - Configure Twitch live chat monitoring + - Twitch Developer Console setup + - Creating OAuth applications + - Bot account configuration + - Real-time chat integration + +- **[YouTube Chat Configuration](providers/content/YouTubeChat-Configuration.md)** - Configure YouTube live stream chat + - Google Cloud Platform setup + - YouTube Data API v3 configuration + - OAuth 2.0 authentication + - Quota management + +- **[Blazot Configuration](providers/content/Blazot-Configuration.md)** - Configure Blazot social network monitoring + - Blazot account creation + - User vs Site accounts + - API key generation + - Rate limit management + +### Authentication Provider Configuration Guides + +These guides explain how to set up external login providers for TagzApp: + +- **[Microsoft OAuth Configuration](providers/authentication/Microsoft-OAuth-Configuration.md)** - Enable Sign in with Microsoft + - Azure Active Directory setup + - App registration + - Client credentials + - Multi-tenant support + +- **[GitHub OAuth Configuration](providers/authentication/GitHub-OAuth-Configuration.md)** - Enable Sign in with GitHub + - GitHub Developer Console + - OAuth app creation + - Scope management + - Organization apps + +- **[Google OAuth Configuration](providers/authentication/Google-OAuth-Configuration.md)** - Enable Sign in with Google + - Google Cloud Console setup + - OAuth consent screen + - Client credentials + - Publishing apps + +- **[Twitch OAuth Configuration](providers/authentication/Twitch-OAuth-Configuration.md)** - Enable Sign in with Twitch + - Twitch Developer Portal + - Application registration + - OAuth redirect configuration + +- **[LinkedIn OAuth Configuration](providers/authentication/LinkedIn-OAuth-Configuration.md)** - Enable Sign in with LinkedIn + - LinkedIn Developer Portal + - App creation + - LinkedIn Page requirement + - Product approval + +- **[Apple Sign In Configuration](providers/authentication/Apple-OAuth-Configuration.md)** - Enable Sign in with Apple + - Apple Developer account + - Services ID configuration + - JWT client secret generation + - Privacy features + ## Screenshots The `images/` folder contains screenshots and visual references used in the documentation: diff --git a/user-docs/providers/authentication/Apple-OAuth-Configuration.md b/user-docs/providers/authentication/Apple-OAuth-Configuration.md new file mode 100644 index 00000000..3fb213e9 --- /dev/null +++ b/user-docs/providers/authentication/Apple-OAuth-Configuration.md @@ -0,0 +1,196 @@ +# Apple Sign In Configuration Guide + +This guide will help you configure Sign in with Apple authentication for TagzApp, allowing users to sign in with their Apple IDs. + +## Overview + +Sign in with Apple enables users to authenticate to TagzApp using their Apple ID accounts. Apple requires this for iOS apps but can also be used for web applications. + +## Prerequisites + +- An Apple Developer account ($99/year for full access) +- Access to Apple Developer Portal +- For web: Ability to verify your domain + +## Quick Start + +### Step 1: Create an App ID + +1. Go to [Apple Developer Portal](https://developer.apple.com/account) +2. Sign in with your Apple Developer account +3. Navigate to **"Certificates, Identifiers & Profiles"** +4. Click **"Identifiers"** > **"+"** to create new +5. Select **"App IDs"** and click **"Continue"** +6. Select **"App"** and click **"Continue"** +7. Configure: + - **Description**: "TagzApp" + - **Bundle ID**: Choose "Explicit" and enter (e.g., `com.yourdomain.tagzapp`) + - **Capabilities**: Check **"Sign in with Apple"** +8. Click **"Continue"** and **"Register"** + +### Step 2: Create a Services ID + +1. In **"Identifiers"**, click **"+"** again +2. Select **"Services IDs"** and click **"Continue"** +3. Configure: + - **Description**: "TagzApp Web" + - **Identifier**: (e.g., `com.yourdomain.tagzapp.web`) + - Check **"Sign in with Apple"** +4. Click **"Continue"** and **"Register"** + +### Step 3: Configure Sign in with Apple + +1. Select your Services ID from the list +2. Check **"Sign in with Apple"** +3. Click **"Configure"** +4. Configure settings: + - **Primary App ID**: Select the App ID you created + - **Domains**: Add `yourdomain.com` + - **Return URLs**: Add `https://yourdomain.com/signin-apple` +5. Click **"Save"** and **"Continue"** +6. Click **"Register"** + +### Step 4: Create a Key for Sign in with Apple + +1. Navigate to **"Keys"** > **"+"** +2. Configure: + - **Key Name**: "TagzApp Sign in with Apple Key" + - Check **"Sign in with Apple"** + - Click **"Configure"** + - Select your Primary App ID +3. Click **"Continue"** and **"Register"** +4. **Download the key file (.p8)** - you can't download it again! +5. Note the **Key ID** shown on the confirmation page + +### Step 5: Get Your Credentials + +You'll need: +- **Services ID (Client ID)**: The identifier you created (e.g., `com.yourdomain.tagzapp.web`) +- **Team ID**: Found in the top right of Apple Developer Portal +- **Key ID**: From the key you created +- **Private Key (.p8 file)**: The file you downloaded + +### Step 6: Configure TagzApp + +**Admin UI:** +1. Navigate to **Admin > External Authentication** +2. Find **"Apple"** provider +3. Enter the configuration: + - **Client ID**: Your Services ID + - **Client Secret**: This is complex - see "Generating Client Secret" below + - **Enabled**: Toggle to enable +4. Click **"Save"** + +### Generating the Client Secret + +Apple uses JWT tokens instead of simple client secrets. You need to: + +1. Use your Team ID, Key ID, and private key (.p8) +2. Generate a JWT token programmatically or use a tool +3. The JWT must be signed with ES256 algorithm +4. Token is valid for up to 6 months + +**Example using a JWT library:** +```csharp +var privateKey = "-----BEGIN PRIVATE KEY-----\n[your key]\n-----END PRIVATE KEY-----"; +var token = CreateAppleJWT( + teamId: "YOUR_TEAM_ID", + clientId: "com.yourdomain.tagzapp.web", + keyId: "YOUR_KEY_ID", + privateKey: privateKey +); +``` + +**Note:** This is complex. Consider using Apple's official SDKs or existing libraries. + +**Configuration File:** +```json +{ + "Authentication": { + "Apple": { + "ClientID": "com.yourdomain.tagzapp.web", + "ClientSecret": "your-jwt-client-secret", + "Enabled": "true" + } + } +} +``` + +## Testing + +1. Log out of TagzApp +2. Click **"Sign in with Apple"** +3. Sign in with your Apple ID +4. Choose whether to share or hide your email +5. You should be signed in to TagzApp + +## Troubleshooting + +### "Invalid Client" +- Verify Services ID (Client ID) is correct +- Check that JWT client secret is valid and not expired +- Regenerate JWT if it's been more than 6 months + +### "Invalid Request" +- Verify return URL in Apple Developer Portal matches exactly +- Ensure domain is verified +- Check Services ID configuration + +### "Domain Not Verified" +- Apple requires domain verification +- Ensure your domain is added and verified in Services ID config + +### Client Secret Expired +- Apple JWT tokens expire after 6 months maximum +- Generate a new JWT token with the same key +- Update TagzApp configuration + +## Privacy Features + +Apple Sign In includes privacy-focused features: +- **Hide My Email**: Users can choose to hide their actual email +- **Private relay**: Apple provides a relay email (e.g., xyz@privaterelay.appleid.com) +- **Name control**: Users can choose what name to share + +## Security Notes + +1. **Protect your private key**: Never commit the .p8 file to source control +2. **Rotate keys periodically**: Generate new keys annually +3. **Limit key access**: Only authorized personnel should have access +4. **JWT expiration**: Set appropriate expiration (up to 6 months) + +## Advanced Configuration + +### Handling Private Relay Emails + +When users hide their email, Apple provides a relay address: +- Forward emails to this relay address +- Apple forwards to the user's real email +- Relay remains active even if user changes actual email + +### Revoking Access + +Users can revoke access at: +1. Apple ID website or iOS Settings +2. Navigate to Security > Apps Using Your Apple ID +3. Select TagzApp and click "Stop Using Apple ID" + +## Limitations + +- **Requires Apple Developer account** ($99/year) +- **Complex setup** compared to other OAuth providers +- **JWT secret management** adds complexity +- **iOS-first design** may not integrate as smoothly with web apps + +## Additional Resources + +- [Sign in with Apple Documentation](https://developer.apple.com/sign-in-with-apple/) +- [Apple Developer Portal](https://developer.apple.com/account) +- [Configuring Your Webpage](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js/configuring_your_webpage_for_sign_in_with_apple) +- [Generate and Validate Tokens](https://developer.apple.com/documentation/sign_in_with_apple/generate_and_validate_tokens) + +## Need Help? + +Check the [TagzApp GitHub Issues](https://github.com/FritzAndFriends/TagzApp/issues) or consult Apple's Sign in with Apple documentation. + +**Note:** Due to the complexity of Apple Sign In, consider starting with simpler OAuth providers (Google, GitHub, Microsoft) first. diff --git a/user-docs/providers/authentication/GitHub-OAuth-Configuration.md b/user-docs/providers/authentication/GitHub-OAuth-Configuration.md new file mode 100644 index 00000000..c4855d4b --- /dev/null +++ b/user-docs/providers/authentication/GitHub-OAuth-Configuration.md @@ -0,0 +1,341 @@ +# GitHub OAuth Configuration Guide + +This guide will help you configure GitHub OAuth authentication for TagzApp, allowing users to sign in with their GitHub accounts. + +## Overview + +The GitHub OAuth provider enables users to authenticate to TagzApp using their GitHub accounts. This is particularly useful for developer-focused events and communities. + +## Prerequisites + +- A GitHub account +- Repository or organization admin access (for organizational apps) + +## Step 1: Create a GitHub OAuth App + +1. Go to [GitHub.com](https://github.com) and sign in +2. Click on your profile picture (top right) and select **"Settings"** +3. Scroll down in the left sidebar and click **"Developer settings"** +4. Click **"OAuth Apps"** in the left sidebar +5. Click **"New OAuth App"** or **"Register a new application"** + +## Step 2: Configure Your OAuth Application + +Fill in the application registration form: + +### Application Details + +- **Application name**: "TagzApp" (or your preferred name) +- **Homepage URL**: Your TagzApp URL + - Production: `https://yourdomain.com` + - Development: `https://localhost:5001` +- **Application description**: (Optional) "TagzApp social media aggregator authentication" +- **Authorization callback URL**: Your TagzApp OAuth callback URL + - Production: `https://yourdomain.com/signin-github` + - Development: `https://localhost:5001/signin-github` + - **Important:** This must match exactly what TagzApp uses + +### Important Notes + +- The callback URL must match exactly (protocol, domain, port, path) +- You can only specify one callback URL per OAuth app +- For multiple environments, create separate OAuth apps + +Click **"Register application"** + +## Step 3: Get Your Client Credentials + +After creating your OAuth app, you'll see the application page: + +1. Copy the **Client ID** - this is visible on the page +2. Click **"Generate a new client secret"** +3. **Important:** Copy the **Client Secret** immediately - you won't be able to see it again! +4. Store both the Client ID and Client Secret securely + +**⚠️ Security Warning:** The Client Secret is sensitive. Never share it, commit it to source control, or expose it in client-side code. + +## Step 4: Configure TagzApp + +### Using the Admin UI (Recommended) + +1. Log in to TagzApp as an administrator +2. Navigate to **Admin > External Authentication** +3. Find the **"GitHub"** provider +4. Enter your credentials: + - **Client ID**: Your GitHub OAuth App Client ID + - **Client Secret**: Your GitHub OAuth App Client Secret + - **Enabled**: Toggle to enable the provider +5. Click **"Save Configuration"** + +### Using Configuration Files + +**appsettings.json:** +```json +{ + "Authentication": { + "GitHub": { + "ClientID": "your-github-client-id", + "ClientSecret": "your-github-client-secret", + "Enabled": "true" + } + } +} +``` + +**Environment Variables:** +```bash +Authentication__GitHub__ClientID=your-github-client-id +Authentication__GitHub__ClientSecret=your-github-client-secret +Authentication__GitHub__Enabled=true +``` + +**Azure Key Vault:** +Store with the key: +``` +TagzApp-Authentication-GitHub +``` + +## Step 5: Test Your Configuration + +1. Log out of TagzApp (if logged in) +2. Navigate to the login page +3. You should see a **"Sign in with GitHub"** button +4. Click the button +5. You'll be redirected to GitHub's authorization page +6. Click **"Authorize [your-app-name]"** to grant permissions +7. You'll be redirected back to TagzApp and logged in + +## Understanding GitHub Scopes + +GitHub OAuth uses scopes to control what data your application can access: + +### Default Scopes + +The GitHub OAuth provider in TagzApp uses minimal scopes by default: +- `read:user` - Read basic user profile information +- `user:email` - Read user email addresses + +### User Data Accessed + +With these scopes, TagzApp can access: +- GitHub username +- Display name +- Public email address +- Avatar/profile picture +- Unique user ID + +### Privacy Considerations + +- Only public profile information is accessed +- Private repositories are not accessed +- Organization memberships may be visible if public +- Users control what email addresses are public + +## Troubleshooting + +### Common Issues + +#### "Redirect URI Mismatch" Error +- **Cause**: The callback URL doesn't match the one configured in your GitHub OAuth app +- **Solution**: + - Verify the Authorization callback URL in your GitHub OAuth app settings + - Ensure it matches: `https://yourdomain.com/signin-github` + - Check protocol (http vs https) and port match exactly + - No trailing slashes should be added + +#### "Bad Verification Code" Error +- **Cause**: OAuth flow failed or expired +- **Solution**: + - Try authenticating again from the start + - Clear browser cache and cookies + - Verify Client ID and Client Secret are correct + - Check that the OAuth app is not suspended + +#### "Application Suspended" Error +- **Cause**: Your GitHub OAuth app has been suspended (rare) +- **Solution**: + - Check your GitHub account for notifications + - Review GitHub's OAuth App guidelines + - Contact GitHub Support if needed + +#### "Invalid Client" Error +- **Cause**: Client ID or Client Secret is incorrect +- **Solution**: + - Verify you copied the full Client ID + - Regenerate Client Secret if needed + - Update TagzApp configuration + - Ensure there are no extra spaces or characters + +#### Sign In Button Not Appearing +- **Cause**: Provider not enabled or configuration not saved +- **Solution**: + - Check that GitHub provider is enabled in TagzApp admin + - Verify configuration was saved successfully + - Restart TagzApp if needed + - Check application logs for errors + +## Security Best Practices + +1. **Use separate OAuth apps** for development and production +2. **Rotate client secrets** periodically (every 6-12 months) +3. **Never commit secrets** to source control +4. **Use environment variables** or secure vaults for credentials +5. **Monitor OAuth app usage** in GitHub settings +6. **Revoke unused OAuth apps** regularly +7. **Review authorized applications** in your GitHub account settings + +## Multiple Environments + +### Best Practice: Separate OAuth Apps + +Create different OAuth apps for each environment: + +1. **Development OAuth App** + - Callback URL: `https://localhost:5001/signin-github` + - Name: "TagzApp (Development)" + +2. **Staging OAuth App** + - Callback URL: `https://staging.yourdomain.com/signin-github` + - Name: "TagzApp (Staging)" + +3. **Production OAuth App** + - Callback URL: `https://yourdomain.com/signin-github` + - Name: "TagzApp" + +### Managing Multiple Apps + +- Use different configuration per environment +- Each environment uses its own Client ID and Secret +- Prevents development OAuth from affecting production + +## Organization OAuth Apps vs Personal OAuth Apps + +### Personal OAuth Apps +- Created under your personal account +- Suitable for small teams or personal projects +- You control the OAuth app settings + +### Organization OAuth Apps +- Created under a GitHub organization +- Better for team projects and enterprises +- Organization admins can manage the app +- Can integrate with organization SSO + +To create an organization OAuth app: +1. Go to your organization's settings +2. Click "Developer settings" > "OAuth Apps" +3. Follow the same steps as personal OAuth apps + +## Revoking Access + +### For Users + +Users can revoke TagzApp's access to their GitHub account: +1. Go to [GitHub Settings > Applications](https://github.com/settings/applications) +2. Find your TagzApp application in "Authorized OAuth Apps" +3. Click "Revoke" to remove access + +### For Admins + +To revoke or regenerate credentials: +1. Go to your OAuth app settings in GitHub +2. Regenerate client secret (old secret stops working immediately) +3. Update TagzApp configuration with new secret +4. Or delete the OAuth app entirely to revoke all access + +## Monitoring OAuth App Usage + +### View OAuth App Activity + +1. Go to your GitHub OAuth app settings +2. No built-in analytics in GitHub OAuth apps +3. Monitor through TagzApp's own logs and analytics +4. Check GitHub account notification for security alerts + +### Security Alerts + +GitHub may notify you if: +- Unusual authorization patterns detected +- OAuth app policy violations +- Security issues with your app + +## Rate Limits + +GitHub OAuth has rate limits: +- **Authenticated requests**: 5,000 requests per hour (per user) +- **OAuth authorizations**: No specific limit for OAuth flow +- TagzApp's authentication only uses a few requests per login + +## GitHub Enterprise Support + +TagzApp can work with GitHub Enterprise: + +### Configuration Changes + +For GitHub Enterprise Server (self-hosted): + +```json +{ + "Authentication": { + "GitHub": { + "ClientID": "your-client-id", + "ClientSecret": "your-client-secret", + "AuthorizationEndpoint": "https://github.yourcompany.com/login/oauth/authorize", + "TokenEndpoint": "https://github.yourcompany.com/login/oauth/access_token", + "UserInformationEndpoint": "https://github.yourcompany.com/api/v3/user" + } + } +} +``` + +**Note:** This may require custom configuration in TagzApp's authentication setup. + +## Privacy and Data Handling + +### What Data is Collected + +TagzApp stores: +- GitHub username +- Display name +- Email address (if public) +- GitHub user ID +- Avatar URL (for display) + +### What Data is NOT Collected + +- Private repository information +- Code or file contents +- Organization secrets +- SSH keys or personal access tokens +- Private organization memberships + +## Compliance + +### GDPR + +- Users can view and export their data through TagzApp +- Users can delete their account and data +- Users can revoke OAuth access at any time + +### Data Retention + +- User profile data stored as long as account exists +- Authentication tokens refreshed automatically +- No unnecessary data retention + +## Additional Resources + +- [GitHub OAuth Documentation](https://docs.github.com/en/developers/apps/building-oauth-apps) +- [Creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) +- [Authorizing OAuth Apps](https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps) +- [OAuth App Scopes](https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps) +- [GitHub Authentication Best Practices](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps) + +## Need Help? + +If you encounter issues not covered here: +1. Check the [TagzApp GitHub Issues](https://github.com/FritzAndFriends/TagzApp/issues) +2. Review GitHub OAuth app settings for configuration errors +3. Check TagzApp application logs for detailed error messages +4. Consult GitHub's OAuth documentation +5. Open a new issue on GitHub with details about your problem diff --git a/user-docs/providers/authentication/Google-OAuth-Configuration.md b/user-docs/providers/authentication/Google-OAuth-Configuration.md new file mode 100644 index 00000000..4466004a --- /dev/null +++ b/user-docs/providers/authentication/Google-OAuth-Configuration.md @@ -0,0 +1,106 @@ +# Google OAuth Configuration Guide + +This guide will help you configure Google OAuth authentication for TagzApp, allowing users to sign in with their Google accounts. + +## Overview + +The Google OAuth provider enables users to authenticate to TagzApp using their Google accounts (Gmail, Google Workspace, etc.). + +## Prerequisites + +- A Google account +- Access to Google Cloud Console + +## Quick Start + +### Step 1: Create a Google Cloud Project + +1. Go to [Google Cloud Console](https://console.cloud.google.com/) +2. Click **"Select a project"** > **"New Project"** +3. Enter project name (e.g., "TagzApp Authentication") +4. Click **"Create"** + +### Step 2: Configure OAuth Consent Screen + +1. Navigate to **"APIs & Services"** > **"OAuth consent screen"** +2. Select **"External"** user type +3. Click **"Create"** +4. Fill in required information: + - **App name**: "TagzApp" + - **User support email**: Your email + - **Developer contact email**: Your email +5. Click **"Save and Continue"** through remaining screens + +### Step 3: Create OAuth Credentials + +1. Go to **"APIs & Services"** > **"Credentials"** +2. Click **"+ Create Credentials"** > **"OAuth client ID"** +3. Select **"Web application"** +4. Configure: + - **Name**: "TagzApp Web Client" + - **Authorized redirect URIs**: + - Add: `https://yourdomain.com/signin-google` + - Development: `https://localhost:5001/signin-google` +5. Click **"Create"** +6. **Copy the Client ID and Client Secret immediately!** + +### Step 4: Configure TagzApp + +**Admin UI:** +1. Navigate to **Admin > External Authentication** +2. Find **"Google"** provider +3. Enter **Client ID** and **Client Secret** +4. Toggle **Enabled** +5. Click **"Save"** + +**Configuration File:** +```json +{ + "Authentication": { + "Google": { + "ClientID": "your-client-id.apps.googleusercontent.com", + "ClientSecret": "your-client-secret", + "Enabled": "true" + } + } +} +``` + +## Testing + +1. Log out of TagzApp +2. Click **"Sign in with Google"** +3. Select your Google account +4. Grant permissions +5. You should be signed in to TagzApp + +## Troubleshooting + +### "Redirect URI Mismatch" +- Verify the redirect URI in Google Cloud Console matches exactly: `https://yourdomain.com/signin-google` + +### "Invalid Client" +- Regenerate credentials in Google Cloud Console +- Update TagzApp configuration + +### "Access Denied" +- Check OAuth consent screen is configured +- Verify user is added as test user (if app is in testing mode) + +## Publishing Your App (Optional) + +For production use with any Google account: + +1. In OAuth consent screen, click **"Publish App"** +2. Submit for verification if prompted +3. Or keep in testing mode and add users manually + +## Additional Resources + +- [Google OAuth Documentation](https://developers.google.com/identity/protocols/oauth2) +- [Google Cloud Console](https://console.cloud.google.com/) +- [OAuth Consent Screen Guide](https://support.google.com/cloud/answer/10311615) + +## Need Help? + +Check the [TagzApp GitHub Issues](https://github.com/FritzAndFriends/TagzApp/issues) or consult Google's OAuth documentation. diff --git a/user-docs/providers/authentication/LinkedIn-OAuth-Configuration.md b/user-docs/providers/authentication/LinkedIn-OAuth-Configuration.md new file mode 100644 index 00000000..2aa43053 --- /dev/null +++ b/user-docs/providers/authentication/LinkedIn-OAuth-Configuration.md @@ -0,0 +1,119 @@ +# LinkedIn OAuth Configuration Guide + +This guide will help you configure LinkedIn OAuth authentication for TagzApp, allowing users to sign in with their LinkedIn accounts. + +## Overview + +The LinkedIn OAuth provider enables users to authenticate to TagzApp using their LinkedIn accounts. Ideal for professional networking events and corporate use cases. + +## Prerequisites + +- A LinkedIn account +- Access to LinkedIn Developer Portal + +## Quick Start + +### Step 1: Create a LinkedIn App + +1. Go to [LinkedIn Developers](https://www.linkedin.com/developers/) +2. Sign in with your LinkedIn account +3. Click **"Create app"** +4. Fill in the application details: + - **App name**: "TagzApp" + - **LinkedIn Page**: Select or create a LinkedIn page (required) + - **Privacy policy URL**: Your privacy policy URL + - **App logo**: Upload a logo (optional) +5. Check the legal agreement +6. Click **"Create app"** + +### Step 2: Configure OAuth Settings + +1. In your app, go to the **"Auth"** tab +2. Under **"OAuth 2.0 settings"**: + - **Authorized redirect URLs**: Add `https://yourdomain.com/signin-linkedin` + - For development: `https://localhost:5001/signin-linkedin` +3. Click **"Update"** + +### Step 3: Get Your Credentials + +1. In the **"Auth"** tab, find: + - **Client ID** - Copy this + - **Client Secret** - Click "Show" and copy +2. Store both securely + +### Step 4: Request OAuth Scopes + +1. Go to the **"Products"** tab +2. Request access to **"Sign In with LinkedIn using OpenID Connect"** +3. Wait for approval (usually immediate for Sign In product) + +### Step 5: Configure TagzApp + +**Admin UI:** +1. Navigate to **Admin > External Authentication** +2. Find **"LinkedIn"** provider +3. Enter **Client ID** and **Client Secret** +4. Toggle **Enabled** +5. Click **"Save"** + +**Configuration File:** +```json +{ + "Authentication": { + "LinkedIn": { + "ClientID": "your-client-id", + "ClientSecret": "your-client-secret", + "Enabled": "true" + } + } +} +``` + +## Testing + +1. Log out of TagzApp +2. Click **"Sign in with LinkedIn"** +3. Authorize the application +4. You should be signed in to TagzApp + +## Troubleshooting + +### "Redirect URI Mismatch" +- Verify the redirect URL in LinkedIn app settings matches: `https://yourdomain.com/signin-linkedin` + +### "Invalid Redirect URI" +- LinkedIn requires HTTPS (except for localhost) +- Ensure no trailing slashes in the redirect URI + +### "Product Not Approved" +- Request "Sign In with LinkedIn" product access +- Wait for approval (usually instant) + +### "Invalid Client" +- Verify Client ID and Client Secret +- Ensure app is not in development restrictions + +## LinkedIn Page Requirement + +LinkedIn requires you to associate your app with a LinkedIn Page: +- Can be a personal or company page +- Used for verification and user trust +- Page doesn't need to be published or active + +## Data Access + +With Sign In with LinkedIn, you can access: +- Name +- Email address +- Profile picture +- Basic profile information + +## Additional Resources + +- [LinkedIn OAuth Documentation](https://docs.microsoft.com/linkedin/shared/authentication/authentication) +- [LinkedIn Developer Portal](https://www.linkedin.com/developers/) +- [Sign In with LinkedIn](https://docs.microsoft.com/linkedin/consumer/integrations/self-serve/sign-in-with-linkedin) + +## Need Help? + +Check the [TagzApp GitHub Issues](https://github.com/FritzAndFriends/TagzApp/issues) or consult LinkedIn's OAuth documentation. diff --git a/user-docs/providers/authentication/Microsoft-OAuth-Configuration.md b/user-docs/providers/authentication/Microsoft-OAuth-Configuration.md new file mode 100644 index 00000000..d7a26da7 --- /dev/null +++ b/user-docs/providers/authentication/Microsoft-OAuth-Configuration.md @@ -0,0 +1,300 @@ +# Microsoft OAuth Configuration Guide + +This guide will help you configure Microsoft OAuth authentication for TagzApp, allowing users to sign in with their Microsoft accounts (including Office 365 and Azure AD accounts). + +## Overview + +The Microsoft OAuth provider enables users to authenticate to TagzApp using their Microsoft accounts. This includes: +- Personal Microsoft accounts (outlook.com, hotmail.com, live.com) +- Work or school accounts (Office 365, Azure AD) +- Azure B2C accounts + +## Prerequisites + +- An Azure account (free tier available) +- Access to Azure Active Directory (included with Azure account) +- Administrator permissions to register applications + +## Step 1: Sign In to Azure Portal + +1. Go to the [Azure Portal](https://portal.azure.com) +2. Sign in with your Microsoft account +3. If you don't have an Azure account, create one (free tier available) + +## Step 2: Register an Application + +1. In the Azure Portal, search for **"Azure Active Directory"** or **"Microsoft Entra ID"** +2. Click on **Azure Active Directory** in the search results +3. In the left menu, click **"App registrations"** +4. Click **"+ New registration"** +5. Fill in the application details: + - **Name**: "TagzApp" (or your preferred name) + - **Supported account types**: Choose based on your needs: + - **Single tenant**: Only your organization + - **Multi-tenant**: Any organization's directory + - **Multi-tenant and personal**: Any organization + personal Microsoft accounts (Recommended) + - **Personal only**: Only personal Microsoft accounts + - **Redirect URI**: + - Platform: **Web** + - URI: `https://yourdomain.com/signin-microsoft` + - For development: `https://localhost:5001/signin-microsoft` (adjust port as needed) +6. Click **"Register"** + +## Step 3: Get Your Application Credentials + +After registration, you'll see the application overview page: + +1. Copy the **Application (client) ID** - this is your Client ID +2. Copy the **Directory (tenant) ID** (you may need this for certain configurations) +3. Keep this page open - you'll need it for the next step + +## Step 4: Create a Client Secret + +1. In your app registration, click **"Certificates & secrets"** in the left menu +2. Click **"+ New client secret"** +3. Configure the secret: + - **Description**: "TagzApp Secret" (or your preferred description) + - **Expires**: Choose an expiration period (6 months, 12 months, 24 months, or custom) + - **Recommendation**: Choose 12 or 24 months and set a reminder to rotate +4. Click **"Add"** +5. **Important:** Copy the secret **Value** immediately - you won't be able to see it again! +6. Store the Client ID and Client Secret securely + +**⚠️ Security Warning:** The Client Secret is sensitive. Never share it, commit it to source control, or expose it in client-side code. + +## Step 5: Configure API Permissions (Optional) + +By default, your app has basic sign-in permissions. Additional permissions can be added if needed: + +1. In your app registration, click **"API permissions"** +2. You'll see default permissions like: + - `User.Read` (sign users in and read their profile) +3. For basic authentication, these default permissions are sufficient +4. If you need additional permissions, click **"+ Add a permission"** + +## Step 6: Add Additional Redirect URIs + +If you have multiple environments (development, staging, production): + +1. In your app registration, click **"Authentication"** +2. Under **"Platform configurations"** > **"Web"** +3. Click **"Add URI"** +4. Add URIs for each environment: + - Development: `https://localhost:5001/signin-microsoft` + - Staging: `https://staging.yourdomain.com/signin-microsoft` + - Production: `https://yourdomain.com/signin-microsoft` +5. Click **"Save"** + +## Step 7: Configure TagzApp + +### Using the Admin UI (Recommended) + +1. Log in to TagzApp as an administrator +2. Navigate to **Admin > External Authentication** +3. Find the **"Microsoft"** provider +4. Enter your credentials: + - **Client ID**: Your Application (client) ID from Azure + - **Client Secret**: Your Client Secret value + - **Enabled**: Toggle to enable the provider +5. Click **"Save Configuration"** + +### Using Configuration Files + +**appsettings.json:** +```json +{ + "Authentication": { + "Microsoft": { + "ClientID": "your-application-client-id", + "ClientSecret": "your-client-secret", + "Enabled": "true" + } + } +} +``` + +**Environment Variables:** +```bash +Authentication__Microsoft__ClientID=your-application-client-id +Authentication__Microsoft__ClientSecret=your-client-secret +Authentication__Microsoft__Enabled=true +``` + +**Azure Key Vault:** +Store with the key: +``` +TagzApp-Authentication-Microsoft +``` + +## Step 8: Test Your Configuration + +1. Log out of TagzApp (if logged in) +2. Navigate to the login page +3. You should see a **"Sign in with Microsoft"** button +4. Click the button +5. You'll be redirected to Microsoft's login page +6. Sign in with a Microsoft account +7. Grant permissions if prompted +8. You should be redirected back to TagzApp and logged in + +## Troubleshooting + +### Common Issues + +#### "Redirect URI Mismatch" Error +- **Cause**: The redirect URI in your app registration doesn't match the one TagzApp is using +- **Solution**: + - Check the exact URI TagzApp is redirecting to + - Add or correct the redirect URI in Azure Portal + - Ensure the protocol (http/https) and port match exactly + - Common format: `https://yourdomain.com/signin-microsoft` + +#### "Invalid Client Secret" Error +- **Cause**: Client Secret is incorrect or expired +- **Solution**: + - Verify you copied the entire secret value + - Check if the secret has expired in Azure Portal + - Generate a new secret if needed + - Update TagzApp configuration with the new secret + +#### "AADSTS50011: Reply URL Mismatch" Error +- **Cause**: Same as redirect URI mismatch +- **Solution**: Add the exact redirect URI to your app registration + +#### "Cannot Authenticate" Error +- **Cause**: Client ID or Client Secret is invalid +- **Solution**: + - Verify Client ID is correct (check Azure Portal) + - Verify Client Secret is correct + - Regenerate credentials if needed + - Clear browser cache and cookies + +#### "User Not Authorized" Error +- **Cause**: User's account type not supported by your app configuration +- **Solution**: + - Check your app's supported account types in Azure Portal + - Change to "Accounts in any organizational directory and personal Microsoft accounts" for broadest support + - Ensure user meets any conditional access policies + +### Account Type Issues + +#### Personal Accounts Not Working +- **Cause**: App registration only supports organizational accounts +- **Solution**: + - In Azure Portal, go to app registration > Authentication + - Change supported account types to include personal accounts + - Save changes and test again + +#### Work/School Accounts Not Working +- **Cause**: App registration only supports personal accounts +- **Solution**: + - Change supported account types to include organizational accounts + - May require admin consent for organizational accounts + +## Security Best Practices + +1. **Rotate secrets regularly**: Set expiration reminders and rotate before expiry +2. **Use shortest necessary expiration**: Balance between security and maintenance +3. **Never commit secrets**: Use environment variables or Key Vault +4. **Limit redirect URIs**: Only add URIs you actually use +5. **Monitor sign-ins**: Review Azure AD sign-in logs for suspicious activity +6. **Enable conditional access**: Add MFA or other policies if needed +7. **Use managed identity**: When running in Azure, use managed identity instead of secrets + +## Advanced Configuration + +### Custom Token Claims + +To include additional user information in tokens: + +1. In Azure Portal, go to your app registration +2. Click **"Token configuration"** +3. Click **"+ Add optional claim"** +4. Choose token type (ID, Access) and select claims +5. Common claims: + - `email` - User's email address + - `family_name`, `given_name` - User's name + - `upn` - User Principal Name + +### Conditional Access + +For additional security in enterprise scenarios: + +1. In Azure Portal, go to **Azure Active Directory** +2. Click **"Security"** > **"Conditional Access"** +3. Create policies requiring: + - Multi-factor authentication + - Compliant devices + - Specific locations + - Risk-based access + +### Multi-Tenant Configuration + +For apps supporting multiple organizations: + +1. Set account type to "Multi-tenant" +2. Tenant admin must consent for their users +3. Provide admin consent URL: +``` +https://login.microsoftonline.com/{tenant}/adminconsent?client_id={client-id} +``` + +## Monitoring and Management + +### View Sign-In Logs + +1. In Azure Portal, go to **Azure Active Directory** +2. Click **"Sign-in logs"** +3. Filter by your application name +4. Review successful and failed sign-ins +5. Investigate any suspicious activity + +### Application Usage + +1. Go to your app registration +2. Click **"Usage and insights"** (if available) +3. View authentication metrics and trends + +### Secret Expiration + +1. Set calendar reminders for secret expiration +2. Rotate secrets before they expire to avoid downtime +3. Generate new secret, update TagzApp, then delete old secret + +## Cost Considerations + +- **Azure AD Free**: Sufficient for basic OAuth (included with Azure account) +- **Azure AD Premium P1/P2**: Required for advanced features like conditional access +- **No per-authentication charges**: OAuth authentication is free + +## Compliance and Privacy + +### Data Access + +Microsoft OAuth for TagzApp accesses: +- User's name +- User's email address +- Basic profile information +- Unique identifier + +### GDPR Compliance + +- Users can revoke access at [Microsoft account settings](https://account.microsoft.com/privacy) +- Data is processed according to Microsoft's privacy policy +- TagzApp only stores necessary user information + +## Additional Resources + +- [Microsoft Identity Platform Documentation](https://docs.microsoft.com/azure/active-directory/develop/) +- [Register an App in Azure AD](https://docs.microsoft.com/azure/active-directory/develop/quickstart-register-app) +- [Microsoft Authentication Libraries (MSAL)](https://docs.microsoft.com/azure/active-directory/develop/msal-overview) +- [Azure AD Sign-In Logs](https://docs.microsoft.com/azure/active-directory/reports-monitoring/concept-sign-ins) +- [Conditional Access](https://docs.microsoft.com/azure/active-directory/conditional-access/) + +## Need Help? + +If you encounter issues not covered here: +1. Check the [TagzApp GitHub Issues](https://github.com/FritzAndFriends/TagzApp/issues) +2. Review Azure AD sign-in logs for detailed error messages +3. Consult Microsoft Identity Platform documentation +4. Open a new issue on GitHub with details about your problem diff --git a/user-docs/providers/authentication/Twitch-OAuth-Configuration.md b/user-docs/providers/authentication/Twitch-OAuth-Configuration.md new file mode 100644 index 00000000..835f41fd --- /dev/null +++ b/user-docs/providers/authentication/Twitch-OAuth-Configuration.md @@ -0,0 +1,91 @@ +# Twitch OAuth Configuration Guide + +This guide will help you configure Twitch OAuth authentication for TagzApp, allowing users to sign in with their Twitch accounts. + +## Overview + +The Twitch OAuth provider enables users to authenticate to TagzApp using their Twitch accounts. Perfect for streaming and gaming communities. + +## Prerequisites + +- A Twitch account +- Access to Twitch Developer Console + +## Quick Start + +### Step 1: Create a Twitch Application + +1. Go to [Twitch Developer Console](https://dev.twitch.tv/console) +2. Sign in with your Twitch account +3. Click **"Register Your Application"** +4. Fill in the details: + - **Name**: "TagzApp" + - **OAuth Redirect URLs**: `https://yourdomain.com/signin-twitch` + - For development: `https://localhost:5001/signin-twitch` + - **Category**: "Application Integration" +5. Click **"Create"** + +### Step 2: Get Your Credentials + +1. Click **"Manage"** on your application +2. Copy the **Client ID** +3. Click **"New Secret"** to generate a **Client Secret** +4. **Copy the Client Secret immediately** - you can't see it again! + +### Step 3: Configure TagzApp + +**Admin UI:** +1. Navigate to **Admin > External Authentication** +2. Find **"Twitch"** provider +3. Enter **Client ID** and **Client Secret** +4. Toggle **Enabled** +5. Click **"Save"** + +**Configuration File:** +```json +{ + "Authentication": { + "Twitch": { + "ClientID": "your-client-id", + "ClientSecret": "your-client-secret", + "Enabled": "true" + } + } +} +``` + +## Testing + +1. Log out of TagzApp +2. Click **"Sign in with Twitch"** +3. Authorize the application +4. You should be signed in to TagzApp + +## Troubleshooting + +### "Redirect URI Mismatch" +- Add the exact redirect URI to your Twitch app: `https://yourdomain.com/signin-twitch` + +### "Invalid Client" +- Verify Client ID and Client Secret are correct +- Regenerate secret if needed + +### "Application Suspended" +- Check for notifications in Twitch Developer Console +- Review Twitch's developer policies + +## Security Notes + +- Rotate Client Secrets periodically +- Never commit secrets to source control +- Use separate apps for dev/prod environments + +## Additional Resources + +- [Twitch Authentication Docs](https://dev.twitch.tv/docs/authentication) +- [Twitch Developer Console](https://dev.twitch.tv/console) +- [OAuth Authorization Flow](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth) + +## Need Help? + +Check the [TagzApp GitHub Issues](https://github.com/FritzAndFriends/TagzApp/issues) or consult Twitch's authentication documentation. diff --git a/user-docs/providers/content/Blazot-Configuration.md b/user-docs/providers/content/Blazot-Configuration.md new file mode 100644 index 00000000..ccee648b --- /dev/null +++ b/user-docs/providers/content/Blazot-Configuration.md @@ -0,0 +1,340 @@ +# Blazot Provider Configuration Guide + +This guide will help you configure the Blazot content provider for TagzApp to monitor posts from the Blazot social network. + +## Overview + +The Blazot provider allows TagzApp to search and display posts containing specific hashtags from Blazot (https://blazot.com), a social networking platform. Blazot is designed for developers and technology enthusiasts. + +## Prerequisites + +- A Blazot user account +- API Key and Secret Auth Key from Blazot +- Understanding of Blazot's account types (User vs Site) + +## Understanding Blazot Account Types + +Blazot has two types of accounts: + +### User Accounts +- Personal accounts for individuals +- Can create posts and interact with content +- API keys are available in user settings +- **Create this first!** + +### Site Accounts +- Organizational accounts (like company pages) +- Created after logging in with your user account +- Have separate API keys +- Can represent brands, projects, or organizations + +**⚠️ Important:** Create a **user account** first, not a Site account. If you want to represent a company, create your personal user account first, then create a Site within that account. If you use the desired company username as a user, it won't be available as a Site later. + +## Step 1: Create a Blazot Account + +1. Go to [https://blazot.com](https://blazot.com) +2. Click **"Sign Up"** or **"Register"** +3. Fill in your personal information: + - Username (your personal username, not your company name) + - Email address + - Password +4. Verify your email address if required +5. Complete your profile setup + +## Step 2: Create a Site (Optional) + +If you want to represent an organization or company: + +1. Log in to Blazot with your personal user account +2. Click on your profile menu (top right) +3. Select **"Create Site"** or navigate to Site management +4. Fill in the site information: + - Site name/username (e.g., your company name) + - Description + - Site type/category +5. Complete the site setup +6. You can now manage the site from your user account + +## Step 3: Get Your API Credentials + +### For User Account + +1. Log in to [https://blazot.com](https://blazot.com) +2. Click on your profile picture or menu (top right) +3. Select **"Configuration"** or **"Settings"** +4. Navigate to the **"API"** or **"Developer"** section +5. You'll see: + - **API Key**: Your public API key + - **Secret Auth Key**: Your private authentication key +6. Copy both keys and store them securely + +### For Site Account + +1. Log in to Blazot with your user account +2. Switch to your Site context (if you have multiple) +3. Navigate to the Site's **"Configuration"** page +4. Go to the **"API"** section +5. Copy the **API Key** and **Secret Auth Key** for the Site +6. Store them securely + +**⚠️ Security Note:** The Secret Auth Key is sensitive. Never share it or commit it to source control. It's used only to obtain access tokens. + +## Step 4: Understand Blazot API Access + +### API Key Types + +- **API Key**: Public identifier for your application +- **Secret Auth Key**: Private key used to authenticate and get access tokens +- **Access Token**: Temporary token used for API requests (managed by TagzApp) + +### How Authentication Works + +1. TagzApp uses your API Key and Secret Auth Key +2. Requests an access token from Blazot +3. Uses the access token for all API requests +4. Automatically renews the token when it expires + +**You only need to provide the API Key and Secret Auth Key** - TagzApp handles token management. + +## Step 5: Configure TagzApp + +### Option A: Using the Admin UI (Recommended) + +1. Log in to TagzApp as an administrator +2. Navigate to **Admin > Providers** +3. Find the **"Blazot"** provider +4. Click **"Configure"** +5. Enter your credentials: + - **API Key**: Your Blazot API Key + - **Secret Auth Key**: Your Blazot Secret Auth Key + - **Window Seconds**: Rate limit window duration (default: 300 seconds / 5 minutes) + - **Window Requests**: Number of requests allowed per window (default: 5) + - **Enabled**: Toggle to enable the provider +6. Click **"Save Configuration"** +7. The provider will authenticate and start monitoring + +### Option B: Using Configuration Files + +If you prefer to configure via files or environment variables: + +**appsettings.json:** +```json +{ + "Blazot": { + "Enabled": true, + "ApiKey": "your-api-key", + "SecretAuthKey": "your-secret-auth-key", + "BaseAddress": "https://blazot.com", + "WindowSeconds": 300, + "WindowRequests": 5, + "Timeout": "00:00:30", + "UseHttp2": true + } +} +``` + +**Environment Variables:** +```bash +Blazot__Enabled=true +Blazot__ApiKey=your-api-key +Blazot__SecretAuthKey=your-secret-auth-key +Blazot__WindowSeconds=300 +Blazot__WindowRequests=5 +``` + +**Azure Key Vault:** +If using Azure Key Vault, store the configuration with the key: +``` +TagzApp-Blazot +``` + +## Step 6: Test Your Configuration + +1. In TagzApp, configure a hashtag to monitor (e.g., `#blazot`) +2. Post on Blazot with that hashtag +3. Check if the post appears in TagzApp (may take 30-60 seconds) +4. If posts don't appear, check the logs for errors + +## Rate Limits and Quotas + +### Default Rate Limits + +- **Free users**: 5 requests per 15-minute window +- **With subscription**: Higher limits (check Blazot subscription details) +- **Rate limits will increase** as the platform grows + +### Understanding Rate Limits + +TagzApp automatically manages rate limits: +- Tracks request counts per time window +- Pauses when limits are reached +- Resumes after the window resets +- Logs rate limit events + +**For most use cases, 5 requests per 15 minutes is sufficient** since TagzApp caches results and doesn't need to poll frequently. + +### Optimizing for Rate Limits + +1. **Increase polling interval**: Check every 3+ minutes instead of every minute +2. **Monitor fewer hashtags**: Focus on key hashtags +3. **Consider subscription**: If you need higher limits +4. **Use caching**: TagzApp caches results to reduce API calls + +## Regenerating API Keys + +If your keys are compromised or you need to rotate them: + +1. Log in to Blazot +2. Go to Configuration > API +3. Click **"Regenerate Keys"** or **"Reset Keys"** +4. Copy the new API Key and Secret Auth Key +5. Update your TagzApp configuration immediately +6. Old keys will stop working + +## Troubleshooting + +### Common Issues + +#### "Authentication Failed" Error +- **Cause**: Invalid API Key or Secret Auth Key +- **Solution**: + - Verify you copied the keys correctly + - Ensure there are no extra spaces or characters + - Regenerate keys in Blazot if needed + - Update TagzApp configuration + +#### "Rate Limited" Error +- **Cause**: Exceeded your rate limit quota +- **Solution**: + - Wait for the rate limit window to reset (15 minutes) + - Reduce polling frequency in TagzApp + - Consider upgrading your Blazot account + - Check if multiple TagzApp instances are using the same keys + +#### No Posts Appearing +- **Cause**: Various reasons +- **Solution**: + - Verify the hashtag has recent posts on Blazot + - Check if the provider is enabled in TagzApp + - Verify API credentials are correct + - Check TagzApp logs for errors + - Ensure you're not rate limited + +#### "Invalid Response" Error +- **Cause**: API response format unexpected +- **Solution**: + - Check if TagzApp is up to date + - Blazot API may have changed (check for updates) + - Report the issue on GitHub with log details + +#### "Connection Refused" Error +- **Cause**: Cannot connect to Blazot servers +- **Solution**: + - Check your internet connection + - Verify Blazot is operational (visit blazot.com) + - Check firewall settings + - Verify the BaseAddress is correct + +## Advanced Configuration + +### Custom Base Address + +If Blazot changes domains or you're using a development instance: + +```json +{ + "Blazot": { + "BaseAddress": "https://api.blazot.com" + } +} +``` + +### Timeout Configuration + +For slower connections or rate limiting: + +```json +{ + "Blazot": { + "Timeout": "00:01:00" + } +} +``` + +### HTTP/2 Support + +Blazot supports HTTP/2 for better performance: + +```json +{ + "Blazot": { + "UseHttp2": true + } +} +``` + +## Security Best Practices + +1. **Never commit API keys to source control** +2. **Use environment variables or Key Vault** for production +3. **Rotate keys periodically** (every 3-6 months) +4. **Regenerate keys if compromised** immediately +5. **Monitor API usage** for unusual activity +6. **Use separate keys for development and production** +7. **Limit key access** to only necessary team members + +## Blazot API Features + +### Current Support + +- Hashtag search +- Post retrieval +- User information +- Real-time monitoring + +### Future Enhancements + +Potential future features: +- Post creation from TagzApp +- User mentions monitoring +- Direct message integration +- Analytics and insights + +## Comparing Blazot to Other Providers + +| Feature | Blazot | Twitter/X | Mastodon | +|---------|--------|-----------|----------| +| Setup Complexity | Easy | Moderate | Easy | +| API Keys Required | Yes | Yes | No | +| Rate Limits | 5/15min (free) | Strict | Per instance | +| Cost | Free (subscriptions available) | Free/Paid tiers | Free | +| Target Audience | Developers/Tech | General | General | + +### When to Use Blazot Provider + +- Your audience is on Blazot +- Tech/developer focused events +- Want to support developer-friendly platforms +- Need straightforward API setup + +## Additional Resources + +- [Blazot Official Site](https://blazot.com) +- [Blazot API Documentation](https://developers.blazot.com/docs/api/v1) +- [Blazot Support](https://blazot.com/support) +- [TagzApp Blazot Provider README](https://github.com/FritzAndFriends/TagzApp/blob/main/src/TagzApp.Providers.Blazot/ReadMe.md) + +## Community and Support + +- **Blazot Community**: Join discussions on Blazot itself +- **Developer Forum**: Check Blazot's developer resources +- **TagzApp Issues**: Report integration issues on GitHub + +## Need Help? + +If you encounter issues not covered here: +1. Check the [TagzApp GitHub Issues](https://github.com/FritzAndFriends/TagzApp/issues) +2. Review the application logs for detailed error messages +3. Consult [Blazot API Documentation](https://developers.blazot.com/docs/api/v1) +4. Check Blazot's status and announcements +5. Open a new issue on GitHub with details about your problem diff --git a/user-docs/providers/content/Bluesky-Configuration.md b/user-docs/providers/content/Bluesky-Configuration.md new file mode 100644 index 00000000..d690429d --- /dev/null +++ b/user-docs/providers/content/Bluesky-Configuration.md @@ -0,0 +1,258 @@ +# Bluesky Provider Configuration Guide + +This guide will help you configure the Bluesky content provider for TagzApp to monitor hashtags on the Bluesky social network powered by the AT Protocol. + +## Overview + +The Bluesky provider allows TagzApp to search and display posts containing specific hashtags from the Bluesky social network. Bluesky uses the AT Protocol, a decentralized social networking protocol. + +## Prerequisites + +- A Bluesky account is **not required** for basic hashtag monitoring +- Bluesky's public API allows reading posts without authentication +- Understanding of Bluesky's decentralized architecture (optional but helpful) + +## Understanding Bluesky + +Bluesky is built on the AT Protocol (Authenticated Transfer Protocol): +- **Decentralized**: Data is distributed across multiple servers (PDSs - Personal Data Servers) +- **Public by default**: Most posts are publicly accessible +- **No API keys needed**: Public search doesn't require authentication +- **Open protocol**: Anyone can build clients and tools + +## Step 1: Understanding Bluesky's Public API + +Bluesky's public API allows you to: +- Search for posts by hashtag +- Read public posts without authentication +- Access user profiles and feeds +- Monitor real-time content + +**Important:** For basic hashtag monitoring with TagzApp, you don't need any credentials or setup on Bluesky itself! + +## Step 2: Configure TagzApp + +### Option A: Using the Admin UI (Recommended) + +1. Log in to TagzApp as an administrator +2. Navigate to **Admin > Providers** +3. Find the **"Bluesky"** provider +4. Click **"Configure"** +5. Toggle **"Enabled"** to enable the provider +6. Click **"Save Configuration"** +7. The provider will start monitoring hashtags you configure + +That's it! No API keys or credentials needed. + +### Option B: Using Configuration Files + +If you prefer to configure via files or environment variables: + +**appsettings.json:** +```json +{ + "providers": { + "bluesky": { + "Enabled": true + } + } +} +``` + +**Environment Variables:** +```bash +providers__bluesky__Enabled=true +``` + +**Azure Key Vault:** +If using Azure Key Vault, store the configuration with the key: +``` +TagzApp-providers-bluesky +``` + +## Step 3: Test Your Configuration + +1. In TagzApp, configure a hashtag to monitor (e.g., `#bluesky`) +2. Post on Bluesky with that hashtag, or wait for others to post +3. Check if posts appear in TagzApp (may take 30-60 seconds due to API polling) +4. If posts don't appear, check the logs for errors + +## How Hashtags Work in Bluesky + +### Hashtag Format + +Bluesky supports hashtags similar to other platforms: +- Format: `#hashtag` or `#MultiWordHashtag` +- Case-insensitive: `#TagzApp` matches `#tagzapp` +- Can include numbers: `#dotnet9` +- Unicode supported: `#社交媒体` + +### Hashtag Discovery + +Posts with hashtags on Bluesky are: +- Indexed automatically +- Searchable across the network +- Visible to all users (if public) +- Federated across Personal Data Servers + +## Advanced Topics + +### Understanding the AT Protocol + +The AT Protocol provides: +- **Decentralized identity**: Users own their identity +- **Repository-based**: Content stored in signed repositories +- **Federated**: Data distributed across multiple servers +- **Interoperable**: Multiple clients can access the same data + +### App Passwords (Future Feature) + +While not currently required for TagzApp's public monitoring, Bluesky supports app-specific passwords for authenticated operations: +- Used for posting or advanced API features +- Generated in Bluesky Settings > App Passwords +- More secure than using your main password +- Can be revoked individually + +**Note:** TagzApp currently only reads public posts and doesn't require authentication. + +### Future Authentication Support + +If you need authenticated features in the future (like posting or accessing private content): + +1. Log in to [Bluesky](https://bsky.app) +2. Go to **Settings > App Passwords** +3. Click **"Add App Password"** +4. Enter a name (e.g., "TagzApp") +5. Copy the generated password +6. Store it securely for future use + +## Troubleshooting + +### Common Issues + +#### "Connection Error" or "Cannot Connect" +- **Cause**: Network issues or Bluesky API unavailable +- **Solution**: + - Check your internet connection + - Verify Bluesky services are operational at [status.bsky.app](https://status.bsky.app) + - Wait a few minutes and try again + +#### No Posts Appearing +- **Cause**: Various reasons +- **Solution**: + - Verify the hashtag has recent posts on Bluesky + - Check if the provider is enabled in TagzApp + - Check TagzApp logs for error messages + - Ensure posts with the hashtag are public + - Try a more popular hashtag (e.g., `#bluesky`) + +#### "Rate Limited" Messages +- **Cause**: Too many API requests in a short time +- **Solution**: + - TagzApp will automatically back off and retry + - Wait a few minutes for rate limits to reset + - Consider reducing polling frequency if it happens frequently + +#### "Invalid Response" Errors +- **Cause**: API response format changed or unexpected data +- **Solution**: + - Check if TagzApp is up to date + - Report the issue on GitHub with log details + - Bluesky's API may have changed (check for updates) + +## Rate Limits + +Bluesky has rate limiting on public API access: + +- **Public endpoints**: Generous limits for read operations +- **Unauthenticated**: Lower limits than authenticated requests +- **Auto-recovery**: TagzApp handles rate limits automatically + +Best practices: +- Don't monitor too many hashtags simultaneously +- Use reasonable polling intervals (30-60 seconds) +- TagzApp respects rate limits and backs off automatically + +## Performance Considerations + +### Response Times + +Bluesky's decentralized architecture means: +- Posts may take a few seconds to be indexed +- Search results are eventually consistent +- Some delays in cross-server federation + +### Data Freshness + +- New posts may take 30-60 seconds to appear in search +- Very high-volume hashtags may have paged results +- TagzApp polls regularly to catch new posts + +## Privacy and Security + +### What Data is Accessed? + +TagzApp's Bluesky provider only accesses: +- Public posts with matching hashtags +- Public profile information (username, display name) +- Post metadata (timestamp, likes, reposts) + +### What is NOT Accessed? + +- Private or followers-only posts +- Direct messages +- Account credentials +- Personal information beyond public profiles + +### Security Best Practices + +1. **No credentials needed** - Public monitoring requires no authentication +2. **Respect user privacy** - Only public posts are monitored +3. **Follow terms of service** - Comply with Bluesky's acceptable use policies +4. **Don't abuse the API** - Use reasonable polling rates + +## Bluesky vs Twitter/Mastodon + +### Comparison + +| Feature | Bluesky | Twitter/X | Mastodon | +|---------|---------|-----------|----------| +| API Keys Required | No (for public) | Yes | No (for public) | +| Decentralized | Yes (AT Protocol) | No | Yes (ActivityPub) | +| Rate Limits | Moderate | Strict (paid tiers) | Per instance | +| Setup Complexity | Very Easy | Moderate | Easy | +| Hashtag Search | Built-in | Built-in | Built-in | + +### When to Use Bluesky Provider + +- Your audience is active on Bluesky +- You want decentralized social monitoring +- You need easy setup without API credentials +- You're exploring alternative social platforms + +## Additional Resources + +- [Bluesky Official Site](https://bsky.app) +- [AT Protocol Documentation](https://atproto.com) +- [Bluesky API Docs](https://docs.bsky.app) +- [AT Protocol Specifications](https://atproto.com/specs/atp) +- [Bluesky Status Page](https://status.bsky.app) +- [Bluesky Community](https://bsky.app/profile/bsky.app) + +## Future Enhancements + +Potential future features for the Bluesky provider: +- Authenticated access for posting +- Following specific accounts +- Custom feed integration +- Reply threading support +- Embed support (images, videos, links) + +## Need Help? + +If you encounter issues not covered here: +1. Check the [TagzApp GitHub Issues](https://github.com/FritzAndFriends/TagzApp/issues) +2. Review the application logs for detailed error messages +3. Check [Bluesky Status](https://status.bsky.app) for service issues +4. Consult the AT Protocol documentation +5. Open a new issue on GitHub with details about your problem diff --git a/user-docs/providers/content/Mastodon-Configuration.md b/user-docs/providers/content/Mastodon-Configuration.md new file mode 100644 index 00000000..6ae74a08 --- /dev/null +++ b/user-docs/providers/content/Mastodon-Configuration.md @@ -0,0 +1,234 @@ +# Mastodon Provider Configuration Guide + +This guide will help you configure the Mastodon content provider for TagzApp to monitor hashtags across the Mastodon federated social network. + +## Overview + +The Mastodon provider allows TagzApp to search and display posts (toots) containing specific hashtags from Mastodon instances. Mastodon is a federated social network, meaning it consists of many independent servers (instances) that communicate with each other. + +## Prerequisites + +- A Mastodon account (optional, but recommended) +- Access to a Mastodon instance's public API (most instances allow public read access) +- No API keys required for public hashtag search! + +## Understanding Mastodon Federation + +Mastodon is federated, meaning: +- There are many independent Mastodon servers (instances) +- Each instance has its own domain (e.g., mastodon.social, fosstodon.org, etc.) +- Instances communicate with each other to share content +- You can search hashtags on any public instance + +**Note:** By default, TagzApp searches `mastodon.social`, but you can configure it to search any public Mastodon instance. + +## Step 1: Choose a Mastodon Instance + +You need to decide which Mastodon instance to search: + +### Popular Public Instances + +- **mastodon.social** - The flagship instance (default in TagzApp) +- **fosstodon.org** - Technology and open-source focused +- **mas.to** - General purpose +- **techhub.social** - Technology focused +- **mastodon.online** - General purpose + +### Finding Instances + +- Browse instances at [joinmastodon.org/servers](https://joinmastodon.org/servers) +- Consider instances relevant to your event's topic +- Choose larger instances for broader hashtag coverage +- Verify the instance has public API access enabled + +## Step 2: Verify Instance API Access + +Most Mastodon instances allow public API access for searching hashtags without authentication: + +1. Visit your chosen instance in a web browser (e.g., https://mastodon.social) +2. Navigate to the instance's API documentation: `https://[instance-domain]/api/v1/` +3. Check if you can access the API without authentication +4. Look for the hashtag search endpoint: `/api/v1/timelines/tag/:hashtag` + +**Note:** Some private or restricted instances may require authentication. For TagzApp, choose instances with public API access. + +## Step 3: Configure TagzApp + +### Option A: Using the Admin UI (Recommended) + +1. Log in to TagzApp as an administrator +2. Navigate to **Admin > Providers** +3. Find the **"Mastodon"** provider +4. Click **"Configure"** +5. Enter your configuration: + - **Base Address**: The URL of the Mastodon instance (e.g., `https://mastodon.social`) + - **Enabled**: Toggle to enable the provider +6. Click **"Save Configuration"** +7. The provider will start monitoring hashtags you configure + +### Option B: Using Configuration Files + +If you prefer to configure via files or environment variables: + +**appsettings.json:** +```json +{ + "provider-mastodon": { + "Enabled": true, + "BaseAddress": "https://mastodon.social", + "Timeout": "00:00:30", + "UseHttp2": true + } +} +``` + +**Environment Variables:** +```bash +provider__mastodon__Enabled=true +provider__mastodon__BaseAddress=https://mastodon.social +``` + +**Azure Key Vault:** +If using Azure Key Vault, store the configuration with the key: +``` +TagzApp-provider-mastodon +``` + +## Step 4: Test Your Configuration + +1. In TagzApp, configure a hashtag to monitor (e.g., `#fediverse`) +2. Post a toot with that hashtag on Mastodon (or wait for someone else to) +3. Check if the toot appears in TagzApp (may take 30-60 seconds due to API polling) +4. If posts don't appear, check the logs for errors + +## Advanced Configuration + +### Monitoring Multiple Instances + +To monitor multiple Mastodon instances simultaneously: + +1. Run multiple instances of the Mastodon provider with different configurations +2. Configure each with a different base address +3. Each will independently monitor the same hashtags on different instances + +**Note:** This requires advanced configuration and may require code changes to support multiple provider instances. + +### Custom Timeout Settings + +If you experience timeout issues: + +```json +{ + "provider-mastodon": { + "Timeout": "00:01:00" + } +} +``` + +### HTTP/2 Configuration + +Most modern Mastodon instances support HTTP/2: + +```json +{ + "provider-mastodon": { + "UseHttp2": true + } +} +``` + +## Troubleshooting + +### Common Issues + +#### "Connection Refused" or "Cannot Connect" Error +- **Cause**: Invalid instance URL or instance is down +- **Solution**: + - Verify the instance URL is correct (include `https://`) + - Check if the instance is operational by visiting it in a browser + - Try a different instance (e.g., mastodon.social) + +#### "404 Not Found" Error +- **Cause**: API endpoint not available or instance API structure is different +- **Solution**: + - Verify the instance is running standard Mastodon API + - Some forks (Pleroma, Akkoma) may have slightly different APIs + - Try using a mainstream Mastodon instance + +#### No Toots Appearing +- **Cause**: Various reasons +- **Solution**: + - Verify the hashtag exists and has recent posts on that instance + - Check if the provider is enabled in TagzApp + - Verify the instance allows public API access + - Check TagzApp logs for error messages + - Try a more popular instance (e.g., mastodon.social) + +#### "429 Too Many Requests" Error +- **Cause**: Exceeded instance rate limits +- **Solution**: + - Wait for the rate limit window to reset (typically 5 minutes) + - Reduce polling frequency in TagzApp + - Consider using a different instance + - Contact the instance administrators about rate limits + +#### "403 Forbidden" Error +- **Cause**: Instance requires authentication or blocks your IP +- **Solution**: + - Switch to an instance that allows public access + - Check if the instance has IP restrictions + - Contact instance administrators if needed + +## Rate Limits + +Mastodon instances have their own rate limiting policies: + +- **Default Mastodon**: 300 requests per 5 minutes per IP +- **Custom instances**: May have different limits +- **Public endpoints**: Generally more restrictive than authenticated endpoints + +TagzApp automatically handles rate limiting and will pause requests when limits are reached. + +## Federation Considerations + +### What Posts Will You See? + +When monitoring a hashtag on a Mastodon instance, you'll see: +- Posts from local users (on that instance) +- Posts from remote users that are federated to that instance +- Posts that the instance is aware of through follows and boosts + +You **won't** see: +- Posts from instances that aren't federated with your chosen instance +- Posts from instances that are blocked or defederated +- Posts from very small instances with limited federation + +### Best Practices for Hashtag Monitoring + +1. **Use larger, well-connected instances** (mastodon.social, fosstodon.org) for broader coverage +2. **Choose topic-specific instances** if your event has a specific theme +3. **Consider monitoring multiple instances** if you need comprehensive coverage +4. **Ask users to tag your instance** in posts for better visibility + +## Security Considerations + +1. **No credentials required** - The Mastodon provider uses public APIs +2. **Respect instance rules** - Follow the instance's terms of service +3. **Don't abuse rate limits** - Configure reasonable polling intervals +4. **Be a good federation citizen** - Don't overload small instances + +## Additional Resources + +- [Mastodon Official Documentation](https://docs.joinmastodon.org/) +- [Mastodon API Documentation](https://docs.joinmastodon.org/api/) +- [List of Mastodon Instances](https://joinmastodon.org/servers) +- [Mastodon Apps and Tools](https://joinmastodon.org/apps) +- [Understanding Federation](https://docs.joinmastodon.org/user/network/) + +## Need Help? + +If you encounter issues not covered here: +1. Check the [TagzApp GitHub Issues](https://github.com/FritzAndFriends/TagzApp/issues) +2. Review the application logs for detailed error messages +3. Consult the Mastodon instance's documentation or support channels +4. Open a new issue on GitHub with details about your problem diff --git a/user-docs/providers/content/TwitchChat-Configuration.md b/user-docs/providers/content/TwitchChat-Configuration.md new file mode 100644 index 00000000..ff1fd115 --- /dev/null +++ b/user-docs/providers/content/TwitchChat-Configuration.md @@ -0,0 +1,294 @@ +# Twitch Chat Provider Configuration Guide + +This guide will help you configure the Twitch Chat content provider for TagzApp to monitor chat messages from Twitch streams in real-time. + +## Overview + +The Twitch Chat provider allows TagzApp to connect to a Twitch channel's chat and display messages containing specific hashtags or keywords. This is perfect for live streaming events where you want to display viewer interactions. + +## Prerequisites + +- A Twitch account (can be a separate bot account) +- A Twitch application registered in the Twitch Developer Console +- The Twitch channel name you want to monitor +- Basic understanding of Twitch chat and IRC + +## Step 1: Create a Twitch Developer Application + +1. Go to the [Twitch Developer Console](https://dev.twitch.tv/console) +2. Sign in with your Twitch account +3. Click **"Register Your Application"** or **"Applications"** > **"Register"** +4. Fill out the application form: + - **Name**: Enter a name (e.g., "TagzApp Bot") + - **OAuth Redirect URLs**: Add `https://localhost` (or your TagzApp domain) + - **Category**: Select "Application Integration" or "Chat Bot" +5. Complete the CAPTCHA and click **"Create"** + +## Step 2: Get Your Client ID and Client Secret + +After creating your application: + +1. Click **"Manage"** on your application in the Developer Console +2. You'll see your **Client ID** - copy this +3. Click **"New Secret"** to generate a **Client Secret** +4. **Important:** Copy the Client Secret immediately! You won't be able to see it again +5. Store both values securely + +## Step 3: Create a Chat Bot Account (Recommended) + +For best practices, create a separate Twitch account for your bot: + +1. Create a new Twitch account (e.g., "YourEventBot") +2. Set up a profile picture and description +3. This account will appear in chat as the bot monitoring messages + +**Why use a bot account?** +- Keeps your personal account separate +- Makes it clear a bot is monitoring chat +- Easier to manage permissions and OAuth tokens + +## Step 4: Generate an OAuth Token + +You need an OAuth token for the bot account to access chat: + +### Method A: Using Twitch Token Generator (Easiest) + +1. Go to [Twitch Token Generator](https://twitchtokengenerator.com/) +2. Log in with your **bot account** (not your main account) +3. Select scopes: + - `chat:read` - Read chat messages + - `chat:edit` - Send chat messages (optional) +4. Click **"Generate Token"** +5. Copy the **OAuth Token** (starts with `oauth:`) +6. Store it securely + +### Method B: Using Twitch CLI + +1. Install the [Twitch CLI](https://dev.twitch.tv/docs/cli) +2. Run: `twitch token` +3. Follow the authentication flow +4. Copy the OAuth token + +### Method C: Manual OAuth Flow + +1. Use this URL (replace `YOUR_CLIENT_ID` and `YOUR_REDIRECT_URI`): +``` +https://id.twitch.tv/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=chat:read%20chat:edit +``` +2. Authorize the application +3. Exchange the authorization code for an access token using the Twitch API +4. Prepend `oauth:` to the token + +## Step 5: Configure TagzApp + +### Option A: Using the Admin UI (Recommended) + +1. Log in to TagzApp as an administrator +2. Navigate to **Admin > Providers** +3. Find the **"TwitchChat"** provider +4. Click **"Configure"** +5. Enter your credentials: + - **Client ID**: Your Twitch application Client ID + - **Client Secret**: Your Twitch application Client Secret + - **Chat Bot Name**: Your bot account's Twitch username (e.g., "youreventbot") + - **OAuth Token**: The OAuth token for your bot account (include `oauth:` prefix) + - **Channel Name**: The Twitch channel to monitor (without the `#`, e.g., "csharpfritz") + - **Enabled**: Toggle to enable the provider +6. Click **"Save Configuration"** +7. The provider will connect to Twitch chat and start monitoring + +### Option B: Using Configuration Files + +If you prefer to configure via files or environment variables: + +**appsettings.json:** +```json +{ + "provider-twitch": { + "Enabled": true, + "ClientId": "your-client-id", + "ClientSecret": "your-client-secret", + "ChatBotName": "youreventbot", + "OAuthToken": "oauth:your-oauth-token", + "ChannelName": "csharpfritz" + } +} +``` + +**Environment Variables:** +```bash +provider__twitch__Enabled=true +provider__twitch__ClientId=your-client-id +provider__twitch__ClientSecret=your-client-secret +provider__twitch__ChatBotName=youreventbot +provider__twitch__OAuthToken=oauth:your-oauth-token +provider__twitch__ChannelName=csharpfritz +``` + +**Azure Key Vault:** +If using Azure Key Vault, store the configuration with the key: +``` +TagzApp-provider-twitch +``` + +## Step 6: Test Your Configuration + +1. Start TagzApp and verify the Twitch provider connects successfully +2. Go to the Twitch channel you're monitoring +3. Send a test message in chat with your configured hashtag +4. The message should appear in TagzApp within a few seconds +5. Check the logs if messages don't appear + +## Understanding Twitch Chat Integration + +### How It Works + +The Twitch Chat provider: +1. Connects to Twitch IRC servers +2. Joins the specified channel's chat +3. Listens for all messages in real-time +4. Filters messages based on your hashtag configuration +5. Displays matching messages in TagzApp + +### Message Processing + +- **Real-time**: Messages appear instantly (no polling delay) +- **Filtering**: Only messages with configured hashtags/keywords are shown +- **Metadata**: Includes username, timestamp, and badges +- **Emotes**: Twitch emotes are captured but displayed as text codes + +## Troubleshooting + +### Common Issues + +#### "Authentication Failed" Error +- **Cause**: Invalid OAuth token or wrong bot account +- **Solution**: + - Regenerate the OAuth token + - Ensure the token is for the correct bot account + - Verify the token includes `oauth:` prefix + - Check that the token has necessary scopes + +#### "Unable to Connect" Error +- **Cause**: Network issues or invalid credentials +- **Solution**: + - Verify your internet connection + - Check that Twitch IRC is operational + - Verify all credentials are correct + - Check firewall settings (allow IRC connections) + +#### No Messages Appearing +- **Cause**: Various reasons +- **Solution**: + - Verify the channel name is correct (no `#` prefix) + - Check if the provider is enabled + - Ensure hashtag configuration matches messages + - Verify the bot has joined the channel (check Twitch chat user list) + - Check TagzApp logs for errors + +#### "Rate Limited" or "Message Throttled" +- **Cause**: Sending too many messages too quickly +- **Solution**: + - This shouldn't affect reading messages + - If posting replies, slow down the rate + - Twitch limits: 20 messages per 30 seconds for non-moderators + +#### Bot Not Appearing in Chat +- **Cause**: Connection issue or authentication problem +- **Solution**: + - Check the OAuth token is valid + - Verify the bot account is not banned from the channel + - Restart TagzApp to reconnect + - Check if the channel exists and is live + +#### "Invalid OAuth Token" Error +- **Cause**: Token expired or revoked +- **Solution**: + - OAuth tokens don't expire unless revoked + - Regenerate the token in the Developer Console + - Update the configuration with the new token + +## Advanced Configuration + +### Monitoring Multiple Channels + +To monitor multiple Twitch channels: +1. Deploy multiple TagzApp instances, each configured for a different channel +2. Or modify the configuration to support multiple channels (requires code changes) + +### Bot Commands (Future Feature) + +The Twitch provider can potentially support: +- Responding to commands in chat +- Posting messages to chat +- Moderator actions + +### Custom Badge Support + +Twitch chat includes badges (subscriber, moderator, VIP, etc.): +- TagzApp captures badge information +- Can be used for filtering or display customization +- Check the Twitch API documentation for badge details + +## Rate Limits and Performance + +### Twitch IRC Limits + +- **Read messages**: No limit (can read all messages) +- **Send messages**: + - Non-moderators: 20 messages per 30 seconds + - Moderators: 100 messages per 30 seconds +- **Join channels**: Up to 50 channels per connection + +### Performance Tips + +- Single channel monitoring has no performance issues +- Real-time connection is more efficient than polling +- Messages are processed as they arrive +- No delay compared to other providers + +## Security Best Practices + +1. **Use a dedicated bot account** - Don't use your personal account +2. **Secure OAuth tokens** - Never commit tokens to source control +3. **Rotate credentials** - Regenerate tokens periodically +4. **Limit scopes** - Only request necessary permissions +5. **Monitor usage** - Watch for unusual activity +6. **Revoke tokens** - Revoke tokens if compromised + +## Integration with Twitch Features + +### Channel Points + +TagzApp can potentially integrate with: +- Channel point redemptions +- Custom rewards triggering messages + +### Subscriber-Only Chat + +- Works with any chat mode (sub-only, followers-only, etc.) +- Bot must meet the requirements to read messages + +### Emotes + +- Twitch emotes are captured +- Displayed as text codes (e.g., `:Kappa:`) +- Future enhancement: Render emote images + +## Additional Resources + +- [Twitch Developer Documentation](https://dev.twitch.tv/docs/) +- [Twitch IRC Guide](https://dev.twitch.tv/docs/irc/) +- [Twitch API Reference](https://dev.twitch.tv/docs/api/) +- [Twitch Authentication Guide](https://dev.twitch.tv/docs/authentication/) +- [Twitch Chat Badges](https://dev.twitch.tv/docs/irc/tags/#privmsg-tags) +- [Twitch Token Generator](https://twitchtokengenerator.com/) + +## Need Help? + +If you encounter issues not covered here: +1. Check the [TagzApp GitHub Issues](https://github.com/FritzAndFriends/TagzApp/issues) +2. Review the application logs for detailed error messages +3. Consult the Twitch Developer documentation +4. Test your credentials with other Twitch IRC tools +5. Open a new issue on GitHub with details about your problem diff --git a/user-docs/providers/content/Twitter-Configuration.md b/user-docs/providers/content/Twitter-Configuration.md new file mode 100644 index 00000000..956bf279 --- /dev/null +++ b/user-docs/providers/content/Twitter-Configuration.md @@ -0,0 +1,179 @@ +# Twitter/X Provider Configuration Guide + +This guide will help you configure the Twitter/X (formerly Twitter) content provider for TagzApp to monitor hashtags and display tweets in real-time. + +## Overview + +The Twitter/X provider allows TagzApp to search and display tweets containing specific hashtags. You'll need a Twitter/X Developer account and API credentials to use this provider. + +## Prerequisites + +- A Twitter/X account +- Access to the Twitter/X Developer Portal +- A Twitter/X app with appropriate API access level + +## Step 1: Create a Twitter/X Developer Account + +1. Go to the [Twitter Developer Portal](https://developer.twitter.com/en/portal/dashboard) +2. Sign in with your Twitter/X account +3. If you don't have a developer account yet, click **"Sign up"** or **"Apply for a developer account"** +4. Fill out the application form: + - Select your use case (typically "Building tools for Twitter users") + - Provide a description of how you'll use the API + - Accept the Terms of Service +5. Wait for approval (this can take a few minutes to a few hours) + +## Step 2: Create a Twitter/X App + +1. Once approved, go to the [Developer Portal Dashboard](https://developer.twitter.com/en/portal/dashboard) +2. Click **"+ Create Project"** (if you don't have one already) + - Enter a project name (e.g., "TagzApp") + - Select a use case (e.g., "Explore the API") + - Provide a project description +3. Click **"+ Add App"** or **"Create App"** + - Enter an app name (e.g., "TagzApp Monitor") + - The app will be created and you'll see the API keys + +## Step 3: Get Your API Credentials + +After creating your app, you'll need to obtain a Bearer Token: + +1. In your app's dashboard, go to the **"Keys and tokens"** tab +2. Under **"Authentication Tokens"**, find **"Bearer Token"** +3. Click **"Generate"** if you haven't already +4. **Important:** Copy the Bearer Token immediately and store it securely. You won't be able to see it again! +5. If you lose the token, you can regenerate it (but the old token will stop working) + +### API Access Levels + +Twitter/X offers different API access levels: +- **Free tier**: Limited to 500,000 tweets/month +- **Basic tier**: $100/month, includes more features +- **Pro tier**: $5,000/month, includes advanced features +- **Enterprise**: Custom pricing + +For basic hashtag monitoring with TagzApp, the **Free tier** is usually sufficient for small to medium events. + +## Step 4: Configure TagzApp + +### Option A: Using the Admin UI (Recommended) + +1. Log in to TagzApp as an administrator +2. Navigate to **Admin > Providers** +3. Find the **"X (formerly Twitter)"** provider +4. Click **"Configure"** +5. Enter your credentials: + - **Bearer Token**: Paste the Bearer Token you copied earlier + - **Enabled**: Toggle to enable the provider +6. Click **"Save Configuration"** +7. The provider will start monitoring hashtags you configure + +### Option B: Using Configuration Files + +If you prefer to configure via files or environment variables: + +**appsettings.json:** +```json +{ + "providers": { + "twitter": { + "Enabled": true, + "BearerToken": "your-bearer-token-here", + "BaseAddress": "https://api.twitter.com", + "Timeout": "00:00:30" + } + } +} +``` + +**Environment Variables:** +```bash +providers__twitter__Enabled=true +providers__twitter__BearerToken=your-bearer-token-here +``` + +**Azure Key Vault:** +If using Azure Key Vault, store the configuration with the key: +``` +TagzApp-providers-twitter +``` + +## Step 5: Test Your Configuration + +1. In TagzApp, configure a hashtag to monitor (e.g., `#test`) +2. Post a tweet with that hashtag on Twitter/X +3. Check if the tweet appears in TagzApp (may take 30-60 seconds due to API polling) +4. If tweets don't appear, check the logs for errors + +## Troubleshooting + +### Common Issues + +#### "401 Unauthorized" Error +- **Cause**: Invalid or expired Bearer Token +- **Solution**: + - Verify you copied the entire token correctly + - Regenerate the token in the Developer Portal + - Update the configuration with the new token + +#### "429 Too Many Requests" Error +- **Cause**: Exceeded API rate limits +- **Solution**: + - Wait for the rate limit window to reset (typically 15 minutes) + - Consider upgrading your Twitter/X API access tier + - Reduce the frequency of hashtag polling in TagzApp + +#### No Tweets Appearing +- **Cause**: Various reasons +- **Solution**: + - Verify the hashtag exists and has recent tweets + - Check if the provider is enabled in TagzApp + - Verify your Bearer Token is correct + - Check TagzApp logs for error messages + - Ensure your Twitter/X app has appropriate permissions + +#### "403 Forbidden" Error +- **Cause**: API access level doesn't support the feature +- **Solution**: + - Verify your Twitter/X account has the correct API access level + - Some features require paid API tiers + - Check the Twitter/X Developer Portal for your access level + +## Rate Limits + +Twitter/X imposes rate limits on API requests: + +- **Free tier**: + - 500,000 tweets/month + - Search endpoint: ~180 requests per 15 minutes +- **Basic tier**: + - More generous limits, check Twitter/X documentation +- **Higher tiers**: + - Increased or unlimited access depending on plan + +TagzApp automatically handles rate limiting and will pause requests when limits are reached. + +## Security Best Practices + +1. **Never commit API credentials to source control** +2. **Use environment variables or secure vaults** (Azure Key Vault, AWS Secrets Manager, etc.) +3. **Rotate credentials periodically** +4. **Regenerate tokens if compromised** +5. **Use the minimum required API access level** +6. **Monitor API usage** in the Developer Portal + +## Additional Resources + +- [Twitter/X API Documentation](https://developer.twitter.com/en/docs/twitter-api) +- [Twitter/X Developer Portal](https://developer.twitter.com/en/portal/dashboard) +- [API Access Levels and Pricing](https://developer.twitter.com/en/products/twitter-api) +- [Rate Limit Documentation](https://developer.twitter.com/en/docs/twitter-api/rate-limits) +- [Twitter/X API Support](https://developer.twitter.com/en/support/twitter-api) + +## Need Help? + +If you encounter issues not covered here: +1. Check the [TagzApp GitHub Issues](https://github.com/FritzAndFriends/TagzApp/issues) +2. Review the application logs for detailed error messages +3. Consult the Twitter/X API documentation +4. Open a new issue on GitHub with details about your problem diff --git a/user-docs/providers/content/YouTubeChat-Configuration.md b/user-docs/providers/content/YouTubeChat-Configuration.md new file mode 100644 index 00000000..8575b957 --- /dev/null +++ b/user-docs/providers/content/YouTubeChat-Configuration.md @@ -0,0 +1,342 @@ +# YouTube Chat Provider Configuration Guide + +This guide will help you configure the YouTube Chat content provider for TagzApp to monitor live chat messages from YouTube live streams. + +## Overview + +The YouTube Chat provider allows TagzApp to connect to a YouTube live stream's chat and display messages containing specific hashtags or keywords. This is ideal for live streaming events where you want to showcase viewer interactions from YouTube. + +## Prerequisites + +- A Google account with YouTube access +- A YouTube channel (required for API access) +- A Google Cloud Platform (GCP) project +- YouTube Data API v3 enabled +- OAuth 2.0 credentials configured + +## Step 1: Create a Google Cloud Project + +1. Go to the [Google Cloud Console](https://console.cloud.google.com/) +2. Sign in with your Google account +3. Click **"Select a project"** at the top, then **"New Project"** +4. Enter a project name (e.g., "TagzApp YouTube Integration") +5. Click **"Create"** +6. Wait for the project to be created (takes a few seconds) + +## Step 2: Enable YouTube Data API v3 + +1. In the Google Cloud Console, select your project +2. Go to **"APIs & Services"** > **"Library"** +3. Search for **"YouTube Data API v3"** +4. Click on **"YouTube Data API v3"** +5. Click **"Enable"** +6. Wait for the API to be enabled + +## Step 3: Create OAuth 2.0 Credentials + +### Configure OAuth Consent Screen + +1. Go to **"APIs & Services"** > **"OAuth consent screen"** +2. Select **"External"** user type (unless you have Google Workspace) +3. Click **"Create"** +4. Fill in the application information: + - **App name**: "TagzApp" + - **User support email**: Your email + - **Developer contact email**: Your email +5. Click **"Save and Continue"** +6. On the **Scopes** page: + - Click **"Add or Remove Scopes"** + - Search for and select: `https://www.googleapis.com/auth/youtube.readonly` + - Click **"Update"** and **"Save and Continue"** +7. On **Test users** page: + - Click **"Add Users"** + - Add the Google account that owns the YouTube channel you want to monitor + - Click **"Save and Continue"** +8. Review and click **"Back to Dashboard"** + +### Create OAuth Client ID + +1. Go to **"APIs & Services"** > **"Credentials"** +2. Click **"+ Create Credentials"** > **"OAuth client ID"** +3. Select **"Web application"** +4. Configure the client: + - **Name**: "TagzApp YouTube Client" + - **Authorized redirect URIs**: Add your TagzApp URL(s): + - Development: `https://localhost:5001/signin-google` (adjust port as needed) + - Production: `https://yourdomain.com/signin-google` +5. Click **"Create"** +6. **Important:** Copy the **Client ID** and **Client Secret** immediately +7. Click **"OK"** + +## Step 4: Get an API Key (Alternative Method) + +If you prefer to use an API key instead of OAuth (limited functionality): + +1. Go to **"APIs & Services"** > **"Credentials"** +2. Click **"+ Create Credentials"** > **"API key"** +3. Copy the generated API key +4. Click **"Close"** +5. (Optional) Click **"Restrict Key"** to add security restrictions + +**Note:** API keys have more limitations than OAuth. OAuth is recommended for full functionality. + +## Step 5: Configure TagzApp for OAuth + +### Using the Admin UI + +1. Log in to TagzApp as an administrator +2. Navigate to **Admin > External Authentication** +3. Find **"Google"** provider +4. Configure OAuth credentials: + - **Client ID**: Your Google OAuth Client ID + - **Client Secret**: Your Google OAuth Client Secret + - **Enabled**: Toggle to enable +5. Click **"Save Configuration"** + +## Step 6: Authenticate with YouTube + +1. In TagzApp, navigate to **Admin > Providers** +2. Find the **"YouTubeChat"** provider +3. Click **"Configure"** or **"Authenticate with Google"** +4. You'll be redirected to Google's login page +5. Sign in with the Google account that has your YouTube channel +6. Grant the requested permissions: + - View your YouTube account + - View YouTube live chat messages +7. You'll be redirected back to TagzApp +8. TagzApp will store a refresh token for ongoing access + +## Step 7: Configure YouTube Chat Provider + +After authenticating, configure the provider: + +### Using the Admin UI + +1. Navigate to **Admin > Providers** > **YouTubeChat** +2. Configure the settings: + - **Enabled**: Toggle to enable the provider + - **Channel Email**: Your YouTube/Google account email (auto-filled) + - **YouTube API Key**: (Optional) Your API key if not using OAuth + - **Channel ID**: (Auto-detected from OAuth) + - **Channel Title**: (Auto-detected from OAuth) +3. Select the broadcast to monitor: + - TagzApp will show your active live streams + - Select the stream you want to monitor +4. Click **"Save Configuration"** + +### Using Configuration Files + +**appsettings.json:** +```json +{ + "Authentication": { + "Google": { + "ClientId": "your-client-id.apps.googleusercontent.com", + "ClientSecret": "your-client-secret" + } + }, + "providers": { + "youtubechat": { + "Enabled": true, + "YouTubeApiKey": "your-api-key", + "ChannelId": "UC...", + "ChannelTitle": "Your Channel", + "ChannelEmail": "your-email@gmail.com", + "BroadcastId": "broadcast-id", + "LiveChatId": "live-chat-id", + "RefreshToken": "your-refresh-token" + } + } +} +``` + +**Note:** Most of these values are obtained automatically through OAuth authentication. + +## Step 8: Test Your Configuration + +1. Start a YouTube live stream on your channel +2. Ensure TagzApp is configured to monitor that stream +3. Send a test message in the YouTube chat with your hashtag +4. The message should appear in TagzApp within a few seconds +5. Check the logs if messages don't appear + +## Understanding YouTube Chat Integration + +### How It Works + +The YouTube Chat provider: +1. Uses OAuth to authenticate with your YouTube account +2. Retrieves your active live streams +3. Connects to the selected stream's live chat +4. Polls for new messages every few seconds +5. Filters messages based on hashtag configuration +6. Displays matching messages in TagzApp + +### Message Processing + +- **Near real-time**: Messages appear with a few seconds delay (API polling) +- **Filtering**: Only messages with configured hashtags are shown +- **Metadata**: Includes username, timestamp, and author details +- **Emojis**: YouTube emojis and Super Chat are captured + +## Troubleshooting + +### Common Issues + +#### "Authentication Failed" Error +- **Cause**: OAuth credentials are invalid or expired +- **Solution**: + - Re-authenticate with Google in the Admin UI + - Verify Client ID and Client Secret are correct + - Check that the YouTube Data API is enabled + - Ensure your Google account has access to the YouTube channel + +#### "Quota Exceeded" Error +- **Cause**: YouTube API quota limits reached +- **Solution**: + - YouTube API has daily quotas (10,000 units/day for free tier) + - Each API call costs quota units + - Wait for quota to reset (midnight Pacific Time) + - Request quota increase in Google Cloud Console + - Consider upgrading to a paid plan + +#### No Messages Appearing +- **Cause**: Various reasons +- **Solution**: + - Verify the live stream is active + - Check if chat is enabled for the stream + - Ensure the provider is enabled in TagzApp + - Verify OAuth tokens are valid (re-authenticate if needed) + - Check TagzApp logs for errors + - Verify the broadcast ID and chat ID are correct + +#### "Invalid Broadcast" Error +- **Cause**: Broadcast ID is wrong or stream ended +- **Solution**: + - Reconfigure the provider to select the correct stream + - Start a new live stream on YouTube + - Verify the stream has chat enabled + +#### "Insufficient Permissions" Error +- **Cause**: OAuth scopes are missing +- **Solution**: + - Re-authenticate and ensure you grant all requested permissions + - Verify the OAuth consent screen includes YouTube read scope + - Check that the authenticated account owns the YouTube channel + +### Rate Limits and Quotas + +#### YouTube API Quotas + +- **Default quota**: 10,000 units per day (free tier) +- **List messages**: ~5 units per request +- **Get broadcast**: ~1 unit per request +- **Polling frequency**: Affects quota usage + +**Quota calculation example:** +- Polling every 5 seconds: 17,280 requests/day +- At 5 units per request: 86,400 units/day +- **Exceeds free quota!** Adjust polling frequency or request more quota. + +#### Best Practices for Quota Management + +1. **Increase polling interval**: Check every 10-15 seconds instead of 5 +2. **Request quota increase**: In Google Cloud Console > Quotas +3. **Monitor usage**: Check quota usage in GCP Console +4. **Optimize filters**: Only poll when stream is active +5. **Consider paid plans**: Higher quotas available with billing enabled + +## Advanced Configuration + +### Multiple Streams + +To monitor multiple YouTube channels: +1. Each channel requires separate OAuth authentication +2. Deploy multiple TagzApp instances or +3. Configure multiple provider instances (requires code changes) + +### Super Chat Integration + +YouTube Super Chat messages (paid highlights): +- Automatically included in chat messages +- Can be filtered or highlighted separately +- Includes payment amount and styling information + +### Moderator Actions + +If authenticated as a channel owner/moderator: +- Can potentially remove messages (future feature) +- Can view all messages including held for review + +## OAuth Token Management + +### Refresh Tokens + +- TagzApp stores a refresh token after initial authentication +- Refresh tokens are long-lived (don't expire unless revoked) +- Used to get new access tokens automatically +- Securely stored in TagzApp configuration + +### Token Security + +1. **Never share OAuth tokens** +2. **Store in secure configuration** (Azure Key Vault, environment variables) +3. **Revoke if compromised**: Google Cloud Console > Credentials +4. **Rotate periodically**: Re-authenticate every few months + +### Revoking Access + +To revoke TagzApp's access to your YouTube: +1. Go to [Google Account Security](https://myaccount.google.com/permissions) +2. Find "TagzApp" in the list +3. Click **"Remove Access"** +4. Re-authenticate in TagzApp to restore access + +## Security Best Practices + +1. **Use OAuth instead of API keys** - More secure and full featured +2. **Restrict API keys** - Add HTTP referrer or IP restrictions +3. **Limit OAuth scopes** - Only request necessary permissions +4. **Monitor quota usage** - Watch for unexpected API usage +5. **Secure credentials** - Use Key Vault or secrets management +6. **Enable 2FA** - On the Google account used for authentication + +## Additional Resources + +- [YouTube Data API Documentation](https://developers.google.com/youtube/v3) +- [YouTube Live Streaming API](https://developers.google.com/youtube/v3/live/docs/) +- [Google OAuth 2.0 Documentation](https://developers.google.com/identity/protocols/oauth2) +- [YouTube API Quotas](https://developers.google.com/youtube/v3/getting-started#quota) +- [Google Cloud Console](https://console.cloud.google.com/) +- [YouTube Chat API Reference](https://developers.google.com/youtube/v3/live/docs/liveChatMessages) + +## Cost Considerations + +### Free Tier + +- 10,000 quota units per day +- Sufficient for light usage +- Monitor quota carefully + +### Paid Tier + +- Billing must be enabled in GCP +- Higher quotas available +- Pay-as-you-go pricing +- [Check current pricing](https://cloud.google.com/pricing) + +### Quota Increase Requests + +- Can request quota increases in GCP Console +- Approval usually within 24-48 hours +- May require billing account +- Explain your use case in the request + +## Need Help? + +If you encounter issues not covered here: +1. Check the [TagzApp GitHub Issues](https://github.com/FritzAndFriends/TagzApp/issues) +2. Review the application logs for detailed error messages +3. Check [YouTube API Status](https://www.google.com/appsstatus) +4. Consult Google's YouTube API documentation +5. Open a new issue on GitHub with details about your problem From d79a2e130198dbab8d860f6080444ed85faaa507 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 5 Oct 2025 16:11:14 +0000 Subject: [PATCH 3/3] Complete provider documentation with Azure Queue and screenshot guidelines Co-authored-by: csharpfritz <78577+csharpfritz@users.noreply.github.com> --- user-docs/README.md | 36 ++ .../content/AzureQueue-Configuration.md | 429 ++++++++++++++++++ 2 files changed, 465 insertions(+) create mode 100644 user-docs/providers/content/AzureQueue-Configuration.md diff --git a/user-docs/README.md b/user-docs/README.md index 4152666e..eb32be09 100644 --- a/user-docs/README.md +++ b/user-docs/README.md @@ -53,6 +53,12 @@ These guides explain how to obtain API credentials and configure social media co - API key generation - Rate limit management +- **[Azure Queue Configuration](providers/content/AzureQueue-Configuration.md)** - Configure custom message queue integration + - Azure Storage Account setup + - Queue creation and management + - Connection string configuration + - Message format and integration examples + ### Authentication Provider Configuration Guides These guides explain how to set up external login providers for TagzApp: @@ -92,6 +98,36 @@ These guides explain how to set up external login providers for TagzApp: - JWT client secret generation - Privacy features +## Adding Screenshots + +The documentation above references several configuration steps that would benefit from screenshots. To add screenshots: + +1. **For Content Providers:** Take screenshots showing: + - Developer console/portal pages + - API key generation screens + - Configuration forms + - Successful configuration indicators + +2. **For Authentication Providers:** Take screenshots showing: + - OAuth app registration forms + - Client credential pages + - Redirect URI configuration + - TagzApp login page with provider buttons + +3. **Save screenshots to:** `user-docs/images/providers/` + - Content providers: `user-docs/images/providers/content/[provider-name]/` + - Authentication providers: `user-docs/images/providers/authentication/[provider-name]/` + +4. **Reference in documentation:** Use relative paths like: + ```markdown + ![Twitter Developer Portal](../../images/providers/content/twitter/developer-portal.png) + ``` + +5. **Screenshot naming conventions:** + - Use lowercase and hyphens: `twitter-api-keys.png` + - Be descriptive: `github-oauth-app-creation.png` + - Include step numbers if helpful: `01-azure-create-app.png` + ## Screenshots The `images/` folder contains screenshots and visual references used in the documentation: diff --git a/user-docs/providers/content/AzureQueue-Configuration.md b/user-docs/providers/content/AzureQueue-Configuration.md new file mode 100644 index 00000000..6b0cb1d5 --- /dev/null +++ b/user-docs/providers/content/AzureQueue-Configuration.md @@ -0,0 +1,429 @@ +# Azure Queue Provider Configuration Guide + +This guide will help you configure the Azure Queue content provider for TagzApp to read custom messages from Azure Storage Queue. + +## Overview + +The Azure Queue provider allows TagzApp to read messages from a custom Azure Storage Queue. This is useful for integrating custom data sources, third-party applications, or automated systems that post content to TagzApp via Azure Queue Storage. + +## Prerequisites + +- An Azure account +- An Azure Storage Account +- Access to Azure Portal or Azure CLI +- Basic understanding of Azure Queue Storage + +## Use Cases + +The Azure Queue provider is ideal for: +- **Custom integrations**: Push content from internal systems +- **Third-party services**: Integrate services without direct API support +- **Automated content**: Post scheduled or triggered content +- **Legacy systems**: Connect systems that can write to Azure Queue +- **Bulk operations**: Queue multiple messages for processing + +## Step 1: Create an Azure Storage Account + +### Using Azure Portal + +1. Go to [Azure Portal](https://portal.azure.com) +2. Sign in with your Azure account +3. Click **"Create a resource"** +4. Search for **"Storage account"** +5. Click **"Create"** +6. Configure the storage account: + - **Subscription**: Select your subscription + - **Resource group**: Create new or select existing + - **Storage account name**: Enter a unique name (lowercase, numbers only) + - **Region**: Select your preferred region + - **Performance**: Standard (unless you need Premium) + - **Redundancy**: Choose based on your needs (LRS is cheapest) +7. Click **"Review + create"** and then **"Create"** +8. Wait for deployment to complete + +### Using Azure CLI + +```bash +# Create resource group (if needed) +az group create --name TagzAppResources --location eastus + +# Create storage account +az storage account create \ + --name tagzappstorage \ + --resource-group TagzAppResources \ + --location eastus \ + --sku Standard_LRS +``` + +## Step 2: Create a Queue + +### Using Azure Portal + +1. Navigate to your Storage Account +2. In the left menu, click **"Queues"** under "Data storage" +3. Click **"+ Queue"** +4. Enter a queue name (e.g., `tagzapp-messages`) +5. Click **"OK"** + +### Using Azure CLI + +```bash +# Get connection string +CONNECTION_STRING=$(az storage account show-connection-string \ + --name tagzappstorage \ + --resource-group TagzAppResources \ + --query connectionString -o tsv) + +# Create queue +az storage queue create \ + --name tagzapp-messages \ + --connection-string "$CONNECTION_STRING" +``` + +## Step 3: Get Your Connection String + +### Using Azure Portal + +1. Navigate to your Storage Account +2. In the left menu, click **"Access keys"** under "Security + networking" +3. You'll see two keys (key1 and key2) +4. Click **"Show keys"** to reveal connection strings +5. Copy the **"Connection string"** for either key + - Example: `DefaultEndpointsProtocol=https;AccountName=tagzappstorage;AccountKey=xxx...;EndpointSuffix=core.windows.net` + +### Using Azure CLI + +```bash +az storage account show-connection-string \ + --name tagzappstorage \ + --resource-group TagzAppResources \ + --query connectionString -o tsv +``` + +**⚠️ Security Warning:** Connection strings provide full access to your storage account. Keep them secure and never commit them to source control. + +## Step 4: Configure TagzApp + +### Using the Admin UI (Recommended) + +1. Log in to TagzApp as an administrator +2. Navigate to **Admin > Providers** +3. Find the **"AzureQueue"** provider +4. Click **"Configure"** +5. Enter your configuration: + - **Queue Connection String**: Paste your Azure Storage connection string + - **Enabled**: Toggle to enable the provider +6. Click **"Save Configuration"** + +### Using Configuration Files + +**appsettings.json:** +```json +{ + "providers": { + "azurequeue": { + "Enabled": true, + "QueueConnectionString": "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net" + } + } +} +``` + +**Environment Variables:** +```bash +providers__azurequeue__Enabled=true +providers__azurequeue__QueueConnectionString="DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...;EndpointSuffix=core.windows.net" +``` + +**Azure Key Vault:** +Store with the key: +``` +TagzApp-providers-azurequeue +``` + +## Step 5: Send Messages to the Queue + +### Message Format + +Messages sent to the Azure Queue should follow the TagzApp content format. The exact schema depends on your TagzApp version, but typically includes: + +```json +{ + "provider": "AzureQueue", + "author": { + "displayName": "User Name", + "userName": "username", + "profileImage": "https://example.com/avatar.jpg" + }, + "content": "Message content with #hashtag", + "timestamp": "2024-01-15T12:00:00Z", + "sourceUri": "https://source.example.com/message/123" +} +``` + +### Using Azure Portal + +1. Navigate to your Storage Account +2. Click **"Queues"** +3. Select your queue +4. Click **"+ Add message"** +5. Enter your JSON message +6. Click **"OK"** + +### Using Azure CLI + +```bash +az storage message put \ + --queue-name tagzapp-messages \ + --content '{"provider":"AzureQueue","author":{"displayName":"Test User"},"content":"Test message #test"}' \ + --connection-string "$CONNECTION_STRING" +``` + +### Using C# Code + +```csharp +using Azure.Storage.Queues; +using System.Text.Json; + +var connectionString = "your-connection-string"; +var queueName = "tagzapp-messages"; + +var queueClient = new QueueClient(connectionString, queueName); +await queueClient.CreateIfNotExistsAsync(); + +var message = new { + provider = "AzureQueue", + author = new { + displayName = "User Name", + userName = "username" + }, + content = "Message content #hashtag", + timestamp = DateTime.UtcNow.ToString("o"), + sourceUri = "https://example.com/message/123" +}; + +var messageJson = JsonSerializer.Serialize(message); +await queueClient.SendMessageAsync(messageJson); +``` + +### Using PowerShell + +```powershell +$connectionString = "your-connection-string" +$queueName = "tagzapp-messages" + +$context = New-AzStorageContext -ConnectionString $connectionString +$queue = Get-AzStorageQueue -Name $queueName -Context $context + +$message = @{ + provider = "AzureQueue" + author = @{ + displayName = "User Name" + userName = "username" + } + content = "Message content #hashtag" + timestamp = (Get-Date).ToUniversalTime().ToString("o") +} | ConvertTo-Json + +$queue.CloudQueue.AddMessage($message) +``` + +## Step 6: Test Your Configuration + +1. Send a test message to your Azure Queue (using any method above) +2. Wait a few seconds for TagzApp to poll the queue +3. The message should appear in TagzApp +4. Check TagzApp logs if messages don't appear + +## Troubleshooting + +### Common Issues + +#### "Invalid Connection String" Error +- **Cause**: Connection string is malformed or incorrect +- **Solution**: + - Verify you copied the entire connection string + - Check for extra spaces or line breaks + - Regenerate connection string in Azure Portal + +#### "Queue Not Found" Error +- **Cause**: Queue doesn't exist or name mismatch +- **Solution**: + - Verify the queue exists in your storage account + - Check queue name spelling + - Create the queue if it doesn't exist + +#### "Authentication Failed" Error +- **Cause**: Invalid account key or SAS token +- **Solution**: + - Regenerate access keys in Azure Portal + - Update TagzApp configuration + - Check if connection string has expired + +#### No Messages Appearing +- **Cause**: Various reasons +- **Solution**: + - Verify the provider is enabled in TagzApp + - Check if messages are in the queue (Azure Portal) + - Verify message format is correct + - Check TagzApp logs for parsing errors + - Ensure queue connection string is correct + +#### Messages Disappearing Without Processing +- **Cause**: Invalid message format +- **Solution**: + - Check message schema matches expected format + - Review TagzApp logs for parsing errors + - Validate JSON structure + +## Queue Behavior + +### Message Processing + +- TagzApp polls the queue periodically +- Messages are retrieved and processed +- Successfully processed messages are deleted from the queue +- Failed messages may be retried (depending on configuration) + +### Message Visibility + +- Messages have a visibility timeout (default 30 seconds) +- If TagzApp crashes during processing, message becomes visible again +- Prevents message loss during failures + +### Message Retention + +- Azure Queue messages are retained for up to 7 days by default +- Unprocessed messages older than retention period are deleted +- Configure retention period in Azure Portal if needed + +## Security Best Practices + +1. **Use Azure Key Vault**: Store connection strings in Azure Key Vault +2. **Rotate keys regularly**: Regenerate storage account keys periodically +3. **Use Managed Identity**: If TagzApp runs in Azure, use managed identity instead of connection strings +4. **Limit access**: Use SAS tokens with minimal permissions instead of full connection strings +5. **Monitor access**: Review Azure Storage logs for unauthorized access +6. **Encrypt at rest**: Enable storage account encryption (enabled by default) + +## Using Shared Access Signatures (SAS) + +For better security, use SAS tokens instead of full connection strings: + +### Generate SAS Token + +```bash +# Generate SAS token for queue +az storage queue generate-sas \ + --name tagzapp-messages \ + --account-name tagzappstorage \ + --permissions raup \ + --expiry 2025-12-31 \ + --https-only \ + --connection-string "$CONNECTION_STRING" +``` + +### Use SAS Token in Connection String + +``` +BlobEndpoint=https://tagzappstorage.blob.core.windows.net/;QueueEndpoint=https://tagzappstorage.queue.core.windows.net/;SharedAccessSignature=sv=2021-06-08&ss=q&srt=sco&sp=raup&se=2025-12-31T... +``` + +## Cost Considerations + +### Azure Storage Pricing + +- **Queue operations**: ~$0.0036 per 10,000 operations +- **Data storage**: ~$0.02 per GB per month +- **Data transfer**: Free for data in, varies for data out + +### Typical Costs for TagzApp + +- Small events: < $1/month +- Medium events: $1-5/month +- Large events: $5-20/month + +### Cost Optimization + +1. **Delete processed messages**: TagzApp does this automatically +2. **Monitor queue length**: Prevent unbounded growth +3. **Use appropriate redundancy**: LRS is cheapest +4. **Set message retention**: Don't store messages longer than needed + +## Advanced Configuration + +### Using Managed Identity (Azure) + +If TagzApp runs in Azure (App Service, Container, VM): + +1. Enable managed identity on your Azure resource +2. Grant identity "Storage Queue Data Contributor" role +3. Use managed identity authentication instead of connection string + +**Code example:** +```csharp +var queueServiceClient = new QueueServiceClient( + new Uri("https://tagzappstorage.queue.core.windows.net"), + new DefaultAzureCredential() +); +``` + +### Multiple Queues + +To integrate multiple sources: +1. Create separate queues for each source +2. Configure multiple AzureQueue provider instances (requires code changes) +3. Or process all messages through a single queue with source identification + +## Integration Examples + +### Webhook to Queue + +Create an Azure Function to receive webhooks and post to queue: + +```csharp +[FunctionName("WebhookToQueue")] +public static async Task Run( + [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req, + [Queue("tagzapp-messages")] IAsyncCollector queueMessages) +{ + var content = await new StreamReader(req.Body).ReadToEndAsync(); + await queueMessages.AddAsync(content); + return new OkResult(); +} +``` + +### Scheduled Messages + +Use Azure Logic Apps or Functions to post scheduled content to the queue. + +## Monitoring + +### Azure Portal + +1. Navigate to your Storage Account +2. Click **"Monitoring"** > **"Metrics"** +3. View queue operations, message count, etc. + +### Application Insights + +Integrate TagzApp with Application Insights to track: +- Message processing times +- Error rates +- Queue poll frequency + +## Additional Resources + +- [Azure Queue Storage Documentation](https://docs.microsoft.com/azure/storage/queues/) +- [Azure Storage Explorer](https://azure.microsoft.com/features/storage-explorer/) +- [Azure CLI Reference](https://docs.microsoft.com/cli/azure/storage/queue) +- [.NET Azure Queue Client Library](https://docs.microsoft.com/dotnet/api/overview/azure/storage.queues-readme) +- [Azure Pricing Calculator](https://azure.microsoft.com/pricing/calculator/) + +## Need Help? + +If you encounter issues not covered here: +1. Check the [TagzApp GitHub Issues](https://github.com/FritzAndFriends/TagzApp/issues) +2. Review Azure Storage Queue logs and metrics +3. Consult Azure Storage Queue documentation +4. Open a new issue on GitHub with details about your problem