Authentication Setup - smart-coder997/recommendarr GitHub Wiki

Authentication Setup (Optional)

Recommendarr supports optional user authentication via social login (Google, GitHub) or a custom OAuth2 provider. This allows multiple users to use the application with their own settings.

Generating a Secure SESSION_SECRET

A SESSION_SECRET is crucial for encrypting user session cookies. It must be:

At least 32 characters long Randomly generated Kept secret You can generate a secure secret using tools like OpenSSL:

# On Linux/macOS:
openssl rand -hex 32

# On Windows (using PowerShell):
$bytes = New-Object Byte[] 32
$rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rng.GetBytes($bytes)
$secret = [System.BitConverter]::ToString($bytes).Replace("-", "").ToLower()
Write-Host $secret

Store this generated secret securely; you'll need it for the environment variables.

Setting Up OAuth Providers

1. Create OAuth Applications

You need to register Recommendarr as an application with each provider you want to enable:

  • Google:

    • Go to the Google Developer Console.
    • Create a new project or select an existing one.
    • Navigate to "APIs & Services" -> "Credentials".
    • Click "Create Credentials" -> "OAuth client ID".
    • Select "Web application" as the application type.
    • Configure Authorized JavaScript origins: Add your Recommendarr's public URL (e.g., http://localhost:3000 or https://recommendarr.yourdomain.com).
    • Configure Authorized redirect URIs: Add the specific callback URL (see below).
    • Save the credentials and note the Client ID and Client Secret.

  • GitHub:

    • Go to your GitHub Developer Settings -> "OAuth Apps".
    • Click "New OAuth App".
    • Fill in the application details (Name, Homepage URL - your Recommendarr's public URL).
    • Set the Authorization callback URL (see below).
    • Click "Register application".
    • Generate a new Client Secret and note it down along with the Client ID.

  • Custom OAuth2 Provider:

    • Access your OAuth2 provider's developer or admin console.
    • Create a new OAuth2 application (client registration).
    • Configure the allowed Redirect URI or Callback URL (see below).
    • Note the provider's Authorization URL, Token URL, and User Info URL.
    • Define the necessary Scopes (e.g., openid profile email).
    • Save the application and note the Client ID and Client Secret.

2. Configure Callback URLs

The callback URL tells the OAuth provider where to redirect the user after successful authentication. It must match exactly what you configured in the provider's settings.

The format is: {PUBLIC_URL}/api/auth/{provider}/callback

Where:

  • {PUBLIC_URL} is your Recommendarr's base public URL (e.g., http://localhost:3000, https://recommendarr.yourdomain.com). This must be set correctly using the PUBLIC_URL environment variable.
  • {provider} is google, github, or custom.

Examples:

  • Google (Development): http://localhost:3000/api/auth/google/callback
  • GitHub (Production): https://recommendarr.yourdomain.com/api/auth/github/callback
  • Custom (Production): https://recommendarr.yourdomain.com/api/auth/custom/callback

3. Set Environment Variables

Add the following environment variables to your Recommendarr setup (e.g., in docker-compose.yml, .env file, or Docker run command):

# Required for any OAuth provider
SESSION_SECRET=your-securely-generated-secret-here # Use the secret you generated earlier
PUBLIC_URL=http://localhost:3000 # IMPORTANT: Set this to your actual public URL

# Google OAuth (only if enabling Google login)
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret

# GitHub OAuth (only if enabling GitHub login)
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# Custom OAuth2 Provider (only if enabling custom login)
CUSTOM_OAUTH_AUTH_URL=https://your-provider.com/oauth/authorize
CUSTOM_OAUTH_TOKEN_URL=https://your-provider.com/oauth/token
CUSTOM_OAUTH_USERINFO_URL=https://your-provider.com/oauth/userinfo
CUSTOM_OAUTH_CLIENT_ID=your-custom-client-id
CUSTOM_OAUTH_CLIENT_SECRET=your-custom-client-secret
CUSTOM_OAUTH_SCOPE=openid profile email # Adjust scopes as needed

# Optional: For HTTPS setups (e.g., behind a reverse proxy)
# FORCE_SECURE_COOKIES=true

See Environment Variables for more details on setting these.

4. Restart Recommendarr

After configuring the environment variables, restart the Recommendarr application for the changes to take effect.

5. Verify Login

  • Visit the Recommendarr login page. You should now see buttons for the OAuth providers you configured.
  • Test the login flow for each enabled provider.
  • Check the Recommendarr server logs for any authentication-related errors if login fails.

Important Notes

  • The SESSION_SECRET must remain consistent across application restarts. Changing it will invalidate all existing user sessions.
  • If Recommendarr is running behind an HTTPS reverse proxy, set FORCE_SECURE_COOKIES=true to ensure cookies are handled correctly. See Troubleshooting.
  • By default, users logging in via OAuth are created with standard privileges. An administrator can promote users if needed via the User Management interface.
  • If you change the PUBLIC_URL, remember to update the callback URLs in your OAuth provider application settings accordingly.