Palmr.

OIDC Authentication

Palmr supports OpenID Connect (OIDC) authentication, allowing users to sign in using external identity providers such as Google, Microsoft Azure AD, Keycloak, Auth0, and other OIDC-compliant services. This feature provides seamless single sign-on (SSO) capabilities and centralized user management.

OIDC authentication in Palmr is built using the industry-standard OpenID Connect protocol with PKCE (Proof Key for Code Exchange) for enhanced security. The implementation supports automatic user provisioning, role mapping, and flexible configuration options.

Why use OIDC authentication?

OIDC authentication provides several advantages for organizations and users:

Centralized Authentication: Users can authenticate using their existing organizational credentials without creating separate accounts for Palmr.

Enhanced Security: OIDC provides robust security features including token-based authentication, PKCE flow, and standardized protocols.

Single Sign-On: Users can access Palmr seamlessly if they're already authenticated with their identity provider.

User Management: Administrators can manage user access centrally through their existing identity provider.

Compliance: OIDC helps meet organizational security and compliance requirements by leveraging existing identity infrastructure.

Prerequisites

Before configuring OIDC authentication, ensure you have:

  • Administrative Access: ADMIN privileges in Palmr to configure OIDC settings
  • Identity Provider: An OIDC-compliant identity provider (Google, Azure AD, Keycloak, etc.)
  • Application Registration: Your Palmr application registered with your identity provider
  • OIDC Credentials: Client ID, Client Secret, and Issuer URL from your identity provider

Supported identity providers

Palmr's OIDC implementation is compatible with any OpenID Connect 1.0 compliant provider, including:

  • Google Workspace / Google Cloud Identity
  • Microsoft Azure Active Directory / Entra ID
  • Keycloak
  • Auth0
  • Okta
  • AWS Cognito
  • Custom OIDC providers

Configuring OIDC settings

OIDC configuration is managed through Palmr's administrative settings panel, accessible only to users with ADMIN privileges.

Accessing OIDC configuration

To configure OIDC authentication:

  1. Access Settings: Click on your profile picture in the header and select Settings
  2. Navigate to Authentication: Find the Authentication or OIDC configuration section
  3. Enable OIDC: Toggle the OIDC authentication option to enable it

OIDC Settings Panel

Required configuration fields

Configure the following essential fields for OIDC authentication:

OIDC Enabled: Enable or disable OIDC authentication for your Palmr instance.

Issuer URL: The base URL of your OIDC identity provider. This is typically the discovery endpoint URL without the /.well-known/openid-configuration suffix.

  • Example: https://accounts.google.com
  • Example: https://login.microsoftonline.com/{tenant-id}/v2.0

Client ID: The unique identifier for your Palmr application as registered with your identity provider.

Client Secret: The secret key provided by your identity provider for your Palmr application. Store this securely and never share it.

Redirect URI: The callback URL where users will be redirected after authentication. This is typically auto-detected but can be manually configured if needed.

  • Format: https://your-palmr-domain.com/api/auth/oidc/callback

Scope: The OpenID Connect scopes to request from the identity provider. Default is openid profile email.

![OIDC Configuration Fields](/assets/v3/oidc/provider setup.png)

Advanced configuration options

Auto-Registration: Configure whether new users can be automatically created when they authenticate via OIDC for the first time.

Admin Email Domains: Specify email domains that should automatically receive admin privileges when registering via OIDC.

User Attribute Mapping: Configure how user attributes from the OIDC provider map to Palmr user fields.

Setting up identity providers

The setup process varies depending on your chosen identity provider. Here are examples for common providers:

Google Workspace / Google Cloud

  1. Create Project: Go to the Google Cloud Console and create a new project
  2. Enable APIs: Enable the Google+ API and OpenID Connect API
  3. Create Credentials: Create OAuth 2.0 credentials for a web application
  4. Configure Redirect URI: Add your Palmr callback URL to authorized redirect URIs
  5. Note Credentials: Copy the Client ID and Client Secret for Palmr configuration

Configuration values:

  • Issuer URL: https://accounts.google.com
  • Scope: openid profile email

Microsoft Azure AD / Entra ID

  1. Register Application: Go to Azure Portal > Azure Active Directory > App registrations
  2. Create Registration: Register a new application with web platform
  3. Configure Authentication: Add your Palmr callback URL to redirect URIs
  4. Create Secret: Generate a client secret in Certificates & secrets
  5. Note Configuration: Copy Application (client) ID and Directory (tenant) ID

Configuration values:

  • Issuer URL: https://login.microsoftonline.com/{tenant-id}/v2.0
  • Scope: openid profile email

Keycloak

  1. Create Client: In your Keycloak realm, create a new OpenID Connect client
  2. Configure Client: Set access type to confidential and enable standard flow
  3. Set Redirect URI: Add your Palmr callback URL to valid redirect URIs
  4. Generate Secret: Note the client secret from the Credentials tab

Configuration values:

  • Issuer URL: https://your-keycloak-domain.com/realms/{realm-name}
  • Scope: openid profile email

Identity Provider Setup

Testing OIDC configuration

After configuring OIDC settings, it's important to test the authentication flow to ensure everything works correctly.

