Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(auth): WebAuthn / Passkey support

Juan Denis47c92e05715f
diff --git a/backend/app/api/auth.py b/backend/app/api/auth.py
index 87f7689e..a02ee317 100644
--- a/backend/app/api/auth.py
+++ b/backend/app/api/auth.py
@@ -335,3 +335,105 @@ def update_current_user():
db.session.commit()
return jsonify({'user': user.to_dict()}), 200
+
+
+# ==========================================
+# PASSKEY / WEBAUTHN
+# ==========================================
+@auth_bp.route('/passkeys/options/register', methods=['POST'])
+@jwt_required()
+def passkey_register_options():
+ """Begin WebAuthn registration for the current user."""
+ from app.services.passkey_service import PasskeyService
+ user_id = get_jwt_identity()
+ user = User.query.get(user_id)
+ if not user:
+ return jsonify({'error': 'User not found'}), 404
+ options = PasskeyService.begin_registration(user)
+ return jsonify(options), 200
+
+
+@auth_bp.route('/passkeys/register', methods=['POST'])
+@jwt_required()
+def passkey_register():
+ """Verify and save a new WebAuthn credential."""
+ from app.services.passkey_service import PasskeyService
+ user_id = get_jwt_identity()
+ user = User.query.get(user_id)
+ if not user:
+ return jsonify({'error': 'User not found'}), 404
+ data = request.get_json() or {}
+ credential = data.get('credential')
+ device_name = data.get('device_name', 'Passkey')
+ if not credential:
+ return jsonify({'error': 'No credential provided'}), 400
+ result = PasskeyService.verify_registration(user, credential, device_name)
+ return jsonify(result), 200 if result['success'] else 400
+
+
+@auth_bp.route('/passkeys', methods=['GET'])
+@jwt_required()
+def passkey_list():
+ """List the current user's passkeys."""
+ from app.services.passkey_service import PasskeyService
+ user_id = get_jwt_identity()
+ return jsonify({'passkeys': PasskeyService.get_user_passkeys(user_id)}), 200
+
+
+@auth_bp.route('/passkeys/<int:passkey_id>', methods=['DELETE'])
+@jwt_required()
+def passkey_delete(passkey_id):
+ """Remove a passkey."""
+ from app.services.passkey_service import PasskeyService
+ user_id = get_jwt_identity()
+ result = PasskeyService.remove_passkey(user_id, passkey_id)
+ return jsonify(result), 200 if result['success'] else 404
+
+
+@auth_bp.route('/passkeys/options/authenticate', methods=['POST'])
+def passkey_auth_options():
+ """Begin WebAuthn authentication (public, challenge only)."""
+ from app.services.passkey_service import PasskeyService
+ data = request.get_json() or {}
+ user_id = data.get('user_id')
+ user = User.query.get(user_id) if user_id else None
+ options = PasskeyService.begin_authentication(user)
+ return jsonify(options), 200
+
+
+@auth_bp.route('/passkeys/authenticate', methods=['POST'])
[email protected]("5 per minute")
+def passkey_authenticate():
+ """Verify a WebAuthn assertion and issue JWT tokens."""
+ from app.services.passkey_service import PasskeyService
+ from app.services import sso_service
+ data = request.get_json() or {}
+ credential = data.get('credential')
+ user_id = data.get('user_id')
+ if not credential:
+ return jsonify({'error': 'No credential provided'}), 400
+
+ user = User.query.get(user_id) if user_id else None
+ result = PasskeyService.verify_authentication(credential, user)
+ if not result['success']:
+ return jsonify(result), 401
+
+ user = result['user']
+ if not user.is_active:
+ return jsonify({'error': 'Account is deactivated'}), 403
+
+ user.reset_failed_login()
+ user.last_login_at = datetime.utcnow()
+ db.session.commit()
+
+ AuditService.log_login(user.id, success=True, details={'method': 'passkey'})
+ db.session.commit()
+
+ access_token = create_access_token(identity=user.id)
+ refresh_token = create_refresh_token(identity=user.id)
+
+ return jsonify({
+ 'user': user.to_dict(),
+ 'access_token': access_token,
+ 'refresh_token': refresh_token
+ }), 200
diff --git a/backend/app/models/__init__.py b/backend/app/models/__init__.py
index d8fde0e3..d4799fe2 100644
--- a/backend/app/models/__init__.py
+++ b/backend/app/models/__init__.py
@@ -38,6 +38,7 @@ from app.models.pending_agent import PendingAgent
from app.models.plugin import InstalledPlugin
from app.models.ai import AiConversation, AiMessage, AiPendingAction
from app.models.image_scan import ImageVulnerabilityScan, SbomArtifact
+from app.models.passkey import PasskeyCredential
__all__ = [
'User', 'Application', 'Domain', 'EnvironmentVariable', 'EnvironmentVariableHistory',
@@ -62,4 +63,5 @@ __all__ = [
'InstalledPlugin',
'AiConversation', 'AiMessage', 'AiPendingAction',
'ImageVulnerabilityScan', 'SbomArtifact',
+ 'PasskeyCredential',
]
diff --git a/backend/app/models/passkey.py b/backend/app/models/passkey.py
new file mode 100644
index 00000000..9ba04034
--- /dev/null
+++ b/backend/app/models/passkey.py
@@ -0,0 +1,54 @@
+import json
+import base64
+from datetime import datetime
+from app import db
+
+
+def _b64decode_url(value: str) -> bytes:
+ """URL-safe base64 decode with padding fix."""
+ if not value:
+ return b''
+ padding = 4 - len(value) % 4
+ if padding != 4:
+ value += '=' * padding
+ return base64.urlsafe_b64decode(value)
+
+
+class PasskeyCredential(db.Model):
+ """Stored WebAuthn credential for a user."""
+ __tablename__ = 'passkey_credentials'
+
+ id = db.Column(db.Integer, primary_key=True)
+ user_id = db.Column(db.Integer, db.ForeignKey('users.id'), nullable=False, index=True)
+ credential_id = db.Column(db.String(500), nullable=False, unique=True, index=True)
+ public_key = db.Column(db.Text, nullable=False) # base64url-encoded COSE key
+ sign_count = db.Column(db.Integer, default=0)
+ transports = db.Column(db.Text, nullable=True) # JSON list
+ device_name = db.Column(db.String(200), nullable=True)
+ is_active = db.Column(db.Boolean, default=True)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+ last_used_at = db.Column(db.DateTime, nullable=True)
+
+ user = db.relationship('User', backref=db.backref('passkeys', lazy='dynamic'))
+
+ def get_transports(self):
+ if not self.transports:
+ return []
+ try:
+ return json.loads(self.transports)
+ except Exception:
+ return []
+
+ def set_transports(self, transports):
+ self.transports = json.dumps(list(transports)) if transports else None
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'credential_id': self.credential_id,
+ 'device_name': self.device_name,
+ 'transports': self.get_transports(),
+ 'is_active': self.is_active,
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ 'last_used_at': self.last_used_at.isoformat() if self.last_used_at else None,
+ }
diff --git a/backend/app/models/user.py b/backend/app/models/user.py
index 493c6993..6d5c340c 100644
--- a/backend/app/models/user.py
+++ b/backend/app/models/user.py
@@ -193,6 +193,7 @@ class User(db.Model):
'totp_enabled': self.totp_enabled,
'auth_provider': self.auth_provider or 'local',
'has_password': self.has_password,
+ 'passkey_enabled': self.passkeys.filter_by(is_active=True).count() > 0,
'sidebar_config': self.get_sidebar_config(),
'created_at': self.created_at.isoformat(),
'updated_at': self.updated_at.isoformat(),
diff --git a/backend/app/services/passkey_service.py b/backend/app/services/passkey_service.py
new file mode 100644
index 00000000..a30b838a
--- /dev/null
+++ b/backend/app/services/passkey_service.py
@@ -0,0 +1,223 @@
+"""WebAuthn / Passkey authentication service."""
+import base64
+import json
+import logging
+import os
+from datetime import datetime
+from typing import Dict, List, Optional
+
+from webauthn import generate_registration_options, verify_registration_response
+from webauthn import generate_authentication_options, verify_authentication_response
+from webauthn.helpers.structs import (
+ RegistrationResult,
+ AuthenticationResult,
+ PublicKeyCredentialDescriptor,
+)
+from webauthn.helpers.exceptions import InvalidRegistrationResponse, InvalidAuthenticationResponse
+
+from app import db
+from app.models import User, PasskeyCredential
+
+logger = logging.getLogger(__name__)
+
+
+def _get_rp_id() -> str:
+ return os.environ.get('SERVERKIT_PASSKEY_RP_ID', os.environ.get('BASE_URL', 'localhost').replace('https://', '').replace('http://', '').split(':')[0])
+
+
+def _get_rp_name() -> str:
+ return os.environ.get('SERVERKIT_PASSKEY_RP_NAME', 'ServerKit')
+
+
+def _get_origin() -> str:
+ origin = os.environ.get('SERVERKIT_PASSKEY_ORIGIN', os.environ.get('BASE_URL', 'http://localhost'))
+ return origin.rstrip('/')
+
+
+def _b64encode_url(data: bytes) -> str:
+ return base64.urlsafe_b64encode(data).rstrip(b'=').decode('ascii')
+
+
+def _b64decode_url(value: str) -> bytes:
+ if not value:
+ return b''
+ padding = 4 - len(value) % 4
+ if padding != 4:
+ value += '=' * padding
+ return base64.urlsafe_b64decode(value)
+
+
+class PasskeyService:
+ """Manage WebAuthn registration and authentication."""
+
+ @classmethod
+ def _challenge_key(cls, user_id: int, suffix: str) -> str:
+ return f'passkey_{suffix}_challenge_{user_id}'
+
+ @classmethod
+ def _get_challenge(cls, user_id: int, suffix: str) -> Optional[bytes]:
+ # Use SystemSettings as a simple server-side challenge store.
+ # Challenges expire naturally because they are overwritten on each request.
+ from app.models import SystemSettings
+ setting = SystemSettings.query.filter_by(key=cls._challenge_key(user_id, suffix)).first()
+ if not setting or not setting.value:
+ return None
+ try:
+ return _b64decode_url(setting.value)
+ except Exception:
+ return None
+
+ @classmethod
+ def _set_challenge(cls, user_id: int, suffix: str, challenge: bytes) -> None:
+ from app.models import SystemSettings
+ key = cls._challenge_key(user_id, suffix)
+ setting = SystemSettings.query.filter_by(key=key).first()
+ if not setting:
+ setting = SystemSettings(key=key, value_type='string')
+ db.session.add(setting)
+ setting.value = _b64encode_url(challenge)
+ db.session.commit()
+
+ @classmethod
+ def _clear_challenge(cls, user_id: int, suffix: str) -> None:
+ from app.models import SystemSettings
+ key = cls._challenge_key(user_id, suffix)
+ SystemSettings.query.filter_by(key=key).delete(synchronize_session=False)
+ db.session.commit()
+
+ @classmethod
+ def get_user_passkeys(cls, user_id: int) -> List[Dict]:
+ return [p.to_dict() for p in PasskeyCredential.query.filter_by(user_id=user_id, is_active=True).all()]
+
+ @classmethod
+ def begin_registration(cls, user: User) -> Dict:
+ """Generate WebAuthn registration options for the user."""
+ options = generate_registration_options(
+ rp_id=_get_rp_id(),
+ rp_name=_get_rp_name(),
+ user_id=str(user.id).encode(),
+ user_name=user.email,
+ user_display_name=user.username or user.email,
+ challenge=os.urandom(32),
+ timeout=60000,
+ attestation='none',
+ authenticator_selection={
+ 'resident_key': 'preferred',
+ 'user_verification': 'preferred',
+ 'authenticator_attachment': 'platform',
+ },
+ )
+ cls._set_challenge(user.id, 'register', options.challenge)
+ return json.loads(options.json())
+
+ @classmethod
+ def verify_registration(cls, user: User, credential: Dict, device_name: str = '') -> Dict:
+ """Verify and store a new WebAuthn credential."""
+ challenge = cls._get_challenge(user.id, 'register')
+ if not challenge:
+ return {'success': False, 'error': 'Registration challenge expired or missing'}
+
+ try:
+ result: RegistrationResult = verify_registration_response(
+ credential=credential,
+ expected_challenge=challenge,
+ expected_rp_id=_get_rp_id(),
+ expected_origin=_get_origin(),
+ )
+ except InvalidRegistrationResponse as e:
+ return {'success': False, 'error': str(e)}
+ except Exception as e:
+ logger.exception('Passkey registration verification failed')
+ return {'success': False, 'error': str(e)}
+
+ cls._clear_challenge(user.id, 'register')
+
+ passkey = PasskeyCredential(
+ user_id=user.id,
+ credential_id=_b64encode_url(result.credential_id),
+ public_key=_b64encode_url(result.credential_public_key),
+ sign_count=result.sign_count,
+ device_name=device_name or 'Passkey',
+ )
+ if credential.get('transports'):
+ passkey.set_transports(credential['transports'])
+
+ db.session.add(passkey)
+ db.session.commit()
+
+ return {'success': True, 'passkey': passkey.to_dict()}
+
+ @classmethod
+ def begin_authentication(cls, user: Optional[User] = None) -> Dict:
+ """Generate authentication options. If user is known, filter by their credentials."""
+ allow_credentials = None
+ if user:
+ creds = PasskeyCredential.query.filter_by(user_id=user.id, is_active=True).all()
+ allow_credentials = [
+ PublicKeyCredentialDescriptor(id=_b64decode_url(c.credential_id), transports=c.get_transports())
+ for c in creds
+ ]
+
+ options = generate_authentication_options(
+ rp_id=_get_rp_id(),
+ challenge=os.urandom(32),
+ timeout=60000,
+ allow_credentials=allow_credentials,
+ user_verification='preferred',
+ )
+ # Store challenge globally or per-user. We store per-user if known.
+ challenge_user_id = user.id if user else 0
+ cls._set_challenge(challenge_user_id, 'auth', options.challenge)
+ return json.loads(options.json())
+
+ @classmethod
+ def verify_authentication(cls, credential: Dict, user: Optional[User] = None) -> Dict:
+ """Verify a WebAuthn assertion and return the authenticated user."""
+ challenge_user_id = user.id if user else 0
+ challenge = cls._get_challenge(challenge_user_id, 'auth')
+ if not challenge:
+ return {'success': False, 'error': 'Authentication challenge expired or missing'}
+
+ credential_id_b64 = credential.get('id')
+ if not credential_id_b64:
+ return {'success': False, 'error': 'Missing credential id'}
+
+ passkey = PasskeyCredential.query.filter_by(credential_id=credential_id_b64, is_active=True).first()
+ if not passkey:
+ return {'success': False, 'error': 'Unknown passkey'}
+
+ try:
+ result: AuthenticationResult = verify_authentication_response(
+ credential=credential,
+ expected_challenge=challenge,
+ expected_rp_id=_get_rp_id(),
+ expected_origin=_get_origin(),
+ credential_public_key=_b64decode_url(passkey.public_key),
+ credential_current_sign_count=passkey.sign_count,
+ )
+ except InvalidAuthenticationResponse as e:
+ return {'success': False, 'error': str(e)}
+ except Exception as e:
+ logger.exception('Passkey authentication verification failed')
+ return {'success': False, 'error': str(e)}
+
+ cls._clear_challenge(challenge_user_id, 'auth')
+
+ passkey.sign_count = result.new_sign_count
+ passkey.last_used_at = datetime.utcnow()
+ db.session.commit()
+
+ return {'success': True, 'user': passkey.user}
+
+ @classmethod
+ def remove_passkey(cls, user_id: int, passkey_id: int) -> Dict:
+ passkey = PasskeyCredential.query.filter_by(id=passkey_id, user_id=user_id).first()
+ if not passkey:
+ return {'success': False, 'error': 'Passkey not found'}
+ db.session.delete(passkey)
+ db.session.commit()
+ return {'success': True, 'message': 'Passkey removed'}
+
+ @classmethod
+ def is_enabled_for_user(cls, user_id: int) -> bool:
+ return PasskeyCredential.query.filter_by(user_id=user_id, is_active=True).count() > 0
diff --git a/backend/migrations/versions/019_passkey_credentials.py b/backend/migrations/versions/019_passkey_credentials.py
new file mode 100644
index 00000000..f3308936
--- /dev/null
+++ b/backend/migrations/versions/019_passkey_credentials.py
@@ -0,0 +1,62 @@
+"""WebAuthn passkey credentials.
+
+Adds:
+- passkey_credentials table
+
+Revision ID: 019_passkey_credentials
+Revises: 018_image_scan_sbom
+Create Date: 2026-06-19
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = '019_passkey_credentials'
+down_revision = '018_image_scan_sbom'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ tables = inspector.get_table_names()
+
+ if 'passkey_credentials' not in tables:
+ op.create_table(
+ 'passkey_credentials',
+ sa.Column('id', sa.Integer(), nullable=False),
+ sa.Column('user_id', sa.Integer(), nullable=False),
+ sa.Column('credential_id', sa.String(length=500), nullable=False),
+ sa.Column('public_key', sa.Text(), nullable=False),
+ sa.Column('sign_count', sa.Integer(), nullable=True),
+ sa.Column('transports', sa.Text(), nullable=True),
+ sa.Column('device_name', sa.String(length=200), nullable=True),
+ sa.Column('is_active', sa.Boolean(), nullable=True),
+ sa.Column('created_at', sa.DateTime(), nullable=True),
+ sa.Column('last_used_at', sa.DateTime(), nullable=True),
+ sa.ForeignKeyConstraint(['user_id'], ['users.id']),
+ sa.PrimaryKeyConstraint('id')
+ )
+ op.create_index(
+ op.f('ix_passkey_credentials_user_id'),
+ 'passkey_credentials',
+ ['user_id'],
+ unique=False
+ )
+ op.create_index(
+ op.f('ix_passkey_credentials_credential_id'),
+ 'passkey_credentials',
+ ['credential_id'],
+ unique=True
+ )
+
+
+def downgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ tables = inspector.get_table_names()
+
+ if 'passkey_credentials' in tables:
+ op.drop_index(op.f('ix_passkey_credentials_credential_id'), table_name='passkey_credentials')
+ op.drop_index(op.f('ix_passkey_credentials_user_id'), table_name='passkey_credentials')
+ op.drop_table('passkey_credentials')
diff --git a/backend/requirements.txt b/backend/requirements.txt
index d6d63804..9386feb4 100644
--- a/backend/requirements.txt
+++ b/backend/requirements.txt
@@ -51,6 +51,9 @@ cryptography==48.0.1
pyotp==2.9.0
qrcode[pil]==7.4.2
+# WebAuthn / Passkeys
+webauthn==2.5.0
+
# HTTP Requests (for webhooks & notifications)
requests==2.33.1