---
title: Discord
icon: MessageSquare
---

import { ZoomableImage } from "@/components/ui/zoomable-image";

Discord is one of Palmr's officially supported OIDC providers, offering secure authentication through Discord OAuth 2.0. This integration allows users to sign in to Palmr using their existing Discord accounts, making it perfect for gaming communities, developer teams, and organizations already using Discord.

<ZoomableImage src="/assets/v3/oidc/discord/sign-in-with-discord.png" alt="Sign in with Discord" />

## Why use Discord authentication?

Discord authentication provides several advantages for community-focused organizations and teams:

- **Community integration** - Perfect for gaming communities and Discord-centric organizations
- **Familiar experience** - Users already trust and use Discord daily
- **Rich user profiles** - Access to Discord usernames, avatars, and global names
- **Developer-friendly** - Great for technical teams and open-source projects
- **No additional accounts** - Users can access Palmr without creating new credentials

---

## Prerequisites

Before configuring Discord authentication, ensure you have:

- **Discord Developer Portal access** - Ability to create applications on Discord
- **Admin privileges in Palmr** - Required to configure OIDC settings
- **Server ownership or permissions** - If integrating with a Discord server

> **Note:** Discord is pre-configured as an official provider in Palmr, which means the technical configuration is handled automatically. You only need to provide your OAuth credentials.

---

## Setting up Discord Developer Portal

### Creating a Discord application

To get started with Discord authentication, you'll need to create an application in Discord Developer Portal.