Validation steps

  1. Save Configuration: Apply your OIDC settings in the Palmr admin panel
  2. Check Status: Verify that OIDC is enabled and properly configured
  3. Test Login Flow: Attempt to log in using the OIDC provider
  4. Verify User Creation: Confirm that user accounts are created or updated correctly

Testing the authentication flow

  1. Access Login Page: Navigate to your Palmr login page
  2. OIDC Login Option: Look for the OIDC/SSO login button or option
  3. Provider Redirect: Click the OIDC login option to redirect to your identity provider
  4. Authenticate: Complete authentication with your identity provider
  5. Return to Palmr: Verify successful redirect back to Palmr with authentication

OIDC Login Flow

Troubleshooting common issues

Configuration Errors:

  • Verify that all required fields are filled correctly
  • Check that the Issuer URL is accessible and returns valid OIDC metadata
  • Ensure Client ID and Client Secret match your identity provider configuration

Redirect URI Mismatches:

  • Confirm that the redirect URI in Palmr matches what's configured in your identity provider
  • Check for protocol mismatches (HTTP vs HTTPS)
  • Verify that the domain and path are exactly correct

Authentication Failures:

  • Check that the user exists in your identity provider
  • Verify that required scopes are granted
  • Ensure the user has necessary permissions in the identity provider

User Creation Issues:

  • Confirm that auto-registration is enabled if you want new users to be created automatically
  • Check that email addresses are provided by the identity provider
  • Verify admin domain configuration if users should receive admin privileges

User experience

Once OIDC is properly configured, users will have a seamless authentication experience integrated into Palmr's login flow.

Login process

  1. Access Palmr: Users navigate to the Palmr login page
  2. Choose OIDC: Users select the OIDC/SSO login option
  3. Provider Authentication: Users are redirected to authenticate with their identity provider
  4. Automatic Return: After successful authentication, users are automatically redirected back to Palmr
  5. Dashboard Access: Users gain immediate access to their Palmr dashboard

User account management

Automatic Provisioning: New users are automatically created when they first authenticate via OIDC (if auto-registration is enabled).

Profile Synchronization: User profile information (name, email) is synchronized from the identity provider during each login.

Role Assignment: User roles and permissions can be automatically assigned based on identity provider attributes or configured rules.

Account unification

Email-Based Matching: If a user authenticates via OIDC using the same email address as an existing credential-based account, both authentication methods will be linked to the same user account.

Dual Authentication Options: Users who have both credential-based and OIDC authentication set up can choose either method to log in:

  • Traditional email/password authentication
  • OIDC/SSO authentication through their identity provider

Seamless Experience: Regardless of which authentication method is used, users will access the same account with all their files, shares, and settings preserved.

Account Consolidation: This feature ensures that users don't accidentally create duplicate accounts and can transition smoothly between authentication methods as organizational requirements change.

User Dashboard After OIDC Login

Security considerations

OIDC authentication in Palmr implements several security best practices to ensure safe and secure authentication.

Security features

PKCE Flow: Palmr uses Proof Key for Code Exchange (PKCE) to prevent authorization code interception attacks.

State Parameter: Random state parameters are used to prevent CSRF attacks during the authentication flow.

Token Validation: All tokens are properly validated according to OIDC specifications.

Secure Storage: Sensitive configuration data is securely stored and never exposed to client-side code.

Best practices

Use HTTPS: Always configure Palmr and your identity provider to use HTTPS in production environments.

Rotate Secrets: Regularly rotate client secrets and update them in both your identity provider and Palmr configuration.

Monitor Access: Regularly review user access and authentication logs to detect any suspicious activity.

Limit Scopes: Only request the minimum necessary scopes from your identity provider.

Validate Domains: Configure admin email domains carefully to prevent unauthorized privilege escalation.

API endpoints

Palmr provides several API endpoints for OIDC authentication that can be used for integration or troubleshooting.

Available endpoints

GET /api/auth/oidc/config: Retrieve OIDC configuration and status information.

GET /api/auth/oidc/authorize: Initiate the OIDC authorization flow.

GET /api/auth/oidc/callback: Handle the callback from the identity provider after authentication.

Finalizing OIDC configuration

After completing the configuration and testing process, your Palmr installation will be ready to handle OIDC authentication seamlessly.

Configuration completion

Once OIDC is properly configured:

  1. Verify Settings: Confirm all configuration fields are correct and saved
  2. Test Authentication: Perform end-to-end testing of the authentication flow
  3. Document Configuration: Keep a record of your OIDC settings for future reference
  4. Inform Users: Notify users about the new OIDC authentication option

Ongoing maintenance

To maintain reliable OIDC authentication:

  • Monitor Authentication: Regularly check that OIDC authentication is working correctly
  • Update Credentials: Rotate client secrets periodically for security
  • Review User Access: Audit user accounts and permissions regularly
  • Stay Updated: Keep informed about changes to your identity provider's configuration

Next steps

With OIDC properly configured, your Palmr installation now provides:

  • Seamless single sign-on authentication for users
  • Centralized user management through your identity provider
  • Enhanced security through industry-standard protocols
  • Improved user experience with reduced password management

Users can now authenticate using their existing organizational credentials, providing a more streamlined and secure access experience to Palmr's file sharing capabilities.

On this page