Add tenant switching functionality for users with multiple tenant access (#783)

### Summary & Motivation

Enable users to switch between multiple tenants when logged in with an
email that has access to multiple tenants. Previously, users with the
same email across multiple tenants could only access the first tenant
upon login. This implementation provides a complete tenant switching
solution with real-time synchronization across browser tabs.

- Add API endpoints for fetching user's tenants and switching between
them.
- Implement tenant selector UI component with pending invitation badges.
- Enable automatic copying of user name, title, avatar, and preferred
language when switching to a new tenant.
- Add invitation acceptance/decline functionality directly from the
tenant selector.
- Implement cross-tab synchronization that detects tenant or user
changes and prompts for reload.
- Store the last selected tenant in local storage for default selection
on next login.
- Add mobile-responsive tenant switcher in the mobile menu.
- Include comprehensive end-to-end tests for all tenant switching
scenarios.

### Downstream projects

Update `your-self-contained-system/WebApp/routes/__root.tsx` to
integrate the federated AuthSyncModal component for cross-tab
synchronization:

```diff
+import { AuthSyncModal } from "@repo/infrastructure/auth/AuthSyncModal";
 import { Outlet, createRootRoute, useNavigate } from "@tanstack/react-router";
+import { lazy } from "react";
+
+// biome-ignore lint/suspicious/noExplicitAny: Federated module import from account-management where type is not known
+const FederatedAuthSyncModal = lazy(() => import("account-management/AuthSyncModal" as any));

      <AuthenticationProvider navigate={(options) => navigate(options)}>
        <AddToHomescreen />
        <PageTracker />
        <Outlet />
+       <AuthSyncModal modalComponent={FederatedAuthSyncModal} />
      </AuthenticationProvider>
```

### Checklist

- [x] I have added tests, or done manual regression tests
- [x] I have updated the documentation, if necessary

Author: tjementum

application/account-management/Api/Endpoints/AuthenticationEndpoints.cs

@@ -19,18 +19,22 @@ public void MapEndpoints(IEndpointRouteBuilder routes)
             => await mediator.Send(command)
         ).Produces<StartLoginResponse>().AllowAnonymous();
 
