Pocket ID

Pocket ID is one of Palmr's officially supported OIDC providers, offering a robust and flexible identity management solution. This integration allows users to sign in to Palmr using Pocket ID's authentication system, making it perfect for organizations that need a self-hosted identity provider with OIDC support.

Why use Pocket ID authentication?

Pocket ID authentication provides several advantages for organizations seeking a self-hosted identity solution:

• Self-hosted control - Full control over your authentication infrastructure and data
• OIDC compliance - Standard OpenID Connect implementation for seamless integration
• Flexible deployment - Deploy on any infrastructure that suits your needs
• Automatic discovery - Supports OIDC discovery for streamlined configuration
• Simple configuration - Intuitive setup process with minimal complexity
• Data sovereignty - Keep all authentication data within your infrastructure
• Cost-effective - No per-user pricing, perfect for growing organizations

Prerequisites

Before configuring Pocket ID authentication, ensure you have:

• Pocket ID instance - A running Pocket ID server accessible via HTTPS
• Admin privileges in Palmr - Required to configure OIDC settings
• Domain configuration - For production deployments with custom domains

Note: Pocket ID 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 Pocket ID Application

Creating a Pocket ID application

To get started with Pocket ID authentication, you'll need to create an application in your Pocket ID admin interface.

1. Navigate to Pocket ID Admin: Go to your Pocket ID instance URL (e.g., https://your-pocket-id.domain.com)

2. Navigate to OIDC Clients: Click "OIDC Clients" in the applications in the left sidebar, you will be redirected to the OIDC Clients page

3. Create a new OIDC Client: Click "Add OIDC Client" button in the OIDC Clients page

Configure the following settings:

• Name: "Palmr File Sharing" (or your preferred name)
• Public Client: "Diasabled"
• PKCE: "Disabled"
• Logo: "Upload a logo image"

Configuring application URLs

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

Redirect URIs

Post Logout Redirect URIs

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).

Getting OAuth credentials

After creating your application, you'll receive your OAuth credentials:

The client ID and client secret shown in the image are examples only (fake credentials). You must use your own credentials from Pocket ID.

Save these credentials securely - you'll need them to configure Palmr:

• Client ID
• Client Secret
• Provider URL (your Pocket ID instance URL)

Configuring Palmr

Accessing OIDC settings

To configure Pocket ID authentication in Palmr:

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 section

Enabling Pocket ID provider

1. Locate Pocket ID: Find Pocket ID in the list of available providers
2. Enable the provider: Toggle the status to Enabled

3. Configure credentials:
   • Provider URL: Your Pocket ID server URL (e.g., https://auth.yourdomain.com)
   • Client ID: Paste the Client ID from your Pocket ID application
   • Client Secret: Paste the Client Secret from your Pocket ID application

This is a fake application, you have to use your own credentials.

Advanced configuration options

Configure additional settings to customize the authentication behavior:

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

Sort Order: Control where the Pocket ID login button appears relative to other authentication providers.

Icon: Choose a custom icon for the Pocket ID login button (default is Key).

Account linking

By default, if a user is already registered in Palmr with their Pocket ID 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 Pocket ID account, you need to delete the user from Palmr.

Technical configuration

Pocket ID's technical configuration is handled automatically through OIDC discovery, but understanding the setup can help with troubleshooting:

Provider Type: OAuth 2.0 with OIDC Discovery
Issuer URL: https://your-pocket-id.domain.com
Authorization Endpoint: /authorize
Token Endpoint: /api/oidc/token
UserInfo Endpoint: /api/oidc/userinfo
Scopes: openid profile email

Field mappings

Palmr automatically maps Pocket ID user information to local user accounts:

• User ID: Maps from Pocket ID's sub field
• Email: Maps from Pocket ID's email field
• Name: Maps from Pocket ID's name field, falls back to preferred_username
• First Name: Maps from Pocket ID's given_name field
• Last Name: Maps from Pocket ID's family_name field
• Avatar: Maps from Pocket ID's picture field

Testing the configuration

Verifying the setup

After configuring Pocket ID authentication, test the integration:

1. Check login page: Verify the "Sign in with Pocket ID" button appears
2. Test authentication flow: Click the button and complete authentication
3. Verify user creation: Confirm new user account creation (if auto-registration is enabled)

Login flow verification

The complete authentication process should work as follows:

1. User clicks "Sign in with Pocket ID"
2. User is redirected to Pocket ID login page
3. User authenticates with their credentials
4. Pocket ID redirects back to Palmr
5. Palmr creates or updates the user account
6. User gains access to Palmr

Troubleshooting common issues

Redirect URI mismatch

Error: invalid_redirect_uri

Solution:

1. Verify the exact callback URL in your Pocket ID application
2. Check for protocol mismatches (http vs https)
3. Ensure no trailing slashes unless specified
4. Add development URLs if testing locally

Authentication failures

Error: access_denied or unauthorized_client

Solution:

1. Verify Client ID and Secret are correct
2. Check if the application is enabled in Pocket ID
3. Ensure required scopes are configured
4. Verify the user has necessary permissions

Discovery endpoint issues

Error: Cannot fetch OIDC configuration

Solution:

1. Verify your Pocket ID server is accessible
2. Check if the discovery endpoint (/.well-known/openid-configuration) is available
3. Ensure SSL certificates are valid
4. Check network connectivity and firewall rules

Security best practices

Credential management

• Secure storage: Keep Client Secret secure and never commit to version control
• Regular rotation: Periodically rotate Client Secret
• Environment variables: Store credentials in environment variables
• Access monitoring: Regular review of authentication logs

Production considerations

• HTTPS required: Always use HTTPS in production
• Valid certificates: Ensure SSL certificates are valid
• Regular updates: Keep Pocket ID server updated
• Backup strategy: Regular backups of Pocket ID configuration

Next steps

After configuring Pocket ID authentication:

• Monitor usage: Track authentication patterns
• Configure MFA: Set up multi-factor authentication if needed
• User management: Review auto-registration settings
• Backup verification: Test backup and restore procedures

For more information about OIDC authentication in Palmr, see the OIDC Authentication overview.

Useful resources

• Pocket ID Documentation
• OIDC Specification
• Palmr OIDC Overview