Allow IAS SSO without email and provide explicit identity linking

This commit is contained in:
Aleksandr Meshchryakov
2026-09-28 13:59:19 +02:00
parent ed1b7ec78f
commit d46ae6fc06
11 changed files with 361 additions and 17 deletions

View File

@@ -263,6 +263,19 @@ make pre-commit
ИАС отправляет `POST /api/v1/auth/sso/` с `Content-Type: application/x-www-form-urlencoded`: обязательное поле `sso_token`, необязательное `redirect_path` (локальный путь, по умолчанию `/main`). Вариант URL без завершающего `/` тоже принимает форму напрямую: промежуточного 301, теряющего POST, нет. Для регистрации в ИАС используйте канонический URL со слешем.
Email в SSO-токене необязателен: отсутствующее поле, `null` и пустая строка означают отсутствие почты. Новый SSO-пользователь создаётся с `email=NULL` и `is_verified=false`; фиктивный адрес не генерируется. Переданный непустой email проверяется на формат, длину и конфликты. Если при следующем входе email отсутствует, сохранённый адрес и его признак подтверждения остаются прежними. Обычная регистрация по-прежнему требует email.
Повторный вход использует неизменяемую пару `(iss, user_id)`. Автоматическая первичная привязка к локальному аккаунту по-прежнему требует совпадения логина и непустой почты. При совпадении только логина вход отклоняется. Администратор может явно привязать существующий аккаунт после проверки принадлежности внешнего `user_id` пользователю:
```bash
python src/manage.py link_sso_identity --user-id <local-id> --expected-username <local-login> --subject <ias-user-id> --dry-run
# После проверки соответствия повторить без --dry-run.
```
Команда использует настроенный `SSO_ISSUER`, не переносит уже занятую identity и не меняет локальные права. До первого успешного входа `last_authenticated_at` равен `NULL`. Сам по себе одинаковый логин не является подтверждением принадлежности аккаунта.
Миграция `0010_sso_optional_email` разрешает NULL в email и времени последнего SSO-входа; данные пользователей сохраняются. При откате приложения оставьте эту совместимую схему: обратная миграция к NOT NULL требует предварительно обработать пользователей без почты и ещё не использованные привязки.
После успешной проверки одноразового ES256 JWT backend устанавливает Django session cookie и CSRF cookie и отвечает `303 Location: <redirect_path>`. GET callback возвращает 405; токен в URL не принимается. Пустая форма при включённом SSO возвращает 400, при выключенном — 503.
Перед выпуском проверяйте каждый контур отдельно: `SSO_ENABLED`, issuer, service code/target, соответствие callback у ИАС и доступность публичного ключа в контейнере. Включение dev не включает main. Правка маршрута не заменяет настройку провайдера и полный вход с настоящим SSO-токеном. Не копируйте токены/cookie в логи или отчёты.

View File

View File

@@ -0,0 +1,63 @@
from apps.user.models import SsoIdentity
from django.conf import settings
from django.contrib.auth import get_user_model
from django.core.management.base import BaseCommand, CommandError
from django.db import IntegrityError, transaction
User = get_user_model()
class Command(BaseCommand):
help = "Explicitly link a verified IAS subject to an existing local user."
def add_arguments(self, parser):
parser.add_argument("--user-id", type=int, required=True)
parser.add_argument("--expected-username", required=True)
parser.add_argument("--subject", required=True)
parser.add_argument("--dry-run", action="store_true")
def handle(self, *args, **options):
issuer = settings.SSO_ISSUER
subject = options["subject"]
if not isinstance(issuer, str) or not issuer.strip() or len(issuer) > 64:
raise CommandError("Configured SSO issuer is invalid.")
if not subject.strip() or subject != subject.strip() or len(subject) > 255:
raise CommandError("SSO subject is invalid.")
try:
with transaction.atomic():
user = (
User.objects.select_for_update()
.filter(
pk=options["user_id"],
username=options["expected_username"],
is_active=True,
)
.first()
)
if user is None:
raise CommandError(
"Active local user and expected username must match."
)
identity = SsoIdentity.objects.filter(
issuer=issuer, subject=subject
).first()
if identity is not None:
if identity.user_id != user.pk:
raise CommandError(
"This SSO identity is already linked to another user."
)
self.stdout.write("SSO identity already linked; no changes.")
return
if SsoIdentity.objects.filter(user=user).exists():
raise CommandError(
"This local user already has another SSO identity."
)
if options["dry_run"]:
self.stdout.write("SSO link validated; dry run, no changes.")
return
SsoIdentity.objects.create(user=user, issuer=issuer, subject=subject)
except IntegrityError as exc:
raise CommandError("SSO link conflicts with an existing identity.") from exc
self.stdout.write(
self.style.SUCCESS("SSO identity linked; local permissions unchanged.")
)

