SSO Authentication¶

Overview¶

KrakenHashes supports Single Sign-On (SSO) authentication, allowing users to log in using their existing enterprise identity providers. This reduces password fatigue, centralizes access control, and improves security through federated authentication.

Supported Provider Types¶

KrakenHashes supports four SSO provider types:

Configuration¶

Global SSO Settings¶

Navigate to Admin Panel → SSO Settings to configure global authentication options:

1. Local Authentication Enabled
2. Toggle to enable/disable username/password login
3. Default: Enabled

4. Warning: Ensure at least one admin has SSO access before disabling

5. Auto-Create Users (JIT Provisioning)

6. When enabled, new users are automatically created on first SSO login
7. Default: Enabled

8. User information is populated from the identity provider

9. Auto-Enable Users

10. When enabled, auto-created users are immediately active
11. Default: Disabled (requires admin approval)
12. When disabled, new users see "Pending Approval" message

Provider-Specific Settings¶

Each provider can override global settings:

• Override Auto-Create: Enable/disable JIT provisioning per provider
• Override Auto-Enable: Enable/disable auto-activation per provider

SSO Encryption Key¶

Purpose¶

The SSO_ENCRYPTION_KEY environment variable protects sensitive SSO secrets stored in the database using AES-256-GCM encryption.

What Gets Encrypted¶

Key Requirements¶

• Size: Exactly 32 bytes (256 bits)
• Format: Base64-encoded string OR raw 32-byte string
• Algorithm: AES-256-GCM with 96-bit random nonce per encryption

Generating a Key¶

# Generate a secure encryption key
openssl rand -base64 32

Example output: K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=

Configuration¶

Add to your environment or .env file:

SSO_ENCRYPTION_KEY=K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=

High Availability Deployments¶

When running multiple backend instances:

• All instances must use the same SSO_ENCRYPTION_KEY
• Store the key in a secrets manager (Vault, AWS Secrets Manager, etc.)
• Rotate keys by re-encrypting all secrets with a new key

LDAP Configuration¶

Basic Setup¶

1. Navigate to Admin Panel → SSO Settings → Add Provider
2. Select LDAP/Active Directory
3. Configure the following:

Attribute Mappings¶

TLS Settings¶

MFA Behavior¶

SAML 2.0 Configuration¶

Prerequisites¶

Before configuring SAML, you'll need from your Identity Provider (IdP):

• IdP Entity ID
• IdP SSO URL
• IdP Certificate (for signature verification)

Basic Setup¶

1. Navigate to Admin Panel → SSO Settings → Add Provider
2. Select SAML 2.0
3. Configure the required fields:

RSA Key Requirements for SAML Trust¶

Service Provider (SP) Keys¶

SP keys are automatically generated when you create or save a SAML provider. This simplifies configuration since manual key generation is no longer required.

Automatic Key Generation:

When you create a new SAML provider or save an existing one without keys, KrakenHashes automatically:

1. Generates a 2048-bit RSA private key
2. Creates a self-signed certificate valid for 10 years
3. Encrypts and stores the private key in the database
4. Makes the certificate available via the SP metadata endpoint

Manual Key Generation (Optional):

If you prefer to use your own keys (e.g., CA-signed certificates), you can still provide them:

Key Format Requirements:

Generating Custom Self-Signed SP Certificates:

# Generate a self-signed certificate valid for 1 year
openssl req -x509 -newkey rsa:2048 \
  -keyout sp-key.pem \
  -out sp-cert.pem \
  -days 365 \
  -nodes \
  -subj "/CN=KrakenHashes SAML SP"

# View the certificate
openssl x509 -in sp-cert.pem -text -noout

• Copy contents of sp-key.pem to SP Private Key field
• Copy contents of sp-cert.pem to SP Certificate field

Identity Provider (IdP) Certificate¶

• Always required for SAML providers
• Used to verify assertion signatures
• Obtain from your IdP's metadata or admin console
• Format: PEM or base64-encoded DER

SP Metadata Endpoint¶

KrakenHashes exposes SP metadata for IdP configuration:

GET /api/auth/saml/{provider_id}/metadata

This endpoint:

• Is publicly accessible (no authentication required)
• Returns XML metadata in SAML 2.0 format
• Includes SP certificate in KeyDescriptor element
• Provides ACS URL and entity ID

ACS URL Format:

https://your-domain.com/api/auth/saml/{provider_id}/acs

Assertion Settings¶

MFA Behavior¶

OAuth 2.0 / OpenID Connect Configuration¶

