mirror of
https://github.com/kyantech/Palmr.git
synced 2025-10-23 16:14:18 +00:00
316 lines
14 KiB
Plaintext
316 lines
14 KiB
Plaintext
---
|
|
title: OIDC Authentication
|
|
icon: Key
|
|
---
|
|
|
|
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
|
|
|
|
|
|
|
|
### 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`.
|
|
|
|
|
|
|
|
### 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](https://console.cloud.google.com/) 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`
|
|
|
|
|
|
|
|
### Zitadel
|
|
1. **Create New ProjectApp**: In your desired Zitadel project, create a new application
|
|
2. **Name and Type**: Give your application a name and choose **WEB** as the application type
|
|
3. **Authentication Method**: Choose Code
|
|
4. **Set Redirect URI**: Add your Palmr callback URL to valid redirect URIs
|
|
5. **Finish**: After reviewing the configuration create the application
|
|
6. **Copy the client ID and client Secrat**: Copy the client id paste it into the **Client ID** of your Palmr OIDC condiguration Form, repeat for the client secret and paste it into the **Client Secret** field
|
|
7. **Obtain your Provider URL**: In your Zitadel application go to **URLs** and copy the **Authorization Endpoint (remove the /authorize from that url)** e.g. https://auth.example.com/oauth/v2
|
|
|
|
**Configuration values:**
|
|
|
|
- **Issuer URL**: Depends on your Zitadel installation and project. Example: `https://auth.example.com/oauth/v2`
|
|
- **Scope**: `openid profile email`
|
|
|
|
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
|
|
|
|
### 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.
|
|
|
|
|
|
|
|
---
|
|
|
|
## 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.
|