View File

@@ -0,0 +1,24 @@
from django.db import migrations, models
class Migration(migrations.Migration):
dependencies = [("user", "0009_ssoidentity")]
operations = [
migrations.AlterField(
model_name="user",
name="email",
field=models.EmailField(
blank=True, null=True, unique=True, max_length=254,
verbose_name="email address",
help_text="Optional for SSO users. Must be unique when provided.",
),
),
migrations.AlterField(
model_name="ssoidentity",
name="last_authenticated_at",
field=models.DateTimeField(
blank=True, null=True, verbose_name="last authenticated at",
),
),
]

View File

@@ -0,0 +1,9 @@
from django.db import migrations
class Migration(migrations.Migration):
dependencies = [
("user", "0010_sso_claims_and_role_management"),
("user", "0010_sso_optional_email"),
]
operations = []

View File

@@ -29,7 +29,11 @@ class User(AbstractUser):
)
email = models.EmailField(
_("email address"), unique=True, help_text=_("Required. Must be unique.")
_("email address"),
unique=True,
blank=True,
null=True,
help_text=_("Optional for SSO users. Must be unique when provided."),
)
phone = models.CharField(
@@ -131,7 +135,10 @@ class SsoIdentity(models.Model):
is_integrated_structure = models.BooleanField(default=False)
ex_loop = models.BooleanField(default=False)
role_managed_by_sso = models.BooleanField(default=False)
last_authenticated_at = models.DateTimeField(_("last authenticated at"))
last_authenticated_at = models.DateTimeField(
_("last authenticated at"), null=True, blank=True
)
created_at = models.DateTimeField(_("created at"), auto_now_add=True)
updated_at = models.DateTimeField(_("updated at"), auto_now=True)

View File

@@ -89,6 +89,9 @@ class UserSerializer(serializers.ModelSerializer):
"updated_at",
)
read_only_fields = ("id", "is_verified", "created_at", "updated_at")
extra_kwargs = {
"email": {"required": True, "allow_null": False, "allow_blank": False},
}
class CurrentUserProfileSerializer(serializers.ModelSerializer):
@@ -156,7 +159,7 @@ class UserManagementSerializer(serializers.Serializer):
id = serializers.IntegerField(read_only=True)
username = serializers.CharField(read_only=True)
email = serializers.EmailField(read_only=True)
email = serializers.EmailField(read_only=True, allow_null=True)
phone = serializers.CharField(read_only=True, allow_null=True)
is_active = serializers.BooleanField(read_only=True)
is_verified = serializers.BooleanField(read_only=True)
@@ -322,6 +325,9 @@ class AdminUserCreateSerializer(serializers.ModelSerializer):
)
extra_kwargs = {
"email": {
"required": True,
"allow_null": False,
"allow_blank": False,
"validators": [UniqueValidator(queryset=User.objects.all())],
},
"username": {
@@ -375,6 +381,10 @@ class AdminUserUpdateSerializer(serializers.ModelSerializer):
"last_name",
)
extra_kwargs = {
"email": {"required": True, "allow_null": False, "allow_blank": False},
}
def validate(self, attrs):
profile_fields = {"first_name", "middle_name", "last_name"}
if not any(field in attrs for field in profile_fields):

View File

@@ -32,7 +32,7 @@ class SsoClaims:
issuer: str
subject: str
username: str
email: str
email: str | None
first_name: str
middle_name: str
last_name: str
@@ -121,7 +121,6 @@ def _decode_sso_payload(encoded_token: str) -> dict:
"sso_target",
"user_id",
"username",
"email",
]
},
)
@@ -173,6 +172,23 @@ def _default_organisation(payload: dict) -> str | dict | None:
return organisation
def _optional_email(payload: dict) -> str | None:
email = payload.get("email")
if email is None:
return None
if not isinstance(email, str):
raise SsoAuthenticationError("Некорректный email SSO-пользователя.")
email = email.strip()
if not email:
return None
try:
validate_email(email)
User._meta.get_field("email").run_validators(email)
except DjangoValidationError as exc:
raise SsoAuthenticationError("Некорректный email SSO-пользователя.") from exc
return email
def verify_sso_token(encoded_token: str) -> SsoClaims:
"""Проверяет ES256 SSO JWT и возвращает только нужные локальному сервису claims."""
payload = _decode_sso_payload(encoded_token)
@@ -185,13 +201,11 @@ def verify_sso_token(encoded_token: str) -> SsoClaims:
_, expires_at = _validate_token_lifetime(payload)
username = payload.get("username")
email = payload.get("email")
email = _optional_email(payload)
jti = payload.get("jti")
subject = payload.get("user_id")
if not isinstance(username, str) or not username.strip():
raise SsoAuthenticationError("В SSO-токене отсутствует username.")
if not isinstance(email, str) or not email.strip():
raise SsoAuthenticationError("В SSO-токене отсутствует email.")
if not isinstance(jti, str) or not jti.strip():
raise SsoAuthenticationError("В SSO-токене отсутствует jti.")
if isinstance(subject, bool) or not isinstance(subject, int | str):
@@ -200,7 +214,6 @@ def verify_sso_token(encoded_token: str) -> SsoClaims:
raise SsoAuthenticationError("В SSO-токене отсутствует user_id.")
try:
validate_email(email)
User._meta.get_field("username").run_validators(username)
except DjangoValidationError as exc:
raise SsoAuthenticationError(
@@ -237,9 +250,10 @@ def reserve_sso_token(claims: SsoClaims) -> None:
def _ensure_user_claims_available(claims: SsoClaims, *, exclude_user_id=None) -> None:
conflicts = User.objects.filter(
Q(username=claims.username) | Q(email__iexact=claims.email)
)
query = Q(username=claims.username)
if claims.email is not None:
query |= Q(email__iexact=claims.email)
conflicts = User.objects.filter(query)
if exclude_user_id is not None:
conflicts = conflicts.exclude(id=exclude_user_id)
if conflicts.exists():
@@ -264,7 +278,11 @@ def provision_sso_user(claims: SsoClaims):
_ensure_user_claims_available(claims, exclude_user_id=user.id)
else:
username_user = User.objects.filter(username=claims.username).first()
email_users = list(User.objects.filter(email__iexact=claims.email)[:2])
email_users = (
list(User.objects.filter(email__iexact=claims.email)[:2])
if claims.email is not None
else []
)
if username_user is not None or email_users:
if (
username_user is None
@@ -278,7 +296,11 @@ def provision_sso_user(claims: SsoClaims):
if not user.is_active:
raise SsoAuthenticationError("Локальная учётная запись отключена.")
else:
user = User(username=claims.username, email=claims.email, is_verified=True)
user = User(
username=claims.username,
email=claims.email,
is_verified=claims.email is not None,
)
user.set_unusable_password()
user.save()
is_new_user = True
@@ -292,8 +314,9 @@ def provision_sso_user(claims: SsoClaims):
)
user.username = claims.username
user.email = claims.email
user.is_verified = True
if claims.email is not None:
user.email = claims.email
user.is_verified = True
user.save(update_fields=["username", "email", "is_verified", "updated_at"])
profile = user.profile
profile.first_name = claims.first_name

View File

@@ -44,6 +44,30 @@ class UserRegistrationSerializerTest(TestCase):
serializer = UserRegistrationSerializer(data=self.user_data)
self.assertTrue(serializer.is_valid())
def test_local_registration_still_requires_email(self):
for value in (None, "", "missing"):
data = self.user_data.copy()
if value == "missing":
data.pop("email")
else:
data["email"] = value
serializer = UserRegistrationSerializer(data=data)
self.assertFalse(serializer.is_valid())
self.assertIn("email", serializer.errors)
def test_admin_creation_still_requires_email(self):
from apps.user.serializers import AdminUserCreateSerializer
data = {
"username": "local",
"password": self.password,
"first_name": "Test",
"last_name": "User",
}
serializer = AdminUserCreateSerializer(data=data)
self.assertFalse(serializer.is_valid())
self.assertIn("email", serializer.errors)
def test_passwords_do_not_match(self):
"""Test validation fails when passwords don't match"""
data = self.user_data.copy()

View File

@@ -1,6 +1,7 @@
import os
import tempfile
from datetime import UTC, datetime, timedelta
from io import StringIO
from urllib.parse import parse_qs, urlencode, urlsplit
import jwt
@@ -9,6 +10,8 @@ from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import ec
from django.apps import apps
from django.contrib.auth import get_user_model
from django.core.management import call_command
from django.core.management.base import CommandError
from django.test import SimpleTestCase, override_settings
from rest_framework.test import APIClient, APITestCase
@@ -390,9 +393,177 @@ class SsoCallbackViewTest(APITestCase):
self.assertFalse(User.objects.exists())
def test_multiple_users_can_login_without_email(self):
for index, email in enumerate((None, "", " ", "missing")):
claims = self._claims(
user_id=9000 + index,
username=f"noemail{index}",
email=email,
jti=f"noemail-{index}",
)
if email == "missing":
claims.pop("email")
response = self._post_callback(self._encode_claims(claims))
self.assertEqual(response.status_code, 303)
user = User.objects.get(username=f"noemail{index}")
self.assertIsNone(user.email)
self.assertFalse(user.is_verified)
self.assertFalse(user.has_usable_password())
self.assertEqual(self.client.get("/api/v1/users/me/").status_code, 200)
self.assertEqual(User.objects.filter(email__isnull=True).count(), 4)
def test_email_less_identity_reuses_account_and_preserves_existing_email(self):
self.assertEqual(self._post_callback(self._token()).status_code, 303)
user = User.objects.get(username="test30")
response = self._post_callback(self._token(email=None, jti="without-email"))
self.assertEqual(response.status_code, 303)
user.refresh_from_db()
self.assertEqual(user.email, "test30@example.com")
self.assertTrue(user.is_verified)
self.assertEqual(User.objects.count(), 1)
self.assertEqual(self.client.session["_auth_user_id"], str(user.pk))
def test_email_less_account_can_receive_email_on_later_login(self):
self.assertEqual(self._post_callback(self._token(email=None)).status_code, 303)
response = self._post_callback(self._token(jti="email-added"))
self.assertEqual(response.status_code, 303)
user = User.objects.get(username="test30")
self.assertEqual(user.email, "test30@example.com")
self.assertTrue(user.is_verified)
self.assertEqual(User.objects.count(), 1)
def test_email_less_token_cannot_claim_existing_local_admin(self):
user = UserFactory.create_user(username="test30", is_staff=True)
original_email = user.email
response = self._post_callback(self._token(email=None))
self.assertEqual(response.status_code, 403)
self.assertNotIn("_auth_user_id", self.client.session)
user.refresh_from_db()
self.assertEqual(user.email, original_email)
self.assertTrue(user.is_staff)
self.assertFalse(apps.get_model("user", "SsoIdentity").objects.exists())
def test_email_less_identity_cannot_take_another_username(self):
self.assertEqual(self._post_callback(self._token(email=None)).status_code, 303)
UserFactory.create_user(username="occupied")
response = self._post_callback(
self._token(email=None, username="occupied", jti="name-collision")
)
self.assertEqual(response.status_code, 403)
self.assertTrue(User.objects.filter(username="test30").exists())
def test_email_less_token_still_requires_signature_and_one_time_use(self):
token = self._token(email=None)
invalid = self._encode_claims(
self._claims(email=None), key=ec.generate_private_key(ec.SECP256R1())
)
self.assertEqual(self._post_callback(invalid).status_code, 403)
self.assertFalse(User.objects.exists())
self.assertEqual(self._post_callback(token).status_code, 303)
self.assertEqual(self._post_callback(token).status_code, 403)
def test_invalid_provided_email_is_rejected(self):
for email in (123, [], "not-an-email", "x" * 250 + "@example.com"):
response = self._post_callback(self._token(email=email))
self.assertEqual(response.status_code, 403)
self.assertFalse(User.objects.exists())
def _link(self, user, subject="2564", **options):
call_command(
"link_sso_identity",
user_id=user.pk,
expected_username=user.username,
subject=subject,
stdout=StringIO(),
**options,
)
def test_explicit_link_allows_email_less_login_and_keeps_local_permissions(self):
user = UserFactory.create_user(
username="test30", is_staff=True, is_verified=False
)
original_email = user.email
self._link(user, dry_run=True)
identity_model = apps.get_model("user", "SsoIdentity")
self.assertFalse(identity_model.objects.exists())
self._link(user)
self._link(user)
self.assertIsNone(identity_model.objects.get(user=user).last_authenticated_at)
response = self._post_callback(self._token(email=None))
self.assertEqual(response.status_code, 303)
user.refresh_from_db()
self.assertEqual(user.email, original_email)
self.assertFalse(user.is_verified)
self.assertTrue(user.is_staff)
self.assertIsNotNone(
identity_model.objects.get(user=user).last_authenticated_at
)
self.assertEqual(self.client.session["_auth_user_id"], str(user.pk))
def test_explicit_link_refuses_reassignment_and_invalid_local_target(self):
user = UserFactory.create_user(username="test30")
other = UserFactory.create_user(username="other")
self._link(user)
with self.assertRaises(CommandError):
self._link(other)
with self.assertRaises(CommandError):
self._link(user, subject="different")
with self.assertRaises(CommandError):
call_command(
"link_sso_identity",
user_id=other.pk,
expected_username="mismatch",
subject="different",
stdout=StringIO(),
)
other.is_active = False
other.save()
with self.assertRaises(CommandError):
self._link(other, subject="different")
self.assertEqual(apps.get_model("user", "SsoIdentity").objects.count(), 1)
def test_repeated_email_less_login_uses_same_identity_after_username_change(self):
self.assertEqual(self._post_callback(self._token(email=None)).status_code, 303)
original = User.objects.get(username="test30")
self.assertEqual(
self._post_callback(
self._token(email=None, username="renamed", jti="renamed-token")
).status_code,
303,
)
self.assertEqual(User.objects.get(username="renamed").pk, original.pk)
self.assertEqual(User.objects.count(), 1)
def test_later_email_collision_does_not_modify_identity(self):
self.assertEqual(self._post_callback(self._token(email=None)).status_code, 303)
UserFactory.create_user(username="other", email="test30@example.com")
self.assertEqual(
self._post_callback(self._token(jti="email-conflict")).status_code, 403
)
self.assertIsNone(User.objects.get(username="test30").email)
def test_email_less_login_rejects_missing_security_claims(self):
for claim in (
"iss",
"exp",
"iat",
"jti",
"token_type",
"sso_target",
"user_id",
"username",
):
claims = self._claims(email=None)
claims.pop(claim)
with self.subTest(claim=claim):
self.assertEqual(
self._post_callback(self._encode_claims(claims)).status_code, 403
)
self.assertFalse(User.objects.exists())
def test_rejects_missing_required_claim(self):
claims = self._claims()
claims.pop("email")
claims.pop("user_id")
response = self._post_callback(self._encode_claims(claims))