Skip to content

armgit / zulip

Public Imported from GitHub
0

Zulip server and web application. Open-source team chat that helps teams stay productive and focused.

management: Add delete_external_auth_ids command.

Mateusz Manderafd23117ad9ce
diff --git a/docs/production/authentication-methods.md b/docs/production/authentication-methods.md
index 8c5e922b251..a7e5638c68a 100644
--- a/docs/production/authentication-methods.md
+++ b/docs/production/authentication-methods.md
@@ -428,6 +428,27 @@ AUTH_LDAP_USER_ATTR_MAP = {
LDAP_UNIQUE_ACCOUNT_ID_IS_BINARY = True
```
+:::{warning}
+
+Changing which attribute `unique_account_id` refers to, or changing
+`LDAP_UNIQUE_ACCOUNT_ID_IS_BINARY`, is unsafe once any Zulip accounts
+are linked to LDAP accounts, which happens when users log in and when
+`manage.py sync_ldap_user_data` runs: a user whose new value matches
+another user's previous one would be logged into that other user's
+Zulip account. To make such a change safely, stop the Zulip server,
+update the configuration, and delete the existing links between Zulip
+accounts and LDAP accounts before starting the server again:
+
+```bash
+/home/zulip/deployments/current/manage.py delete_external_auth_ids --auth-method ldap --all-realms
+```
+
+Users are linked again via their email address the next time they log
+in or `manage.py sync_ldap_user_data` runs, just as when
+`unique_account_id` was first configured.
+
+:::
+
:::{note}
If a Zulip account is already linked to a different
@@ -863,6 +884,26 @@ attribute — for example, an opaque user ID or UUID. If
(or left unset), email synchronization will not be active, and email
changes at the IdP will result in duplicate accounts.
+:::{warning}
+
+Changing which attribute `attr_user_permanent_id` refers to is unsafe
+once any Zulip accounts are linked to the IdP, which happens when
+users log in: a user whose new permanent ID matches another user's
+previous one would be logged into that other user's Zulip account. To
+make such a change safely, stop the Zulip server, update the
+configuration, and delete the existing links between Zulip accounts
+and the IdP (replacing `YOUR_IDP_NAME` with its name in
+`SOCIAL_AUTH_SAML_ENABLED_IDPS`) before starting the server again:
+
+```bash
+/home/zulip/deployments/current/manage.py delete_external_auth_ids --auth-method saml:YOUR_IDP_NAME --all-realms
+```
+
+Users are linked again via their email address the next time they log
+in, just as when `attr_user_permanent_id` was first configured.
+
+:::
+
:::{note}
The first time a user logs in with SAML, the permanent ID is linked to
@@ -1241,10 +1282,30 @@ one the IdP sends for the same email address, Zulip will refuse the
login and log a warning, since the email address may have been
reassigned to a different person. The administrator should resolve
the conflict manually. This can happen when the user's account at the
-IdP was deleted and recreated. With Microsoft Entra ID, it can also
-happen for all users if the Zulip application is registered again with
-a new client ID, since Entra ID issues a different `sub` for each
-application.
+IdP was deleted and recreated.
+
+:::
+
+:::{warning}
+
+If the IdP issues a different `sub` for each application, as Microsoft
+Entra ID does, switching Zulip to a new application registration
+changes every user's `sub`, which makes Zulip refuse all of their
+logins. To avoid that, stop the Zulip server, update `client_id` and
+the secret, and delete the existing links between Zulip accounts and
+the IdP (replacing `YOUR_IDP_NAME` with its name in
+`SOCIAL_AUTH_OIDC_ENABLED_IDPS`, and `ISSUER` with the `iss` it sends,
+which normally matches its `oidc_url`) before starting the server
+again:
+
+```bash
+/home/zulip/deployments/current/manage.py delete_external_auth_ids --auth-method 'oidc:<YOUR_IDP_NAME>:<ISSUER>' --all-realms
+```
+
+The quotes are required, since the name contains `<` and `>`. To find
+the exact name, run the command with `--auth-method oidc`, which lists
+the names in use. Users are linked again via their email address the
+next time they log in.
:::
diff --git a/zerver/management/commands/delete_external_auth_ids.py b/zerver/management/commands/delete_external_auth_ids.py
new file mode 100644
index 00000000000..701034a2bff
--- /dev/null
+++ b/zerver/management/commands/delete_external_auth_ids.py
@@ -0,0 +1,61 @@
+from argparse import ArgumentParser
+from typing import Any
+
+from django.core.management.base import CommandError
+from django.db.models import Count
+from typing_extensions import override
+
+from zerver.lib.management import ZulipBaseCommand
+from zerver.models.users import ExternalAuthID
+
+
+class Command(ZulipBaseCommand):
+ help = """Delete the ExternalAuthIDs linking Zulip accounts to users in an LDAP
+directory or a SAML or OIDC identity provider.
+
+This is necessary when changing which attribute `unique_account_id` (LDAP) or
+`attr_user_permanent_id` (SAML) refers to, or when an identity provider starts
+sending different identifiers for existing users. Users are linked again via
+their email address the next time they log in or, for LDAP, the next time
+manage.py sync_ldap_user_data runs, whichever comes first.
+
+Examples:
+ ./manage.py delete_external_auth_ids --auth-method ldap --all-realms
+ ./manage.py delete_external_auth_ids --auth-method saml:okta -r zulip
+"""
+
+ @override
+ def add_arguments(self, parser: ArgumentParser) -> None:
+ parser.add_argument(
+ "--auth-method",
+ required=True,
+ help="The authentication method to delete ExternalAuthIDs for, e.g. ldap.",
+ )
+ target = parser.add_mutually_exclusive_group(required=True)
+ target.add_argument(
+ "--all-realms", action="store_true", help="Delete ExternalAuthIDs in all realms."
+ )
+ self.add_realm_args(target, help="Delete ExternalAuthIDs in the specified realm.")
+
+ @override
+ def handle(self, *args: Any, **options: Any) -> None:
+ realm = self.get_realm(options)
+ external_auth_ids = ExternalAuthID.objects.all()
+ if realm is not None:
+ external_auth_ids = external_auth_ids.filter(realm=realm)
+
+ auth_method = options["auth_method"]
+ to_delete = external_auth_ids.filter(external_auth_method_name=auth_method)
+ if not to_delete.exists():
+ counts = (
+ external_auth_ids.values_list("external_auth_method_name")
+ .annotate(Count("id"))
+ .order_by("external_auth_method_name")
+ )
+ present = "".join(f"\n {name} ({count})" for name, count in counts)
+ raise CommandError(
+ f"No ExternalAuthIDs for {auth_method!r}. Present:{present or ' none'}"
+ )
+
+ deleted_count, _ = to_delete.delete()
+ print(f"Deleted {deleted_count} ExternalAuthIDs for {auth_method}.")
diff --git a/zerver/tests/test_management_commands.py b/zerver/tests/test_management_commands.py
index c9959b95ec0..e21912cce9c 100644
--- a/zerver/tests/test_management_commands.py
+++ b/zerver/tests/test_management_commands.py
@@ -27,7 +27,7 @@ from zerver.models import Realm, RealmAuditLog, Recipient, UserMessage, UserProf
from zerver.models.realm_audit_logs import AuditLogEventType
from zerver.models.realms import get_realm
from zerver.models.streams import get_stream
-from zerver.models.users import get_user_profile_by_email
+from zerver.models.users import ExternalAuthID, get_user_profile_by_email
class TestWarnNoEmail(ZulipTestCase):
@@ -927,3 +927,45 @@ class TestUserChangeNotifications(ZulipTestCase):
# Verify bot did NOT receive a notification
bot_messages_after = UserMessage.objects.filter(user_profile=bot).count()
self.assertEqual(bot_messages_before, bot_messages_after)
+
+
+class TestDeleteExternalAuthIDs(ZulipTestCase):
+ def test_delete_external_auth_ids(self) -> None:
+ hamlet = self.example_user("hamlet")
+ othello = self.example_user("othello")
+ mit_user = self.mit_user("sipbtest")
+ for user, auth_method, external_auth_id in [
+ (hamlet, "ldap", "hamlet-id"),
+ (othello, "ldap", "othello-id"),
+ (hamlet, "saml:okta", "hamlet-okta-id"),
+ (mit_user, "ldap", "sipbtest-id"),
+ ]:
+ ExternalAuthID.objects.create(
+ user=user,
+ realm=user.realm,
+ external_auth_method_name=auth_method,
+ external_auth_id=external_auth_id,
+ )
+
+ with self.assertRaises(CommandError) as e:
+ call_command("delete_external_auth_ids", "--auth-method=saml:okt", "--realm=zulip")
+ self.assertEqual(
+ str(e.exception),
+ "No ExternalAuthIDs for 'saml:okt'. Present:\n ldap (2)\n saml:okta (1)",
+ )
+
+ with patch("builtins.print") as mock_print:
+ call_command("delete_external_auth_ids", "--auth-method=ldap", "--realm=zulip")
+ mock_print.assert_called_once_with("Deleted 2 ExternalAuthIDs for ldap.")
+ self.assertEqual(
+ set(ExternalAuthID.objects.values_list("user_id", "external_auth_method_name")),
+ {(hamlet.id, "saml:okta"), (mit_user.id, "ldap")},
+ )
+
+ with patch("builtins.print") as mock_print:
+ call_command("delete_external_auth_ids", "--auth-method=ldap", "--all-realms")
+ mock_print.assert_called_once_with("Deleted 1 ExternalAuthIDs for ldap.")
+ self.assertEqual(
+ set(ExternalAuthID.objects.values_list("user_id", "external_auth_method_name")),
+ {(hamlet.id, "saml:okta")},
+ )