-        group.MapPost("login/{id}/complete", async Task<ApiResult> (LoginId id, CompleteLoginCommand command, IMediator mediator)
+        group.MapPost("/login/{id}/complete", async Task<ApiResult> (LoginId id, CompleteLoginCommand command, IMediator mediator)
             => await mediator.Send(command with { Id = id })
         ).AllowAnonymous();
 
-        group.MapPost("login/{emailConfirmationId}/resend-code", async Task<ApiResult<ResendEmailConfirmationCodeResponse>> (EmailConfirmationId emailConfirmationId, IMediator mediator)
+        group.MapPost("/login/{emailConfirmationId}/resend-code", async Task<ApiResult<ResendEmailConfirmationCodeResponse>> (EmailConfirmationId emailConfirmationId, IMediator mediator)
             => await mediator.Send(new ResendEmailConfirmationCodeCommand { Id = emailConfirmationId })
         ).Produces<ResendEmailConfirmationCodeResponse>().AllowAnonymous();
 
-        group.MapPost("logout", async Task<ApiResult> (IMediator mediator)
+        group.MapPost("/logout", async Task<ApiResult> (IMediator mediator)
             => await mediator.Send(new LogoutCommand())
         );
 
+        group.MapPost("/switch-tenant", async Task<ApiResult> (SwitchTenantCommand command, IMediator mediator)
+            => await mediator.Send(command)
+        );
+
         // Note: This endpoint must be called with the refresh token as Bearer token in the Authorization header
         routes.MapPost("/internal-api/account-management/authentication/refresh-authentication-tokens", async Task<ApiResult> (IMediator mediator)
             => await mediator.Send(new RefreshAuthenticationTokensCommand())

application/account-management/Api/Endpoints/SignupEndpoints.cs

@@ -18,11 +18,11 @@ public void MapEndpoints(IEndpointRouteBuilder routes)
             => await mediator.Send(command)
         ).Produces<StartSignupResponse>().AllowAnonymous();
 
-        group.MapPost("{emailConfirmationId}/complete", async Task<ApiResult> (EmailConfirmationId emailConfirmationId, CompleteSignupCommand command, IMediator mediator)
+        group.MapPost("/{emailConfirmationId}/complete", async Task<ApiResult> (EmailConfirmationId emailConfirmationId, CompleteSignupCommand command, IMediator mediator)
             => await mediator.Send(command with { EmailConfirmationId = emailConfirmationId })
         ).AllowAnonymous();
 
-        group.MapPost("{emailConfirmationId}/resend-code", async Task<ApiResult<ResendEmailConfirmationCodeResponse>> (EmailConfirmationId emailConfirmationId, IMediator mediator)
+        group.MapPost("/{emailConfirmationId}/resend-code", async Task<ApiResult<ResendEmailConfirmationCodeResponse>> (EmailConfirmationId emailConfirmationId, IMediator mediator)
             => await mediator.Send(new ResendEmailConfirmationCodeCommand { Id = emailConfirmationId })
         ).Produces<ResendEmailConfirmationCodeResponse>().AllowAnonymous();
     }

application/account-management/Api/Endpoints/TenantEndpoints.cs

@@ -22,6 +22,10 @@ public void MapEndpoints(IEndpointRouteBuilder routes)
             => (await mediator.Send(command)).AddRefreshAuthenticationTokens()
         );
 
+        group.MapGet("/", async Task<ApiResult<GetTenantsForUserResponse>> (IMediator mediator)
+            => await mediator.Send(new GetTenantsForUserQuery())
+        ).Produces<GetTenantsForUserResponse>();
+
         group.MapPost("/current/update-logo", async Task<ApiResult> (IFormFile file, IMediator mediator)
             => await mediator.Send(new UpdateTenantLogoCommand(file.OpenReadStream(), file.ContentType))
         ).DisableAntiforgery();

application/account-management/Api/Endpoints/UserEndpoints.cs

@@ -42,6 +42,10 @@ public void MapEndpoints(IEndpointRouteBuilder routes)
             => await mediator.Send(command)
         );
 
+        group.MapPost("/decline-invitation", async Task<ApiResult> (DeclineInvitationCommand command, IMediator mediator)
+            => await mediator.Send(command)
+        );
+
         // The following endpoints are for the current user only
         group.MapGet("/me", async Task<ApiResult<CurrentUserResponse>> ([AsParameters] GetUserQuery query, IMediator mediator)
             => await mediator.Send(query)

application/account-management/Core/Configuration.cs

@@ -1,7 +1,6 @@
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Hosting;
 using PlatformPlatform.AccountManagement.Database;
-using PlatformPlatform.AccountManagement.Features.Tenants;
 using PlatformPlatform.AccountManagement.Features.Users.Shared;
 using PlatformPlatform.AccountManagement.Integrations.Gravatar;
 using PlatformPlatform.SharedKernel.Configuration;
@@ -29,8 +28,6 @@ public static IServiceCollection AddAccountManagementServices(this IServiceColle
             }
         );
 
-        TenantMapsterConfig.Configure();
-
         return services
             .AddSharedServices<AccountManagementDbContext>(Assembly)
             .AddScoped<AvatarUpdater>()

application/account-management/Core/Features/Authentication/Commands/CompleteLogin.cs

@@ -6,12 +6,13 @@
 using PlatformPlatform.AccountManagement.Integrations.Gravatar;
 using PlatformPlatform.SharedKernel.Authentication.TokenGeneration;
 using PlatformPlatform.SharedKernel.Cqrs;
+using PlatformPlatform.SharedKernel.Domain;
 using PlatformPlatform.SharedKernel.Telemetry;
 
 namespace PlatformPlatform.AccountManagement.Features.Authentication.Commands;
 
 [PublicAPI]
-public sealed record CompleteLoginCommand(string OneTimePassword) : ICommand, IRequest<Result>
+public sealed record CompleteLoginCommand(string OneTimePassword, TenantId? PreferredTenantId = null) : ICommand, IRequest<Result>
 {
     [JsonIgnore] // Removes this property from the API contract
     public LoginId Id { get; init; } = null!;
@@ -32,7 +33,6 @@ ILogger<CompleteLoginHandler> logger
     public async Task<Result> Handle(CompleteLoginCommand command, CancellationToken cancellationToken)
     {
         var login = await loginRepository.GetByIdAsync(command.Id, cancellationToken);
-
         if (login is null)
         {
             // For security, avoid confirming the existence of login IDs
@@ -42,7 +42,7 @@ public async Task<Result> Handle(CompleteLoginCommand command, CancellationToken
         if (login.Completed)
         {
             logger.LogWarning("Login with id '{LoginId}' has already been completed", login.Id);
-            return Result.BadRequest($"The login process {login.Id} for user {login.UserId} has already been completed.");
+            return Result.BadRequest($"The login process '{login.Id}' for user '{login.UserId}' has already been completed.");
         }
 
         var completeEmailConfirmationResult = await mediator.Send(
@@ -54,6 +54,18 @@ public async Task<Result> Handle(CompleteLoginCommand command, CancellationToken
 
         var user = (await userRepository.GetByIdUnfilteredAsync(login.UserId, cancellationToken))!;
 
+        // Check if PreferredTenantId is provided and valid
+        if (command.PreferredTenantId is not null)
+        {
+            var usersWithSameEmail = await userRepository.GetUsersByEmailUnfilteredAsync(user.Email, cancellationToken);
+            var preferredTenantUser = usersWithSameEmail.SingleOrDefault(u => u.TenantId == command.PreferredTenantId);
+
+            if (preferredTenantUser is not null)
+            {
+                user = preferredTenantUser;
+            }
+        }
+
         if (!user.EmailConfirmed)
         {
             CompleteUserInvite(user);

application/account-management/Core/Features/Authentication/Commands/RefreshAuthenticationTokens.cs

@@ -31,39 +31,39 @@ public async Task<Result> Handle(RefreshAuthenticationTokensCommand command, Can
         if (!UserId.TryParse(httpContext.User.FindFirstValue(ClaimTypes.NameIdentifier), out var userId))
         {
             logger.LogWarning("No valid 'sub' claim found in refresh token");
-            return Result.Unauthorized("Invalid refresh token");
+            return Result.Unauthorized("Invalid refresh token.");
         }
 
         if (!RefreshTokenId.TryParse(httpContext.User.FindFirstValue("rtid"), out var refreshTokenId))
         {
             logger.LogWarning("No valid 'rtid' claim found in refresh token");
-            return Result.Unauthorized("Invalid refresh token");
+            return Result.Unauthorized("Invalid refresh token.");
         }
 
         if (!int.TryParse(httpContext.User.FindFirstValue("rtv"), out var refreshTokenVersion))
         {
             logger.LogWarning("No valid 'rtv' claim found in refresh token");
-            return Result.Unauthorized("Invalid refresh token");
+            return Result.Unauthorized("Invalid refresh token.");
         }
 
         var jwtId = httpContext.User.FindFirstValue(JwtRegisteredClaimNames.Jti);
         if (jwtId is null)
         {
             logger.LogWarning("No 'jti' claim found in refresh token");
-            return Result.Unauthorized("Invalid refresh token");
+            return Result.Unauthorized("Invalid refresh token.");
         }
 
         var expiresClaim = httpContext.User.FindFirstValue(JwtRegisteredClaimNames.Exp);
         if (expiresClaim is null)
         {
             logger.LogWarning("No 'exp' claim found in refresh token");
-            return Result.Unauthorized("Invalid refresh token");
+            return Result.Unauthorized("Invalid refresh token.");
         }
 
         if (!long.TryParse(expiresClaim, out var expiresUnixSeconds))
         {
             logger.LogWarning("Invalid 'exp' claim format in refresh token");
-            return Result.Unauthorized("Invalid refresh token");
+            return Result.Unauthorized("Invalid refresh token.");
         }
 
         var refreshTokenExpires = DateTimeOffset.FromUnixTimeSeconds(expiresUnixSeconds);
@@ -72,7 +72,7 @@ public async Task<Result> Handle(RefreshAuthenticationTokensCommand command, Can
         if (user is null)
         {
             logger.LogWarning("No user found with user id {UserId} found", userId);
-            return Result.Unauthorized($"No user found with user id {userId} found.");
+            return Result.Unauthorized($"No user found with user id '{userId}' found.");
         }
 
         // TODO: Check if the refreshTokenId exists in the database and if the jwtId and refreshTokenVersion are valid

application/account-management/Core/Features/Authentication/Commands/SwitchTenant.cs

@@ -0,0 +1,88 @@
+using JetBrains.Annotations;
+using Microsoft.Extensions.DependencyInjection;
+using PlatformPlatform.AccountManagement.Features.Users.Domain;
+using PlatformPlatform.AccountManagement.Features.Users.Shared;
+using PlatformPlatform.SharedKernel.Authentication.TokenGeneration;
+using PlatformPlatform.SharedKernel.Cqrs;
+using PlatformPlatform.SharedKernel.Domain;
+using PlatformPlatform.SharedKernel.ExecutionContext;
+using PlatformPlatform.SharedKernel.Integrations.BlobStorage;
+using PlatformPlatform.SharedKernel.Telemetry;
+
+namespace PlatformPlatform.AccountManagement.Features.Authentication.Commands;
+
+[PublicAPI]
+public sealed record SwitchTenantCommand(TenantId TenantId) : ICommand, IRequest<Result>;
+
+public sealed class SwitchTenantHandler(
+    IUserRepository userRepository,
+    UserInfoFactory userInfoFactory,
+    AuthenticationTokenService authenticationTokenService,
+    AvatarUpdater avatarUpdater,
+    [FromKeyedServices("account-management-storage")]
+    BlobStorageClient blobStorageClient,
+    IExecutionContext executionContext,
+    ITelemetryEventsCollector events,
+    ILogger<SwitchTenantHandler> logger
+) : IRequestHandler<SwitchTenantCommand, Result>
+{
+    public async Task<Result> Handle(SwitchTenantCommand command, CancellationToken cancellationToken)
+    {
+        var users = await userRepository.GetUsersByEmailUnfilteredAsync(executionContext.UserInfo.Email!, cancellationToken);
+        var targetUser = users.SingleOrDefault(u => u.TenantId == command.TenantId);
+        if (targetUser is null)
+        {
+            logger.LogWarning("UserId '{UserId}' does not have access to TenantId '{TenantId}'", executionContext.UserInfo.Id, command.TenantId);
+            return Result.Forbidden($"User does not have access to tenant '{command.TenantId}'.");
+        }
+
+        // If the user's email is not confirmed, confirm it and copy profile data from current user
+        if (!targetUser.EmailConfirmed)
+        {
+            await CopyProfileDataFromCurrentUser(targetUser, cancellationToken);
+        }
+
+        var userInfo = await userInfoFactory.CreateUserInfoAsync(targetUser, cancellationToken);
+        authenticationTokenService.CreateAndSetAuthenticationTokens(userInfo);
+
+        events.CollectEvent(new TenantSwitched(executionContext.TenantId!, command.TenantId, targetUser.Id));
+
+        return Result.Success();
+    }
+
+    private async Task CopyProfileDataFromCurrentUser(User targetUser, CancellationToken cancellationToken)
+    {
+        // Get the current user to copy profile data from
+        var currentUser = await userRepository.GetByIdUnfilteredAsync(executionContext.UserInfo.Id!, cancellationToken);
+        targetUser.Update(
+            currentUser!.FirstName ?? targetUser.FirstName ?? "",
+            currentUser.LastName ?? targetUser.LastName ?? "",
+            currentUser.Title ?? targetUser.Title ?? ""
+        );
+
+        // Copy locale (preferred language)
+        targetUser.ChangeLocale(currentUser.Locale);
+
+        // Copy avatar if the current user has one
+        if (targetUser.Avatar.Url is null && currentUser.Avatar.Url?.StartsWith("/avatars/") == true)
+        {
+            // Blob-stored avatar - copy the blob to the new tenant
+            var sourceBlobPath = currentUser.Avatar.Url[9..]; // Skip "/avatars/" prefix
+
+            // Download the avatar blob from the source tenant
+            var avatarData = await blobStorageClient.DownloadAsync("avatars", sourceBlobPath, cancellationToken);
+            if (avatarData is not null)
+            {
+                // Upload the avatar to the target tenant's storage location
+                await avatarUpdater.UpdateAvatar(targetUser, false, avatarData.Value.ContentType, avatarData.Value.Stream, cancellationToken);
+            }
+        }
+
+        targetUser.ConfirmEmail();
+        userRepository.Update(targetUser);
+
+        // Calculate how long it took to accept the invitation
+        var inviteAcceptedTimeInMinutes = (int)(DateTimeOffset.UtcNow - targetUser.CreatedAt).TotalMinutes;
+        events.CollectEvent(new UserInviteAccepted(targetUser.Id, inviteAcceptedTimeInMinutes));
+    }
+}

application/account-management/Core/Features/TelemetryEvents.cs

@@ -57,6 +57,9 @@ public sealed class TenantLogoRemoved
 public sealed class TenantLogoUpdated(string contentType, long size)
     : TelemetryEvent(("content_type", contentType), ("size", size));
 
+public sealed class TenantSwitched(TenantId fromTenantId, TenantId toTenantId, UserId userId)
+    : TelemetryEvent(("from_tenant_id", fromTenantId), ("to_tenant_id", toTenantId), ("user_id", userId));
+
 public sealed class TenantUpdated
     : TelemetryEvent;
 
@@ -81,6 +84,9 @@ public sealed class UsersBulkDeleted(int count)
 public sealed class UserInviteAccepted(UserId userId, int inviteAcceptedTimeInMinutes)
     : TelemetryEvent(("user_id", userId), ("invite_accepted_time_in_minutes", inviteAcceptedTimeInMinutes));
 
+public sealed class UserInviteDeclined(UserId userId, int inviteExistedTimeInMinutes)
+    : TelemetryEvent(("user_id", userId), ("invite_existed_time_in_minutes", inviteExistedTimeInMinutes));
+
 public sealed class UserInvited(UserId userId)
     : TelemetryEvent(("user_id", userId));
 

application/account-management/Core/Features/Tenants/Domain/TenantRepository.cs

@@ -1,3 +1,4 @@
+using Microsoft.EntityFrameworkCore;
 using PlatformPlatform.AccountManagement.Database;
 using PlatformPlatform.SharedKernel.Domain;
 using PlatformPlatform.SharedKernel.ExecutionContext;
@@ -10,6 +11,8 @@ public interface ITenantRepository : ICrudRepository<Tenant, TenantId>
     Task<Tenant> GetCurrentTenantAsync(CancellationToken cancellationToken);
 
     Task<bool> ExistsAsync(TenantId id, CancellationToken cancellationToken);
+
+    Task<Tenant[]> GetByIdsAsync(TenantId[] ids, CancellationToken cancellationToken);
 }
 
 internal sealed class TenantRepository(AccountManagementDbContext accountManagementDbContext, IExecutionContext executionContext)
@@ -21,4 +24,9 @@ public async Task<Tenant> GetCurrentTenantAsync(CancellationToken cancellationTo
         return await GetByIdAsync(executionContext.TenantId, cancellationToken) ??
                throw new InvalidOperationException("Active tenant not found.");
     }
+
+    public async Task<Tenant[]> GetByIdsAsync(TenantId[] ids, CancellationToken cancellationToken)
+    {
+        return await DbSet.Where(t => ids.Contains(t.Id)).ToArrayAsync(cancellationToken);
+    }
 }