1. **Navigate to Discord Developer Portal**: Go to [discord.com/developers/applications](https://discord.com/developers/applications)

<ZoomableImage src="/assets/v3/oidc/discord/developer-portal-home.png" alt="Discord Developer Portal Home" />

2. **Create new application**: Click **"New Application"** button
3. **Enter application details**:
   - **Name**: Enter a descriptive name like "Palmr File Sharing"
   - **Accept Terms of Service and Developer Policy**: Check the box

<ZoomableImage src="/assets/v3/oidc/discord/create-application-modal.png" alt="Discord Create Application Modal" />

4. **Create application**: Click **"Create"** to generate your application

### Configuring application settings

After creating your application, you'll need to configure basic settings and branding.

1. **Update application information**:
   - **Description**: Add a clear description of your Palmr instance
   - **Icon**: Upload your organization's logo or Palmr-related icon
   - **Cover Image**: Optional banner image for better branding

<ZoomableImage
  src="/assets/v3/oidc/discord/application-settings.png"
  alt="Discord Application Settings"
  legend="This is a fake application, you have to use your own."
/>

2. **Configure application details**:
   - **Tags**: Add relevant tags (optional)
   - **Privacy Policy URL**: Add your privacy policy URL if required
   - **Terms of Service URL**: Add your terms of service URL if required

### Setting up OAuth2 configuration

Now you'll configure the OAuth2 settings that Palmr will use to authenticate users.

1. **Navigate to OAuth2**: In the left sidebar, click **"OAuth2"**

<ZoomableImage src="/assets/v3/oidc/discord/oauth2-general.png" alt="Discord OAuth2 General Settings" />

2. **Configure OAuth2 settings**:
   - **Client Secret**: Click **"Reset Secret"** to generate a new client secret
   - **Copy credentials**: Save both **Client ID** and **Client Secret** for later use

3. **Add redirect URIs**: In the **"Redirects"** section, add your Palmr callback URLs:

You'll need to configure several URLs in your Discord application settings. Here's what to add for each environment:

### Redirect URIs

| Environment | URL                                                               |
| ----------- | ----------------------------------------------------------------- |
| Production  | `https://yourdomain.com/api/auth/providers/discord/callback`      |
| Development | `http://localhost:3000/api/auth/providers/discord/callback`       |
| Custom Port | `https://yourdomain.com:5487/api/auth/providers/discord/callback` |

> **Note:** Replace `yourdomain.com` with your actual domain name in all production and custom port URLs.
> **Note:** You can add multiple redirect URIs for different environments (development, staging, production).

4. **Select required scopes**:
   - **`identify`** - Access to user's basic account information (required)
   - **`email`** - Access to user's email address (required for Palmr)

5. **Save changes**: Click **"Save Changes"** to apply your configuration

<ZoomableImage
  src="/assets/v3/oidc/discord/required-scopes.png"
  alt="Discord Required Scopes"
  legend="This is a fake application, you have to use your own."
/>

---

## Configuring Palmr

### Accessing OIDC settings

To configure Discord authentication in Palmr, you need administrator access to the settings panel.

1. **Login as administrator**: Sign in to Palmr with an admin account

2. **Access settings**: Click your profile picture in the header and select **Settings**

3. **Navigate to authentication**: Find and click on the **Authentication Providers** configuration section

<ZoomableImage src="/assets/v3/oidc/auth-providers.png" alt="Palmr Authentication Providers" />

### Enabling Discord provider

Discord comes pre-configured as an official provider, so the setup process is streamlined.

1. **Locate Discord provider**: Find Discord in the list of available providers

2. **Enable the provider**: Toggle the status to **Enabled**

<ZoomableImage src="/assets/v3/oidc/discord/palmr-enabled-discord.png" alt="Palmr Discord Provider Enabled" />

After enabling the provider, click on the pen icon to configure the provider.

3. **Configure credentials**:
   - **Client ID**: Paste the Client ID from Discord Developer Portal
   - **Client Secret**: Paste the Client Secret from Discord Developer Portal
   - **Scopes**: Add the scopes you want to use. The default scopes are `identify` and `email`.

<ZoomableImage
  src="/assets/v3/oidc/discord/edit-discord.png"
  alt="Edit Discord Provider"
  legend="This is a fake application, you have to use your own."
/>

### Advanced configuration options

Configure additional settings to customize the authentication behavior:

**Auto Registration**: Enable this to automatically create user accounts when someone authenticates for the first time.

**Admin Email Domains**: Specify domains that should automatically receive admin privileges. This is less common with Discord since users often use personal emails.

**Sort Order**: Control where the Discord login button appears relative to other authentication providers.

**Icon**: you can choose the icon you want to use for the Discord login button (default is `FaDiscord`).

<ZoomableImage src="/assets/v3/oidc/discord/discord-icon.png" alt="Discord Icon" />

> **Community tip:** Discord authentication works great for gaming communities and development teams. Consider enabling auto-registration for trusted Discord communities.

---

## Account linking

By default, if a user is already registered in Palmr with their Discord email, they will be automatically linked to their Palmr account.

> **Note:** You can't disable account linking. If you want to unlink a user from their Discord account, you need to delete the user from Palmr.

---

## Technical configuration

Discord's technical configuration is handled automatically, but understanding the setup can help with troubleshooting:

```yaml
Provider Type: OAuth 2.0 (No OIDC Discovery)
Issuer URL: https://discord.com
Authorization Endpoint: /oauth2/authorize
Token Endpoint: /api/oauth2/token
UserInfo Endpoint: /api/users/@me
Scopes: identify email
```

### Field mappings

Palmr automatically maps Discord user information to local user accounts:

- **User ID**: Maps from Discord's `id` field
- **Email**: Maps from Discord's `email` field
- **Display Name**: Maps from Discord's `global_name` or falls back to `username`
- **Username**: Maps from Discord's `username` field
- **Avatar**: Maps from Discord's `avatar` field (processed as Discord CDN URL)

### Discord-specific features

- **Global Names**: Supports Discord's new global name system while maintaining compatibility with legacy usernames
- **Avatar Processing**: Automatically constructs Discord CDN URLs for user avatars
- **No Discovery**: Uses manually configured endpoints for better reliability

---

## Testing the configuration

### Verifying the setup

After configuring Discord authentication, test the integration to ensure everything works correctly.

1. **Check login page**: Navigate to your Palmr login page and verify the "Sign in with Discord" button appears

2. **Test authentication flow**: Click the Discord sign-in button and complete the authentication process

3. **Verify user creation**: Confirm that a new user account is created (if auto-registration is enabled)

### Login flow verification

The complete authentication process should work as follows:

1. **User clicks "Sign in with Discord"**: The browser redirects to Discord's authorization page
2. **User authorizes application**: User grants permissions for `identify` and `email` scopes
3. **Discord redirects back to Palmr**: User returns to Palmr with authentication tokens
4. **Palmr creates or updates user**: User account is automatically managed with Discord information
5. **User accesses Palmr**: User is logged in with their Discord identity

---

## Troubleshooting common issues

### Invalid redirect URI error

**Error message**: `invalid_redirect_uri`

**Cause**: The redirect URI in your request doesn't match what's configured in Discord Developer Portal.

**Solution**:

1. Check the exact URL in the error message
2. Add this exact URL to your Discord application's redirect URIs
3. Ensure you include the correct protocol (http/https) and port
4. Remove any trailing slashes unless they're in the callback URL

### Access denied error

**Error message**: `access_denied`

**Cause**: User denied permissions or the application doesn't have required scopes.

**Solution**:

1. Verify that your Discord application requests `identify` and `email` scopes
2. Check that users are granting permissions during the authorization flow
3. Ensure your application is not restricted or disabled in Discord Developer Portal
4. Verify the application has proper permissions set up

### Invalid client error

**Error message**: `invalid_client`

**Cause**: Incorrect Client ID or Client Secret.

**Solution**:

1. Double-check that you've copied the credentials correctly from Discord Developer Portal
2. Ensure there are no extra spaces or characters in the credentials
3. Generate a new Client Secret if necessary
4. Verify you're using the correct application in Discord Developer Portal

### Missing email scope error

**Error message**: Email not provided or scope missing

**Cause**: Discord application not configured with email scope or user's email is not verified.

**Solution**:

1. Verify that your Discord application requests the `email` scope
2. Check that users have verified their email addresses on Discord
3. Ensure the scope configuration matches what Palmr expects
4. Test with a Discord account that has a verified email

### User information not displaying correctly

**Cause**: Discord username/global name mapping issues.

**Solution**:

1. Check that the user has set a global name in Discord (new feature)
2. Verify field mappings are working correctly in Palmr logs
3. Test with different Discord accounts (some may have legacy usernames)
4. Update user information manually through Palmr admin interface if needed

---

## Security best practices

### Credential management

- **Never expose secrets**: Keep your Client Secret secure and never commit it to version control
- **Rotate credentials regularly**: Generate new Client Secrets periodically for enhanced security
- **Use environment variables**: Store sensitive configuration in environment variables, not config files
- **Monitor access logs**: Regularly review authentication logs for suspicious activity

### Scope and permission management

- **Minimal scopes**: Only request `identify` and `email` scopes as required by Palmr
- **User consent**: Ensure users understand what permissions they're granting
- **Regular audits**: Review which users have connected their Discord accounts
- **Access reviews**: Periodically check user access and remove inactive accounts

### Production considerations

- **Use HTTPS**: Always use HTTPS in production environments
- **Configure proper domains**: Use production domains in Discord redirect URIs
- **Test thoroughly**: Verify the complete authentication flow before going live
- **Plan for failures**: Have fallback authentication methods available

---

## Next steps

With Discord authentication configured, you might want to:

- **Configure additional providers**: Set up other OIDC providers for more authentication options
- **Customize user management**: Fine-tune auto-registration and admin assignment rules
- **Review security settings**: Ensure your authentication setup meets your security requirements
- **Monitor usage**: Keep track of authentication patterns and user activity

For more information about OIDC authentication in Palmr, see the [OIDC Authentication overview](/docs/3.2-beta/oidc-authentication).

## Useful resources

- [Discord Developer Documentation](https://discord.com/developers/docs)
- [Discord OAuth2 Guide](https://discord.com/developers/docs/topics/oauth2)
- [Discord Applications](https://discord.com/developers/applications)
- [Discord API Reference](https://discord.com/developers/docs/reference)