OIDC vs OAuth 2.0¶

Basic Setup (OIDC)¶

1. Navigate to Admin Panel → SSO Settings → Add Provider
2. Select OpenID Connect
3. Configure:

Callback URL¶

Your IdP needs the OAuth callback URL:

https://your-domain.com/api/auth/oauth/{provider_id}/callback

This URL is displayed in the provider card after creation.

OAuth 2.0 Manual Configuration¶

For non-OIDC providers, disable discovery and configure manually:

Scopes¶

Default scopes: openid profile email

Additional scopes may be required depending on your IdP and attribute needs.

Signature Algorithm Requirements¶

Configuring Authentik for RS256:

1. Go to Authentik Admin → Applications → Providers
2. Edit your OIDC provider
3. Set Signing Key to an RSA key
4. Save changes

MFA Behavior¶

Username Attribute Fallback¶

KrakenHashes automatically detects usernames from common claim names. The configured Username Attribute is tried first, followed by these fallbacks:

If no username is found after trying all fallbacks, the email address is used as the username.

SSO User Accounts¶

Just-In-Time (JIT) Provisioning¶

When a user authenticates via SSO for the first time:

1. Email Matching: System checks for existing user with matching email
2. Identity Linking: If found, SSO identity is linked to existing account
3. User Creation: If not found and auto-create is enabled, new user is created
4. Account Status: New users are enabled or disabled based on auto-enable setting

Account Linking¶

Users can have multiple SSO identities linked:

• View linked accounts in User Settings → Linked Accounts
• Unlink accounts (if not the last authentication method)
• Link additional providers while logged in

SSO User Password Generation¶

Why Random Passwords?¶

SSO users authenticate through external identity providers and don't need local passwords. However, the database requires a password_hash value. Instead of modifying the database schema, KrakenHashes generates an unguessable random password.

How It Works¶

1. Generate 48 cryptographically random bytes using crypto/rand
2. Encode to base64 → 64-character string
3. Hash with bcrypt (cost factor 10)
4. Store the hash in the database

Security Properties¶

Admin Override¶

Administrators can reset an SSO user's password through User Management, enabling local login as a fallback if the SSO provider is unavailable.

Per-User Authentication Overrides¶

Administrators can override global authentication settings per user:

Use Cases:

• Emergency admin access when SSO is down
• Restricting specific users to SSO only
• Service accounts that require local authentication

Best Practices¶

Security¶

1. Always set SSO_ENCRYPTION_KEY in production
2. Use RS256 for OIDC token signing
3. Enable assertion signing for SAML
4. Use LDAPS or StartTLS for LDAP connections
5. Regularly rotate SP certificates and encryption keys
6. Monitor failed login attempts in audit logs

Deployment¶

1. Test thoroughly before disabling local authentication
2. Keep at least one admin with local auth override
3. Document recovery procedures for IdP outages
4. Use the same encryption key across all backend instances

User Experience¶

1. Provide clear error messages for SSO failures
2. Document SSO options for end users
3. Configure appropriate session timeouts
4. Test all provider types before production deployment

Troubleshooting¶

Common Issues¶

1. "Invalid signature algorithm HS256"
2. Cause: IdP signing tokens with HS256 instead of RS256

3. Solution: Configure IdP to use RS256 signing key

4. "Issuer mismatch"

5. Cause: Trailing slash inconsistency in discovery URL

6. Solution: Ensure discovery URL matches IdP exactly (including trailing slashes)

7. "Account processing failed"

8. Cause: Various server-side errors

9. Solution: Check backend logs for specific error message

10. "Pending approval"

11. Cause: Auto-enable users is disabled

12. Solution: Admin must enable the user account

13. "SSO provider not found"

14. Cause: Provider failed to load after creation

15. Solution: Check provider configuration and use Test Connection

16. "Failed to decrypt assertion"

17. Cause: Missing or incorrect SP private key

18. Solution: Ensure SP private key matches the certificate sent to IdP

19. LDAP "Invalid credentials"

20. Cause: Wrong bind DN or password
21. Solution: Verify service account credentials with ldapsearch

Diagnostic Steps¶

1. Check backend logs for detailed error messages
2. Use Test Connection to verify provider configuration
3. Verify IdP configuration matches KrakenHashes settings
4. Check network connectivity to IdP servers
5. Validate certificates haven't expired

Getting Help¶

If you encounter issues not covered here:

1. Check the GitHub Issues
2. Join the Discord community
3. Review IdP-specific documentation