diff --git a/docs/Configuration/Configuration.md b/docs/Configuration/Configuration.md index ebbf698..b00f9d5 100644 --- a/docs/Configuration/Configuration.md +++ b/docs/Configuration/Configuration.md @@ -77,6 +77,32 @@ LANGS=en_GB # Available languages SYSTEM_DEFAULTLOCALE=en-GB # Default language ``` +**How language selection works:** + +Stirling-PDF determines the interface language using this priority order: + +1. **User's manual selection** (highest priority) + - When a user clicks the language globe icon and selects a language + - Choice is stored in browser's localStorage (persists across sessions) + - Storage key: `i18nextLng` + +2. **Browser's language preference** + - Automatically detected from browser's `Accept-Language` header via the `navigator` API + - Example: Firefox set to Swedish (sv-SE) will show Swedish UI + +3. **System default locale** (lowest priority) + - Set via `SYSTEM_DEFAULTLOCALE` or `system.defaultLocale` + - Only applied if user has no localStorage preference (first-time visitors) + +**Example:** +- Config: `SYSTEM_DEFAULTLOCALE=en_GB` +- Browser: Swedish (sv-SE) +- Result: UI shows Swedish (browser preference overrides config) + +To force a specific default language regardless of browser settings, users must manually select it via the language globe icon. + +> 💡 **Tip**: Set `SYSTEM_DEFAULTLOCALE` to your organization's primary language. Users can always override it using the language selector in the top-right corner. + ### Deployment Mode ```bash diff --git a/docs/Configuration/External Database.md b/docs/Configuration/External Database.md index ba2e203..2ebb343 100644 --- a/docs/Configuration/External Database.md +++ b/docs/Configuration/External Database.md @@ -26,7 +26,7 @@ You can configure the new `Datasource` property in your `settings.yml` to connec ```yaml datasource: enableCustomDatabase: false - customDatabaseUrl: jdbc:postgresql://localhost:5432/postgres + customDatabackendUrl: jdbc:postgresql://localhost:5432/postgres username: postgres password: postgres type: postgresql @@ -36,7 +36,7 @@ You can configure the new `Datasource` property in your `settings.yml` to connec ``` - `enableCustomDatabase`: Set this property to `true` to enable use of the custom database **Note: An enterprise license to use this feature** -- `customDatabaseUrl`: Enter the database connection url for the database here. **Note: If you set the `customDatabaseUrl` you do not need to set the type, hostName, port and name, they will all be automatically derived from the url.** +- `customDatabackendUrl`: Enter the database connection url for the database here. **Note: If you set the `customDatabackendUrl` you do not need to set the type, hostName, port and name, they will all be automatically derived from the url.** - `username`: The username for the database - `password`: The password for the database @@ -80,7 +80,7 @@ services: environment: DISABLE_ADDITIONAL_FEATURES: "false" "true" SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE: "true" - SYSTEM_DATASOURCE_CUSTOMDATABASEURL: "jdbc:postgresql://db:5432/stirling_pdf" + SYSTEM_DATASOURCE_CUSTOMDATABACKENDURL: "jdbc:postgresql://db:5432/stirling_pdf" SYSTEM_DATASOURCE_USERNAME: "admin" SYSTEM_DATASOURCE_PASSWORD: "stirling" # further configuration @@ -89,7 +89,7 @@ services: - `depends_on`: This specifies any services that your app will need in order to run. Ensure the name matches the container name for your database - `DISABLE_ADDITIONAL_FEATURES`: Set this to `false` to enable security features - `SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE`: An environment variable to connect to the database container. Set this to `true` to enable use of the external database -- `SYSTEM_DATASOURCE_CUSTOMDATABASEURL`: An environment variable to connect to the database container. Set the connection url for the database here. **Note: If you set this url you do not need to set the type, hostName, port and name (namely `SYSTEM_DATASOURCE_TYPE`, `SYSTEM_DATASOURCE_HOSTNAME`, `SYSTEM_DATASOURCE_PORT`, `SYSTEM_DATASOURCE_NAME`), they will all be automatically derived from the url.** +- `SYSTEM_DATASOURCE_CUSTOMDATABACKENDURL`: An environment variable to connect to the database container. Set the connection url for the database here. **Note: If you set this url you do not need to set the type, hostName, port and name (namely `SYSTEM_DATASOURCE_TYPE`, `SYSTEM_DATASOURCE_HOSTNAME`, `SYSTEM_DATASOURCE_PORT`, `SYSTEM_DATASOURCE_NAME`), they will all be automatically derived from the url.** - `SYSTEM_DATASOURCE_USERNAME`: An environment variable to connect to the database container. Set the username for the database. Ensure this matches the corresponding property in your database container - `SYSTEM_DATASOURCE_PASSWORD`: An environment variable to connect to the database container. Set the password for the database. Ensure this matches the corresponding property in your database container @@ -103,7 +103,7 @@ services: environment: DISABLE_ADDITIONAL_FEATURES: "false" "true" SYSTEM_DATASOURCE_ENABLECUSTOMDATABASE: "true" - SYSTEM_DATASOURCE_CUSTOMDATABASEURL: "jdbc:postgresql://db:5432/stirling_pdf" + SYSTEM_DATASOURCE_CUSTOMDATABACKENDURL: "jdbc:postgresql://db:5432/stirling_pdf" SYSTEM_DATASOURCE_USERNAME: "admin" SYSTEM_DATASOURCE_PASSWORD: "stirling" # further configuration diff --git a/docs/Configuration/OAuth SSO Configuration.md b/docs/Configuration/OAuth SSO Configuration.md new file mode 100644 index 0000000..b33c618 --- /dev/null +++ b/docs/Configuration/OAuth SSO Configuration.md @@ -0,0 +1,509 @@ +--- +sidebar_position: 3 +tags: [enterprise, management, feature, advanced feature] +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# OAuth 2.0 Single Sign-On Configuration +> **Tier**: Server + +Stirling-PDF supports Single Sign-On (SSO) using OAuth 2.0 OpenID Connect (OIDC). This allows users to log in using accounts from external providers such as Google, GitHub, Keycloak, Authentik, and others. + +> **Looking for SAML 2.0 SSO?** See [SAML SSO Configuration](./SAML%20SSO%20Configuration/SAML%20SSO%20Configuration.md) (Enterprise tier). + +## Prerequisites + +Before configuring OAuth 2.0 SSO, ensure you have: + +- [ ] Stirling-PDF with login enabled (`security.enableLogin: true`) +- [ ] Valid license for Professional tier or higher +- [ ] An OAuth 2.0 provider account (Google, GitHub, Keycloak, etc.) +- [ ] Registered OAuth application with your provider +- [ ] OAuth Client ID and Client Secret from your provider +- [ ] Public HTTPS URL configured with `system.backendUrl` set to your public backend API URL (often same as frontend, verify `https://your-domain.com/api/v1/info/status` is accessible) +- [ ] Callback URL added to provider: `https://your-domain.com/login/oauth2/code/` + +> **Tip**: Start with `loginMethod: all` during initial setup to allow both username/password and OAuth login. This ensures you can always access the admin account if SSO configuration needs adjustment. + +## Setup Guide + +### Step 1: Configure Login Settings + +Enable login and set the login method to allow both standard and OAuth authentication during initial setup. + + + + ```yaml + security: + enableLogin: true + loginMethod: all # Allows both username/password and OAuth login + ``` + + + ```bash + SECURITY_ENABLELOGIN=true + SECURITY_LOGINMETHOD=all + ``` + + + +**Login Method Options:** +- `all`: Enables all login methods (username/password + OAuth 2) +- `normal`: Username/password only +- `oauth2`: OAuth 2 SSO only (disables username/password login) +- `saml2`: SAML 2 SSO only (Enterprise tier) + +### Step 2: Create Initial Admin Account + +Before enabling OAuth, create an initial admin account using one of these methods: + +**Option A: Use initialLogin credentials** (recommended for first setup) + + + + ```yaml + security: + initialLogin: + username: 'admin' + password: 'yourSecurePassword123' + ``` + + + ```bash + SECURITY_INITIALLOGIN_USERNAME=admin + SECURITY_INITIALLOGIN_PASSWORD=yourSecurePassword123 + ``` + + + +**Option B: Create admin manually** +1. Access Stirling-PDF with OAuth disabled +2. Create an admin user through the UI +3. Then enable OAuth + +### Step 3: Configure OAuth Provider + +Set `security.oauth2.enabled` to `true` and configure your chosen provider. + + + + + + ```yaml + security: + oauth2: + enabled: true + client: + google: + clientId: + clientSecret: + scopes: email, profile + useAsUsername: email + provider: google + autoCreateUser: true + blockRegistration: false + ``` + + + ```bash + SECURITY_OAUTH2_ENABLED=true + SECURITY_OAUTH2_CLIENT_GOOGLE_CLIENTID= + SECURITY_OAUTH2_CLIENT_GOOGLE_CLIENTSECRET= + SECURITY_OAUTH2_CLIENT_GOOGLE_SCOPES=email, profile + SECURITY_OAUTH2_CLIENT_GOOGLE_USEASUSERNAME=email + SECURITY_OAUTH2_PROVIDER=google + SECURITY_OAUTH2_AUTOCREATEUSER=true + SECURITY_OAUTH2_BLOCKREGISTRATION=false + ``` + + + + **Provider Setup:** + 1. Go to [Google Cloud Console](https://console.cloud.google.com/) + 2. Create a new project or select existing + 3. Enable Google+ API + 4. Create OAuth 2.0 credentials (Web application) + 5. Add authorized redirect URI: `https://your-domain.com/login/oauth2/code/google` + 6. Copy Client ID and Client Secret + + + + + ```yaml + security: + oauth2: + enabled: true + client: + github: + clientId: + clientSecret: + scopes: read:user + useAsUsername: login + provider: github + autoCreateUser: true + blockRegistration: false + ``` + + + ```bash + SECURITY_OAUTH2_ENABLED=true + SECURITY_OAUTH2_CLIENT_GITHUB_CLIENTID= + SECURITY_OAUTH2_CLIENT_GITHUB_CLIENTSECRET= + SECURITY_OAUTH2_CLIENT_GITHUB_SCOPES=read:user + SECURITY_OAUTH2_CLIENT_GITHUB_USEASUSERNAME=login + SECURITY_OAUTH2_PROVIDER=github + SECURITY_OAUTH2_AUTOCREATEUSER=true + SECURITY_OAUTH2_BLOCKREGISTRATION=false + ``` + + + + **Provider Setup:** + 1. Go to [GitHub Developer Settings](https://github.com/settings/developers) + 2. Create new OAuth App + 3. Set Authorization callback URL: `https://your-domain.com/login/oauth2/code/github` + 4. Copy Client ID and generate Client Secret + + + + + ```yaml + security: + oauth2: + enabled: true + issuer: https://your-keycloak.com/realms/your-realm + clientId: + clientSecret: + scopes: openid, profile, email + useAsUsername: preferred_username + provider: keycloak + autoCreateUser: true + blockRegistration: false + ``` + + + ```bash + SECURITY_OAUTH2_ENABLED=true + SECURITY_OAUTH2_ISSUER=https://your-keycloak.com/realms/your-realm + SECURITY_OAUTH2_CLIENTID= + SECURITY_OAUTH2_CLIENTSECRET= + SECURITY_OAUTH2_SCOPES=openid, profile, email + SECURITY_OAUTH2_USEASUSERNAME=preferred_username + SECURITY_OAUTH2_PROVIDER=keycloak + SECURITY_OAUTH2_AUTOCREATEUSER=true + SECURITY_OAUTH2_BLOCKREGISTRATION=false + ``` + + + + **Provider Setup:** + 1. Access your Keycloak admin console + 2. Select your realm + 3. Create new client (OpenID Connect) + 4. Set Valid Redirect URIs: `https://your-domain.com/login/oauth2/code/keycloak` + 5. Enable "Client authentication" for confidential access + 6. Copy Client ID and Client Secret from Credentials tab + + + + + ```yaml + security: + oauth2: + enabled: true + issuer: https://your-authentik.com/application/o/stirling-pdf/ + clientId: + clientSecret: + scopes: openid, profile, email + useAsUsername: preferred_username + provider: authentik + autoCreateUser: true + blockRegistration: false + ``` + + + ```bash + SECURITY_OAUTH2_ENABLED=true + SECURITY_OAUTH2_ISSUER=https://your-authentik.com/application/o/stirling-pdf/ + SECURITY_OAUTH2_CLIENTID= + SECURITY_OAUTH2_CLIENTSECRET= + SECURITY_OAUTH2_SCOPES=openid, profile, email + SECURITY_OAUTH2_USEASUSERNAME=preferred_username + SECURITY_OAUTH2_PROVIDER=authentik + SECURITY_OAUTH2_AUTOCREATEUSER=true + SECURITY_OAUTH2_BLOCKREGISTRATION=false + ``` + + + + **Provider Setup:** + 1. Create new Provider (OAuth2/OpenID) + 2. Create new Application + 3. Set Redirect URIs: `https://your-domain.com/login/oauth2/code/authentik` + 4. Copy Client ID and Client Secret + + + + + ```yaml + security: + oauth2: + enabled: true + issuer: + clientId: + clientSecret: + scopes: openid, profile, email + useAsUsername: email + provider: + autoCreateUser: true + blockRegistration: false + ``` + + + ```bash + SECURITY_OAUTH2_ENABLED=true + SECURITY_OAUTH2_ISSUER= + SECURITY_OAUTH2_CLIENTID= + SECURITY_OAUTH2_CLIENTSECRET= + SECURITY_OAUTH2_SCOPES=openid, profile, email + SECURITY_OAUTH2_USEASUSERNAME=email + SECURITY_OAUTH2_PROVIDER= + SECURITY_OAUTH2_AUTOCREATEUSER=true + SECURITY_OAUTH2_BLOCKREGISTRATION=false + ``` + + + + **Requirements:** + - Provider must support OpenID Connect Discovery + - Must expose `/.well-known/openid-configuration` endpoint + + + +### Step 4: Configure Callback URL + +When registering your application with the OAuth provider, use this callback URL format: + +``` +https:///login/oauth2/code/ +``` + +**Understanding the Provider Slug:** + +The `` portion of the callback URL must exactly match your `security.oauth2.provider` configuration value: + +```yaml +security: + oauth2: + provider: authentik # This becomes part of the callback URL +``` + +With the above configuration, your callback URL becomes: +``` +https://your-domain.com/login/oauth2/code/authentik +``` + +**Examples:** +- Google: `https://stirling.example.com/login/oauth2/code/google` +- GitHub: `https://stirling.example.com/login/oauth2/code/github` +- Keycloak: `https://stirling.example.com/login/oauth2/code/keycloak` +- Custom provider: `https://stirling.example.com/login/oauth2/code/mycompany` + +> **Important**: If the provider slug in the callback URL doesn't match your `security.oauth2.provider` value, OAuth login will fail with redirect errors. + +> **Tip**: For generic OIDC providers (not Google/GitHub/Keycloak), you can set `provider` to any lowercase alphanumeric value that makes sense for your organization. + +### Step 5: Test OAuth Login and Promote User + +1. Restart Stirling-PDF +2. Test OAuth login in an incognito/private browser window +3. Verify you can log in with your OAuth provider +4. Log in with your initial admin account (username/password) +5. Go to **Settings** → **User Management** +6. Find the OAuth user account (created during test login) +7. Change role to **Admin** + +### Step 6: (Optional) Switch to SSO-Only Mode + +Once you've verified OAuth works and promoted an OAuth user to admin, you can disable username/password login: + + + + ```yaml + security: + loginMethod: oauth2 # Disables username/password login + ``` + + + ```bash + SECURITY_LOGINMETHOD=oauth2 + ``` + + + +> **Important**: If you set `loginMethod: oauth2` before creating an OAuth admin user, you will only be able to log in via OAuth, and all new OAuth users will have regular user permissions. Keep `loginMethod: all` until you have at least one OAuth user with admin privileges. + +## Configuration Reference + +### Required Properties + +| Property | Description | Example | +|----------|-------------|---------| +| `security.oauth2.enabled` | Enable OAuth 2 login | `true` | +| `security.oauth2.clientId` | Client ID from your OAuth provider | `stirling-pdf-client` | +| `security.oauth2.clientSecret` | Client Secret from your OAuth provider | `your-secret-key` | +| `security.oauth2.provider` | Provider name | `google`, `github`, `keycloak`, `authentik` | + +### Optional Properties + +| Property | Description | Default | Example | +|----------|-------------|---------|---------| +| `security.oauth2.issuer` | OIDC issuer URL (required for generic providers, must support `/.well-known/openid-configuration`) | - | `https://keycloak.example.com/realms/myrealm` | +| `security.oauth2.autoCreateUser` | Auto-create users on first login | `false` | `true` | +| `security.oauth2.blockRegistration` | Block new user registration, only allow pre-registered users | `false` | `true` | +| `security.oauth2.scopes` | Space or comma-separated list of OAuth scopes | Provider-specific | `openid, profile, email` | +| `security.oauth2.useAsUsername` | Claim to use as username (options depend on provider) | Provider-specific | `email`, `preferred_username`, `login` | + +### Provider-Specific Configuration + +**Named providers** (Google, GitHub, Keycloak): +```yaml +oauth2: + client: + google: # or github, keycloak + clientId: ... + clientSecret: ... +``` + +**Generic providers** (Authentik, custom OIDC): +```yaml +oauth2: + issuer: # Must support OIDC discovery + clientId: ... + clientSecret: ... +``` + +### Username Claim Options + +**Google:** +- `email`, `name`, `given_name`, `family_name` +- See [Google OAuth Scopes](https://developers.google.com/identity/protocols/oauth2/scopes) + +**GitHub:** +- `login`, `email`, `name` +- See [GitHub OAuth Scopes](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) + +**Keycloak/Generic OIDC:** +- `email`, `preferred_username`, `nickname`, `name` + +## Advanced Configuration + +### Backend URL Configuration + +If your Stirling-PDF backend is accessible at a different URL than the frontend, configure the backend URL: + + + + ```yaml + system: + backendUrl: https://stirling-api.example.com + ``` + + + ```bash + SYSTEM_BACKENDURL=https://stirling-api.example.com + ``` + + + +Verify the backend URL is correct by checking that `https://your-domain.com/api/v1/info/status` is accessible. + +### Auto-Login Feature +> **Tier**: Enterprise + +Automatically redirect users to OAuth login page, bypassing the Stirling-PDF login screen. + + + + ```yaml + premium: + proFeatures: + SSOAutoLogin: true + ``` + + + ```bash + PREMIUM_PROFEATURES_SSOAUTOLOGIN=true + ``` + + + +**Behavior:** +- Users are automatically redirected to OAuth provider login +- After 5 failed login attempts (configurable via `security.loginAttemptCount`), auto-redirect is disabled +- Users can still access manual login by navigating directly to `/login` + +### User Interface + +Once OAuth is configured, users will see the SSO login button: + +| ![login-page.png](/img/login-page.png) | ![sso-login-option.png](/img/sso-login-option.png) | +|----------------------------------------|---------------------------------------------------| + +## Troubleshooting + +### Common Issues + +**"OAuth2 authentication error"** +- Verify callback URL matches exactly (including provider slug) +- Check client ID and secret are correct +- Ensure provider allows the configured redirect URI +- Confirm `security.oauth2.provider` matches the provider slug in callback URL + +**"Invalid issuer"** +- Confirm issuer URL is correct +- Test `https://your-issuer/.well-known/openid-configuration` returns valid JSON +- Check network connectivity from Stirling-PDF container to provider + +**"User not created"** +- Set `autoCreateUser: true` +- Check `blockRegistration` is `false` or user is pre-registered +- Verify license allows user count + +**Users redirected to wrong URL** +- Verify `system.backendUrl` is configured correctly +- Test that `https://your-domain.com/api/v1/info/status` is accessible +- Check provider's registered redirect URIs match your domain + +### Debug Logging + +Enable OAuth debug logging to troubleshoot authentication issues. + + + + ```yaml + logging: + level: + org.springframework.security.oauth2: DEBUG + ``` + + + ```bash + LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_SECURITY_OAUTH2=DEBUG + ``` + + + +## Known Limitations + +- OAuth users must be manually promoted to admin role after first login +- Provider discovery requires `/.well-known/openid-configuration` endpoint support +- Auto-login feature requires Enterprise tier + +## See Also + +- [SAML SSO Configuration](./SAML%20SSO%20Configuration/SAML%20SSO%20Configuration.md) - Enterprise SAML 2.0 setup +- [System and Security](./System%20and%20Security.md) - Additional security settings +- [External Database](./External%20Database.md) - User storage configuration diff --git a/docs/Configuration/SAML SSO Configuration/SAML SSO Configuration.md b/docs/Configuration/SAML SSO Configuration/SAML SSO Configuration.md new file mode 100644 index 0000000..25402c1 --- /dev/null +++ b/docs/Configuration/SAML SSO Configuration/SAML SSO Configuration.md @@ -0,0 +1,485 @@ +--- +sidebar_position: 1 +tags: [enterprise, management, feature, advanced feature, saml] +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# SAML 2.0 Single Sign-On Configuration +> **Tier**: Enterprise + +Stirling-PDF supports SAML 2.0 Single Sign-On for enterprise deployments. This allows integration with Identity Providers (IdP) like Okta, Azure AD, Google Workspace, OneLogin, Authentik, and others. + +> **Looking for OAuth 2.0 SSO?** See [OAuth SSO Configuration](../OAuth%20SSO%20Configuration.md) (Server tier). + +## Prerequisites + +Before starting, ensure you have: + +- [ ] **Enterprise license active** - SAML requires Enterprise tier +- [ ] **Configs directory mounted** - Docker volume mounted (e.g., `./configs:/configs:ro`) +- [ ] **Public backend URL configured** - Set `system.backendUrl` to your public backend API URL (often same as frontend, verify `https://your-domain.com/api/v1/info/status` is accessible) +- [ ] **Reverse proxy configured** - Nginx/Traefik/Caddy with X-Forwarded-* headers forwarding +- [ ] **Login enabled** - `security.enableLogin: true` in settings +- [ ] **Admin account ready** - Either existing admin or plan to use `security.initialLogin` credentials +- [ ] **IdP admin access** - Access to your SAML Identity Provider (Okta, Azure AD, etc.) + +> ⚠ī¸ **License Requirement**: SAML 2.0 authentication requires an **ENTERPRISE** license. Existing users created before SAML was license-gated are grandfathered and can continue using SAML with any license tier. + +> 💡 **Tip**: Start with `loginMethod: all` during initial setup to allow both username/password and SAML login. This ensures you can always access the admin account if SAML configuration needs adjustment. + +## Setup Guide + +Follow these steps in order to configure SAML SSO: + +### Step 1: Setup Certificates + +SAML requires 3 certificate files for mutual trust: + +| Certificate | Purpose | Action | +|-------------|---------|--------| +| **SP Private Key** | Sign SAML requests to IdP | Generate with OpenSSL | +| **SP Certificate** | Prove identity to IdP | Generate with OpenSSL, upload to IdP | +| **IdP Certificate** | Verify SAML responses from IdP | Download from your IdP | + +#### 1a. Generate Service Provider (SP) Keypair + +Stirling-PDF needs a keypair to sign SAML requests and verify responses. + +> ℹī¸ **If you don't have a keypair**, generate one using OpenSSL: +> +> ```bash +> openssl req -newkey rsa:2048 -nodes \ +> -keyout private_key.key \ +> -x509 -days 365 \ +> -out certificate.crt \ +> -subj "/C=US/ST=State/L=City/O=Stirling-PDF/CN=your-domain.com" +> ``` +> +> **Command explanation:** +> - `rsa:2048`: Generates 2048-bit RSA key (secure standard) +> - `-nodes`: No passphrase (required for automated systems) +> - `-days 365`: Certificate valid for 1 year +> - Creates two files: `private_key.key` (private) and `certificate.crt` (public) + +If you already have a keypair, ensure you have both the private key and certificate files ready. + +#### 1b. Download IdP Certificate + +1. Go to your IdP admin panel +2. Find SAML app/provider settings +3. Download signing certificate (PEM format) +4. Save as `idp-certificate.pem` + +#### 1c. Place Certificates in Mounted Directory + +Place all 3 certificates inside your mounted configs directory: + +``` +./configs/ + ├── private_key.key ← SP private key (keep secure!) + ├── certificate.crt ← SP certificate (will upload to IdP) + └── idp-certificate.pem ← IdP certificate (downloaded) +``` + +> ⚠ī¸ **Critical**: Use absolute paths in configuration: `/configs/filename.pem` (no `file:` or `classpath:` prefix for Docker) + +### Step 2: Configure Stirling-PDF + +Configure SAML authentication by providing: +- **IdP URLs and certificate** - Get these from your Identity Provider (obtained from IdP admin panel) +- **SP certificates** - Point to the certificate files created in Step 1 +- **Backend URL** - Your public backend API URL for SAML callbacks (often same as frontend, e.g., `https://stirling.example.com`) +- **Login settings** - Enable login and set method to `all` (allows both username/password and SAML during setup) + +**Key configuration options:** +- `autoCreateUser: true` - Automatically create user accounts on first SAML login +- `blockRegistration: false` - Allow new SAML users (set to `true` to require admin pre-approval) +- `registrationId: stirling` - Identifier used in SAML URLs (must match across all URLs) + + + + Edit `/configs/settings.yml`: + + ```yaml + security: + enableLogin: true + loginMethod: all # Keep 'all' during initial setup + + saml2: + enabled: true + autoCreateUser: true + blockRegistration: false + registrationId: stirling + + # Identity Provider (IdP) URLs (get from your IdP) + idpSingleLoginUrl: https://idp.example.com/saml/login + idpSingleLogoutUrl: https://idp.example.com/saml/logout + idpIssuer: https://idp.example.com/entityid + idpCert: /configs/idp-certificate.pem + + # Service Provider (SP) Certificates + privateKey: /configs/private_key.key + spCert: /configs/certificate.crt + + # Required for SAML callback URLs + system: + backendUrl: https://stirling.example.com + ``` + + + Add to your `docker-compose.yml` or Docker run command: + + ```yaml + environment: + SYSTEM_BACKENDURL: https://stirling.example.com + SECURITY_ENABLELOGIN: true + SECURITY_LOGINMETHOD: all + SECURITY_SAML2_ENABLED: true + SECURITY_SAML2_AUTOCREATEUSER: true + SECURITY_SAML2_BLOCKREGISTRATION: false + SECURITY_SAML2_REGISTRATIONID: stirling + SECURITY_SAML2_IDPSINGLELOGINURL: https://idp.example.com/saml/login + SECURITY_SAML2_IDPSINGLELOGOUTURL: https://idp.example.com/saml/logout + SECURITY_SAML2_IDPISSUER: https://idp.example.com/entityid + SECURITY_SAML2_IDPCERT: /configs/idp-certificate.pem + SECURITY_SAML2_PRIVATEKEY: /configs/private_key.key + SECURITY_SAML2_SPCERT: /configs/certificate.crt + ``` + + + +> 💡 **Tip**: Replace the example URLs (`idp.example.com`) with actual values from your Identity Provider. + +#### Additional Configuration: baseUrl for SAML SLO + +For Single Logout (SLO) to work correctly in production, you must also set the `baseUrl` property: + + + + Add to `/configs/custom_settings.yml`: + + ```yaml + baseUrl: "https://your-domain.com" + ``` + + + Add to your Docker Compose environment variables: + + ```yaml + environment: + baseUrl: "https://your-domain.com" + ``` + + + +> ⚠ī¸ **Important**: Both `system.backendUrl` and `baseUrl` should be set to your public-facing URL for SAML to work correctly in production. + +### Step 3: Configure Your Identity Provider + +Provide your IdP with these Service Provider details: + +**Entity ID / SP Metadata URL:** +``` +https://your-domain.com/saml2/service-provider-metadata/stirling +``` + +**Assertion Consumer Service (ACS) URL:** +``` +https://your-domain.com/login/saml2/sso/stirling +``` + +**Single Logout (SLO) URL:** +``` +https://your-domain.com/logout +``` + +> 📌 **Important**: Replace `stirling` with your `registrationId` value if you changed it. The registration ID must match in all URLs. + +**Upload SP Certificate to IdP** (Critical Step): +1. Open `certificate.crt` (your SP public certificate) +2. In your IdP's SAML app configuration, find "Verification Certificate" or "SP Certificate" field +3. Upload or paste `certificate.crt` contents +4. Save IdP configuration + +> Without uploading the SP certificate, your IdP cannot verify requests from Stirling-PDF. + +**Configure NameID and Attributes:** +- NameID format: `email` or `unspecified` +- Ensure at least one username attribute is sent: `username`, `emailaddress`, `name`, `upn`, or `uid` + +### Step 4: Test SAML Login + +1. Open an incognito/private browser window +2. Navigate to `https://your-domain.com` +3. Click "Login via Single Sign-On" button +4. You'll be redirected to your IdP login page +5. Enter your IdP credentials +6. You'll be redirected back to Stirling-PDF +7. A new user account is automatically created (if `autoCreateUser: true`) + +> ⚠ī¸ **If login fails**, check application logs for SAML errors. See [Troubleshooting](#troubleshooting) section. + +### Step 5: Promote SAML User to Admin + +1. Log in with your initial admin account (username/password) +2. Go to **Settings** → **User Management** +3. Find the SAML user account (created during test login) +4. Change **Role** to **Admin** +5. **Save** + +> ⚠ī¸ **Important**: Keep at least one SAML user with admin privileges before switching to SSO-only mode. + +### Step 6 (Optional): Switch to SSO-Only Mode + +Once you've verified SAML works and have a SAML admin user: + +```yaml +security: + loginMethod: saml2 # Disables username/password login +``` + +Restart Stirling-PDF. + +## Configuration Reference + +### Required Properties + +| Property | Description | Example | +|----------|-------------|---------| +| `security.saml2.enabled` | Enable SAML 2 authentication | `true` | +| `security.saml2.idpSingleLoginUrl` | IdP's Single Sign-On URL | `https://idp.example.com/sso` | +| `security.saml2.idpSingleLogoutUrl` | IdP's Single Logout URL | `https://idp.example.com/slo` | +| `security.saml2.idpIssuer` | IdP's Entity ID / Issuer | `https://idp.example.com` | +| `security.saml2.idpCert` | IdP's signing certificate (PEM format) | `/configs/idp-cert.pem` | +| `security.saml2.privateKey` | Your SP private key | `/configs/private_key.key` | +| `security.saml2.spCert` | Your SP certificate | `/configs/certificate.crt` | +| `system.backendUrl` | Public HTTPS URL for callbacks | `https://stirling.example.com` | + +### Optional Properties + +| Property | Default | Description | +|----------|---------|-------------| +| `security.saml2.autoCreateUser` | `false` | Auto-create users on first SAML login | +| `security.saml2.blockRegistration` | `false` | Block new users (only allow pre-registered) | +| `security.saml2.registrationId` | `stirling` | Registration ID (must match ACS URL path) | +| `security.saml2.provider` | `null` | Optional provider name for logging | +| `security.loginMethod` | `all` | Login method: `all`, `normal`, `oauth2`, `saml2` | + +## Advanced Configuration + +### SAML Attribute Mapping + +Stirling-PDF attempts to determine the username in the following priority order: + +1. **`username`** attribute +2. **`emailaddress`** attribute (or full URI: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`) +3. **`name`** attribute (or full URI: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`) +4. **`upn`** attribute (User Principal Name - often used in Active Directory) +5. **`uid`** attribute (Unix user ID) +6. **NameID** from SAML Subject (fallback if no attributes provided) + +**Minimum requirement:** NameID in the SAML Subject (used as fallback identifier) + +**Recommended:** At least one username attribute from the priority list above + +#### Attribute Debugging + +Enable debug logging to see what attributes your IdP is sending: + + + + Add to `/configs/custom_settings.yml`: + + ```yaml + logging: + level: + stirling.software.proprietary.security.saml2: DEBUG + ``` + + + ```bash + LOGGING_LEVEL_STIRLING_SOFTWARE_PROPRIETARY_SECURITY_SAML2=DEBUG + ``` + + + +Check logs for: +``` +Extracted SAML Attributes: {username=[john.doe], emailaddress=[john.doe@example.com], ...} +``` + +> 💡 **Note**: Currently, Stirling-PDF only uses attributes for username identification. Other attributes (first name, last name, groups, roles) are extracted but not used. + +### Understanding Registration ID + +The `registrationId` is a critical configuration value that becomes part of your SAML URLs: + +```yaml +security: + saml2: + registrationId: stirling # Default value +``` + +With `registrationId: stirling`, your URLs are: +- Metadata: `https://your-domain.com/saml2/service-provider-metadata/stirling` +- ACS: `https://your-domain.com/login/saml2/sso/stirling` + +**If you change the registration ID:** +```yaml +security: + saml2: + registrationId: mycompany # Custom value +``` + +Your URLs become: +- Metadata: `https://your-domain.com/saml2/service-provider-metadata/mycompany` +- ACS: `https://your-domain.com/login/saml2/sso/mycompany` + +> ⚠ī¸ **Critical**: If you change `registrationId` after configuring your IdP, you must update ALL URLs in your IdP configuration. The registration ID must match exactly in all places, or SAML login will fail. + +> 💡 **Recommendation**: Keep the default `stirling` value unless you have a specific reason to change it (e.g., running multiple Stirling-PDF instances with the same IdP). + +### Auto-Login Feature +> **Tier**: Enterprise + +Automatically redirect users to SAML login, bypassing the Stirling-PDF login screen: + +```yaml +premium: + proFeatures: + SSOAutoLogin: true +``` + +**Behavior:** +- Users accessing Stirling-PDF are immediately redirected to IdP +- After 5 failed attempts (configurable via `security.loginAttemptCount`), auto-redirect is disabled +- Users can still manually access `/login` for form login if `loginMethod: all` + +## Troubleshooting + +### "SAML requires Enterprise license" +**Cause**: SAML authentication requires Enterprise tier license. + +**Solution**: +- Verify valid Enterprise license is configured +- Check `premium.enabled=true` in settings +- Existing users created before license enforcement are grandfathered + +### "Invalid SAML response signature" +**Cause**: IdP certificate mismatch or incorrect format. + +**Solution**: +- Verify `idpCert` file matches certificate from IdP +- Ensure certificate is in PEM format (starts with `-----BEGIN CERTIFICATE-----`) +- Re-download certificate from IdP +- Check certificate hasn't expired + +### "ACS URL mismatch" +**Cause**: Redirect URL doesn't match IdP configuration. + +**Solution**: +- Verify `SYSTEM_BACKENDURL` is set to public HTTPS URL +- Check reverse proxy sends X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port headers +- Ensure `registrationId` matches in both URL and configuration +- Update ACS URL in IdP to match: `https://your-domain.com/login/saml2/sso/stirling` + +### "File not found: idp-certificate.pem" +**Cause**: Certificate file path is incorrect. + +**Solution**: +- Verify file exists at specified path +- For Docker: ensure volume is mounted correctly +- Use absolute paths like `/configs/filename.pem` (no `file:` prefix) +- Check file permissions (must be readable by application) + +### "Cannot auto-create user" +**Cause**: User doesn't exist and auto-creation is disabled. + +**Solution**: +- Set `autoCreateUser: true` to allow new users +- Or pre-create user accounts as admin +- Check license allows additional users + +### "Redirect loop after SAML login" +**Cause**: Session or cookie issues. + +**Solution**: +- Clear browser cookies +- Check `SYSTEM_BACKENDURL` matches actual access URL +- Verify cookies are allowed for domain +- Ensure SameSite cookie settings are compatible + +### "Invalid username" error +**Cause**: No valid username found in assertion. + +**Solution**: +1. Enable debug logging to see what attributes are received +2. Ensure IdP sends at least one of: `username`, `emailaddress`, `name`, `upn`, `uid` +3. Verify NameID is present in SAML Subject as fallback +4. Check attribute name format (short name vs full URI) + +### Debug Logging + +Enable SAML debug logging to see detailed authentication flow: + + + + Add to `/configs/custom_settings.yml`: + + ```yaml + logging: + level: + org.springframework.security.saml2: DEBUG + org.opensaml: DEBUG + stirling.software.proprietary.security: DEBUG + ``` + + + ```bash + LOGGING_LEVEL_ORG_SPRINGFRAMEWORK_SECURITY_SAML2=DEBUG + LOGGING_LEVEL_ORG_OPENSAML=DEBUG + LOGGING_LEVEL_STIRLING_SOFTWARE_PROPRIETARY_SECURITY=DEBUG + ``` + + + +Check logs for SAML attribute information: +``` +Extracted SAML Attributes: {username=[john.doe], emailaddress=[john.doe@example.com], ...} +``` + +### Inspect SAML Assertions + +Use browser developer tools: +1. Open Network tab +2. Clear network log +3. Attempt SAML login +4. Look for POST to `/login/saml2/sso/stirling` +5. Decode SAMLResponse parameter (Base64 + inflate) + +**Tools:** +- [SAML-tracer](https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) (Firefox/Chrome extension) +- [SAML Decoder](https://www.samltool.com/decode.php) (online tool) + +## Known Limitations + +### idpMetadataUri Not Auto-Populating + +The `idpMetadataUri` configuration field exists but is **not currently used** to auto-populate IdP settings. You must manually configure: +- `idpSingleLoginUrl` +- `idpSingleLogoutUrl` +- `idpIssuer` +- `idpCert` + +**Workaround**: Manually extract values from IdP metadata XML. + +> 💡 **Note**: Auto-populating IdP settings from metadata URI is a planned enhancement coming soon. + +## See Also + +- [OAuth SSO Configuration](../OAuth%20SSO%20Configuration.md) - OAuth 2.0 / OIDC setup +- [System and Security](../System%20and%20Security.md) - Additional security settings +- [External Database](../External%20Database.md) - User storage configuration +- [Paid Offerings](../../Paid-Offerings.md) - Enterprise tier and licensing information diff --git a/docs/Configuration/SAML SSO Configuration/_category_.json b/docs/Configuration/SAML SSO Configuration/_category_.json new file mode 100644 index 0000000..c84cd2e --- /dev/null +++ b/docs/Configuration/SAML SSO Configuration/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "SAML SSO Configuration", + "position": 4, + "link": { + "type": "doc", + "id": "Configuration/SAML SSO Configuration/SAML SSO Configuration" + } +} diff --git a/docs/Configuration/Single Sign-On Configuration.md b/docs/Configuration/Single Sign-On Configuration.md index 02ba969..0ecb0aa 100644 --- a/docs/Configuration/Single Sign-On Configuration.md +++ b/docs/Configuration/Single Sign-On Configuration.md @@ -3,329 +3,45 @@ sidebar_position: 3 tags: [enterprise, management, feature, advanced feature] --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; +# Single Sign-On (SSO) Overview -# Single Sign-On (SSO) Configuration -> **Tier**: Enterprise - -Stirling-PDF allows login via Single Sign-On (SSO) using OAuth 2 OpenID Connect (OIDC) and SAML 2. This allows you to log in to the -app using an account you may have with another Provider such as Google or GitHub. - -## OAuth 2 Set Up -To enable OAuth 2 in Stirling-PDF there are a number of properties you must set. Begin by setting `security.enableLogin` -to `true` and `security.loginMethod` to `oauth2` in your `/configs/settings.yml`. - -```yaml -security: - enableLogin: true - ... - loginMethod: all | normal | oauth2 | saml2 -``` - -- `enableLogin`: Set to `true` to enable login -- `loginMethod`: Defines the type of login method that will be used on application start up. The available options are: - - `all`: Enables all login methods (username/password, OAuth 2, SAML 2). Can be used alternatively to `oauth2` - - `normal`: Enables the username/password login method - - `oauth2`: Enables the OAuth 2 login method. Use this if you only want to log in via OAuth 2 - - `saml2`: Enables the SAML 2 login method - -Next, you will need to configure the OAuth 2 properties for your chosen Provider. Start by setting -`security.oauth2.enabled` to `true`. Stirling-PDF supports multiple Providers, in particular -[Google](https://console.cloud.google.com/), [GitHub](https://github.com/settings/developers) and [Keycloak](https://www.keycloak.org/). -You also have the option to use a different Provider apart from the aforementioned if you wish. - -> #### ⚠ī¸ Note -> _The `enableLogin` property must be set to `true` for SSO to work._ - - - - ```yaml - oauth2: - enabled: true - client: - google: - clientId: - clientSecret: - scopes: email, profile - useAsUsername: email | name | given_name | family_name - provider: google - ``` - - - ```yaml - oauth2: - enabled: true - client: - github: - clientId: - clientSecret: - scopes: read:user - useAsUsername: email | login | name - provider: github - ``` - - - ```yaml - oauth2: - enabled: true - client: - keycloak: - issuer: - clientId: - clientSecret: - scopes: openid, profile, email - useAsUsername: email | preferred_name - provider: keycloak - ``` - - - _Using Authentik for example:_ - ```yaml - oauth2: - enabled: true - issuer: - clientId: - clientSecret: - autoCreateUser: true - blockRegistration: false - useAsUsername: email | name | given_name | nickname | preferred_name - scopes: openid, profile, email - provider: authentik - ``` - - - -- `security.oauth2.enabled` Set this to `true` to enable login -- `security.oauth2.issuer` The URL for the Provider's OpenID Configuration. Set this to any Provider that supports an OpenID Connect Discovery `/.well-known/openid-configuration` endpoint -- `security.oauth2.clientId` Client ID from your Provider -- `security.oauth2.clientSecret` Client Secret from your Provider -- `security.oauth2.autoCreateUser` Set this to `true` to allow auto-creation of non-existing users -- `security.oauth2.blockRegistration`: Set to `true` to deny login with SSO without prior registration by an admin -- `security.oauth2.useAsUsername`: The value from the Provider to use as the username for the application. Check with your -Provider for specific options. The default is `email` -- `security.oauth2.scopes`: Specifies the list of scopes for which the application will request permissions. The available scopes -for Google and GitHub can be found [here](https://developers.google.com/identity/protocols/oauth2/scopes#oauth2) and - [here](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes) -- `security.oauth2.provider`: The name of the Provider - -The Callback URL (Redirect URL) for entering in your IdP is: `https:///login/oauth2/code/` eg `https:///login/oauth2/code/keycloak`. If you previously used a bare `/login/oauth2/code/` callback, make sure you now include the provider slug (for example, Authentik uses `/login/oauth2/code/authentik`). -It is highly recommended to use an SSL-enabled reverse-proxy, if the application is going to be exposed to the internet. - -After the OAuth 2 login is enabled, a new button will show up on the login page as per the screenshot below. Clicking the -'Login via Single Sign-On' button will present you with the login for your Provider of choice. Once you have clicked the button, -you will be redirected to your Provider in order to login and authorise Stirling-PDF to use your profile: - -| ![login-page.png](/img/login-page.png) | ![sso-login-option.png](/img/sso-login-option.png) | -|-------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------| +Stirling-PDF supports Single Sign-On (SSO) authentication through two protocols: -## SAML 2 Set Up +## OAuth 2.0 / OpenID Connect (OIDC) +> **Tier**: Server -> #### ⚠ī¸ Note -> _SAML 2 is an enterprise-only feature. To use it you must have `premium.enabled` set to `true` and have a valid license key._ +OAuth 2.0 SSO allows login via popular identity providers like: +- Google +- GitHub +- Keycloak +- Authentik +- Any OIDC-compliant provider -Begin by setting `security.enableLogin` to `true` and `security.loginMethod` to `saml2` in your `/configs/settings.yml`. +**[→ Configure OAuth 2.0 SSO](./OAuth%20SSO%20Configuration.md)** -```yaml -saml2: - enabled: true - provider: - autoCreateUser: true - blockRegistration: false - registrationId: - idpMetadataUri: - idpSingleLoginUrl: - idpSingleLogoutUrl: - idpIssuer: - idpCert: classpath: - privateKey: classpath: - spCert: classpath: -``` +**Key Features:** +- Easy setup with major providers +- Auto-discovery via `.well-known/openid-configuration` +- Social login support +- Suitable for small to medium organizations -- `security.saml2.enabled`: Set to `true` to activate SAML 2 SSO # Only enabled for paid enterprise clients (enterpriseEdition.enabled must be true) -- `security.saml2.autoCreateUser`: Set this to `true` to allow auto-creation of non-existing users -- `security.saml2.blockRegistration`: Set to `true` to deny login with SSO without prior registration by an admin -- `security.saml2.registrationId`: The registration ID for your Provider. Should match the name in the path for your -Assertion Consumer Service (ACS) URL The default is `stirling` -- `security.saml2.idpMetadataUri`: The location of the metadata file from your Provider. Can be a file or URI -- `security.saml2.idpSingleLoginUrl`: The URL given by your Provider to initiate the SSO flow -- `security.saml2.idpSingleLogoutUrl`: The URL given by your Provider to initiate the SLO flow -- `security.saml2.idpIssuer`: The name of your Provider -- `security.saml2.idpCert`: The signing certificate given by your Provider in `.pem` format. Place in `stirling-pdf/src/main/resources` -- `security.saml2.privateKey`: Your private key from your keypair in `.key` format. Place in `stirling-pdf/src/main/resources` -- `security.saml2.spCert`: classpath:certificate.crt from your keypair in `.crt` format. Place in `stirling-pdf/src/main/resources` - -### Generating a Keypair - -To generate a keypair for the app to use for signing and verification, enter this command in your terminal: -```shell -openssl req -newkey rsa:2048 -nodes -keyout private_key.key -x509 -days 365 -out certificate.crt -``` - -- `openssl req`: This starts the OpenSSL command to create or manage a certificate signing request (CSR) or certificate -- `newkey rsa:2048`: This generates a new key pair using the RSA algorithm with a key size of 2048 bits. RSA 2048 is a -common and secure key size -- `nodes`: Skips encrypting the private key (no passphrase). If omitted, you would be prompted to set a password for -the key, which would be required whenever using it. With -nodes, the private key is generated in plain text for easier use in automated systems -- `keyout private_key.key`: Specifies the file name where the private key will be saved -- `x509`: This tells OpenSSL to create a self-signed certificate instead of generating a certificate signing request (CSR) -A self-signed certificate is not verified by a Certificate Authority (CA), which is why browsers may display a security warning when using it -- `days 365`: Specifies the certificate's validity period (in days). In this case, the certificate is valid for 365 days -- `out certificate.crt`: Specifies the output file where the self-signed certificate will be saved - -After generating the keypair, the `.key` and `.crt` files should be located in the directory you executed the above command in. -Move the files to `stirling-pdf/src/main/resources`. - -Once you have added your configuration, you should see the button for your chosen Provider on the login page prompting you to log in: - -| ![sso-login-dark-mode.png](/img/sso-login-dark-mode.png) | ![sso-saml-login.png](/img/sso-saml-login.png) | -|----------------------------------------------------------------------|------------------------------------------------------------| - -### Auto-login -> #### ⚠ī¸ Note -> _Auto Login is an enterprise-only feature. To use it you must have `premium.enabled` set to `true` and have a valid license key._ - -It is also possible to automatically log in to Stirling PDF on start-up using SSO. To enable this feature, set the -property `premium.proFeatures.SSOAutoLogin` to `true`. -This will redirect to your SSO's URL when any user navigates to Stirling-PDF's default login screen. If a login fails 3 times this redirection is disabled - -## Configurations Examples -Below are examples of the full configuration for both OAuth 2 and SAML 2: - - - - ```yaml - security: - enableLogin: true # set to 'true' to enable login - oauth2: - issuer: - clientId: - clientSecret: - autoCreateUser: true - blockRegistration: false - useAsUsername: email - scopes: openid, profile, email - provider: - saml2: - enabled: true - autoCreateUser: true - blockRegistration: false - registrationId: - idpMetadataUri: - idpSingleLoginUrl: - idpSingleLogoutUrl: - idpIssuer: - idpCert: classpath: - privateKey: classpath: - spCert: classpath: - ``` - - - ```bash - export DISABLE_ADDITIONAL_FEATURES=false - export SECURITY_ENABLELOGIN=true - export SECURITY_OAUTH2_ENABLED=true - export SECURITY_OAUTH2_AUTOCREATEUSER=false - export SECURITY_OAUTH2_ISSUER="" - export SECURITY_OAUTH2_CLIENTID="" - export SECURITY_OAUTH2_CLIENTSECRET="" - export SECURITY_OAUTH2_BLOCKREGISTRATION=false - export SECURITY_OAUTH2_SCOPES="openid, profile, email" - export SECURITY_OAUTH2_USEASUSERNAME=email - export SECURITY_OAUTH2_PROVIDER="" +--- - export SECURITY_SAML2_ENABLED=true - export SECURITY_SAML2_AUTOCREATEUSER=false - export SECURITY_SAML2_REGISTRATIONID="" - export SECURITY_SAML2_BLOCKREGISTRATION=false - export SECURITY_SAML2_IDPISSUER="" - export SECURITY_SAML2_IDPMETADATAURI=true - export SECURITY_SAML2_IDPSINGLELOGINURL="" - export SECURITY_SAML2_IDPSINGLELOGOUTURL="" - export SECURITY_SAML2_IDPCERT="" - export SECURITY_SAML2_PRIVATEKEY="" - export SECURITY_SAML2_SPCERT="" - ``` - - - ```bash - -e DISABLE_ADDITIONAL_FEATURES=false \ - -e SECURITY_ENABLELOGIN=true \ - -e SECURITY_OAUTH2_ENABLED=true \ - -e SECURITY_OAUTH2_AUTOCREATEUSER=false \ - -e SECURITY_OAUTH2_ISSUER="" \ - -e SECURITY_OAUTH2_CLIENTID="" \ - -e SECURITY_OAUTH2_CLIENTSECRET="" \ - -e SECURITY_OAUTH2_BLOCKREGISTRATION=false \ - -e SECURITY_OAUTH2_SCOPES="openid, profile, email" \ - -e SECURITY_OAUTH2_USEASUSERNAME=email \ - -e SECURITY_OAUTH2_PROVIDER="" \ - -e SECURITY_SAML2_ENABLED=true \ - -e SECURITY_SAML2_AUTOCREATEUSER=false \ - -e SECURITY_SAML2_BLOCKREGISTRATION=false \ - -e SECURITY_SAML2_REGISTRATIONID="" \ - -e SECURITY_SAML2_IDPISSUER="" \ - -e SECURITY_SAML2_IDPMETADATAURI="" \ - -e SECURITY_SAML2_IDPSINGLELOGINURL="" \ - -e SECURITY_SAML2_IDPSINGLELOGOUTURL="" \ - -e SECURITY_SAML2_IDPCERT="" \ - -e SECURITY_SAML2_PRIVATEKEY="" \ - -e SECURITY_SAML2_SPCERT="" \ - ``` - - - ```yaml - environment: - DISABLE_ADDITIONAL_FEATURES=false - SECURITY_ENABLELOGIN=true - SECURITY_OAUTH2_ENABLED=true - SECURITY_OAUTH2_AUTOCREATEUSER=false - SECURITY_OAUTH2_ISSUER="" - SECURITY_OAUTH2_CLIENTID="" - SECURITY_OAUTH2_CLIENTSECRET="" - SECURITY_OAUTH2_BLOCKREGISTRATION=false - SECURITY_OAUTH2_SCOPES="openid, profile, email" - SECURITY_OAUTH2_USEASUSERNAME=email - SECURITY_OAUTH2_PROVIDER="" +## SAML 2.0 +> **Tier**: Enterprise - SECURITY_SAML2_ENABLED=true - SECURITY_SAML2_AUTOCREATEUSER=false - SECURITY_SAML2_REGISTRATIONID= - SECURITY_SAML2_BLOCKREGISTRATION=false - SECURITY_SAML2_IDPISSUER="" - SECURITY_SAML2_IDPMETADATAURI=true - SECURITY_SAML2_IDPSINGLELOGINURL="" - SECURITY_SAML2_IDPSINGLELOGOUTURLSECURITY_SAML2_IDPSINGLELOGOUTURL="" - SECURITY_SAML2_IDPCERT="" - SECURITY_SAML2_PRIVATEKEY="" - SECURITY_SAML2_SPCERT="" - ``` - - +SAML 2.0 SSO provides enterprise-grade authentication with: +- Okta +- Azure AD (Entra ID) +- Google Workspace +- OneLogin +- Any SAML 2.0-compliant IdP -# Disable Form Login +**[→ Configure SAML 2.0 SSO](./SAML%20SSO%20Configuration/SAML%20SSO%20Configuration.md)** -Once you successfully enabled Single Sign-on (with OAuth2 or SAML), you might want to disable the form login. -This can be done by changing the ``loginMethod`` setting accordingly to your needs, like so: +**Key Features:** +- Enterprise identity provider integration +- Advanced security controls +- Single Logout (SLO) support +- Suitable for large organizations - - - ```yaml - security: - ... - loginMethod: oauth2 # Accepts values like 'all' and 'normal'(only Login with Username/Password), 'oauth2'(only - ``` - - - ```bash - -e SECURITY_LOGINMETHOD="oauth2" # to enable oauth2 only - ``` - - - ```yaml - environment: - ... - SECURITY_LOGINMETHOD: "oauth2" # to enable oauth2 only - ``` - - diff --git a/docs/Configuration/System and Security.md b/docs/Configuration/System and Security.md index a38fc74..9a5e19f 100644 --- a/docs/Configuration/System and Security.md +++ b/docs/Configuration/System and Security.md @@ -284,6 +284,20 @@ If migrating from V1, note these setting name changes: Configure SMTP for sending email invitations and notifications. Enable `mail.enableInvites` to allow invitation links. +> 💡 **When is email configuration required?** +> +> Email configuration is **OPTIONAL** and only needed for: +> - **Email invitations**: Admins can send invite links to users via email +> - **Password reset emails**: Users can reset forgotten passwords (if implemented) +> +> Email is **NOT required** for: +> - Basic username/password login +> - SSO authentication (OAuth 2.0 or SAML 2.0) +> - Manual user creation by admins +> - Normal application operation +> +> You can run Stirling-PDF without any email configuration if you create users manually or use SSO. + ### Email Invites Enable email-based user invitations: