118 lines
No EOL
4.5 KiB
Markdown
118 lines
No EOL
4.5 KiB
Markdown
# Twitch Authentication Setup
|
|
|
|
This document explains how to set up Twitch authentication for the application.
|
|
|
|
## Prerequisites
|
|
|
|
1. You need a Twitch account
|
|
2. You need to register a Twitch application at [Twitch Developer Console](https://dev.twitch.tv/console/apps)
|
|
3. Required Python packages:
|
|
- `cryptography` - For generating SSL certificates
|
|
- `requests` - For making HTTP requests to the Twitch API
|
|
- `python-dotenv` - For managing environment variables
|
|
|
|
You can install these dependencies using the provided script:
|
|
|
|
```bash
|
|
python scripts/install_auth_deps.py
|
|
```
|
|
|
|
## Registering a Twitch Application
|
|
|
|
1. Go to [Twitch Developer Console](https://dev.twitch.tv/console/apps)
|
|
2. Click "Register Your Application"
|
|
3. Fill in the details:
|
|
- **Name**: Choose a name for your application (e.g., "MyStreamInteract")
|
|
- **OAuth Redirect URLs**: Set to `https://localhost:3000` (note: HTTPS is required)
|
|
- **Category**: Choose "Chat Bot"
|
|
4. Click "Create"
|
|
5. Once created, click "Manage" for your application
|
|
6. Make note of your **Client ID**
|
|
7. Generate a **Client Secret** and store it securely
|
|
|
|
## Setting Up Authentication
|
|
|
|
There are two ways to authenticate:
|
|
|
|
### Method 1: Using the Setup Script (Recommended)
|
|
|
|
We provide a setup script that walks you through the authentication process:
|
|
|
|
```bash
|
|
python scripts/setup_twitch_auth.py
|
|
```
|
|
|
|
The script will:
|
|
1. Ask for your Client ID and Client Secret
|
|
2. Generate a self-signed SSL certificate for HTTPS (required by Twitch)
|
|
3. Open a browser window for authentication
|
|
4. Store the tokens securely
|
|
5. Update your .env file with the credentials
|
|
|
|
> **Note:** When the browser opens, you will see a security warning about the self-signed certificate.
|
|
> This is normal for local development. You need to proceed past this warning to continue the authentication process.
|
|
> In Chrome, click "Advanced" and then "Proceed to localhost (unsafe)".
|
|
|
|
If you want to force the generation of a new token (ignoring any cached ones):
|
|
|
|
```bash
|
|
python scripts/setup_twitch_auth.py --force-new-token
|
|
```
|
|
|
|
### Method 2: Manual Setup
|
|
|
|
1. Create or edit a `.env` file in the root directory of the project
|
|
2. Add the following information:
|
|
|
|
```
|
|
TWITCH_CLIENT_ID=your_client_id_here
|
|
TWITCH_CLIENT_SECRET=your_client_secret_here
|
|
TWITCH_USERNAME=your_twitch_username
|
|
TWITCH_CHANNEL=channel_to_connect_to
|
|
```
|
|
|
|
3. Run the authentication script:
|
|
|
|
```bash
|
|
python scripts/setup_twitch_auth.py --manual
|
|
```
|
|
|
|
4. Follow the instructions to complete authentication
|
|
|
|
## Windows-Specific Information
|
|
|
|
On Windows, the application uses the Python `cryptography` library to generate self-signed certificates instead of relying on the OpenSSL command-line tool. This ensures better compatibility with Windows systems.
|
|
|
|
If you encounter any issues with certificate generation on Windows:
|
|
|
|
1. Make sure you have the latest version of pip: `python -m pip install --upgrade pip`
|
|
2. Try reinstalling the cryptography package: `pip install --force-reinstall cryptography`
|
|
3. Visual C++ Build tools might be required. If you get build errors, you may need to install the [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
|
|
|
|
## Important Notes
|
|
|
|
- The application uses user access tokens with `chat:read` and `chat:edit` scopes
|
|
- IRC chat access requires a user access token (client credentials are not sufficient)
|
|
- Twitch requires HTTPS for OAuth redirects, so we use a self-signed certificate for local development
|
|
- The tokens are cached in `data/cache/token_cache.json` and refreshed automatically when needed
|
|
- Never share your Client Secret or access tokens
|
|
|
|
## Self-Signed Certificates
|
|
|
|
The application automatically generates a self-signed certificate for HTTPS, which is stored in `data/ssl/`. This certificate is used for handling OAuth redirects from Twitch.
|
|
|
|
If you encounter certificate issues, you can delete the files in `data/ssl/` to generate a new certificate:
|
|
- `data/ssl/localhost.crt`
|
|
- `data/ssl/localhost.key`
|
|
|
|
## Troubleshooting
|
|
|
|
If you encounter authentication issues:
|
|
|
|
1. Make sure your Client ID and Client Secret are correct
|
|
2. Check that your OAuth redirect URL in the Twitch Developer Console is exactly `https://localhost:3000` (with HTTPS)
|
|
3. When prompted with certificate warnings in your browser, make sure to proceed past these warnings
|
|
4. Verify that your Twitch account has the necessary permissions
|
|
5. Delete the token cache file (`data/cache/token_cache.json`) and try again
|
|
6. Check the application logs for detailed error messages
|
|
7. If the browser doesn't open automatically, you can copy and paste the provided URL |