---
title: "Optimizing Client Selection for Multi-Tenant Authentication"
slug: "auth-client-selection-in-multi-tenant-architecture"
updated: 2025-02-20T20:35:14Z
published: 2025-02-20T20:35:14Z
canonical: "docs.agilenow.io/auth-client-selection-in-multi-tenant-architecture"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agilenow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Optimizing Client Selection for Multi-Tenant Authentication

This system ensures **secure and structured authentication client selection** within a **multi-tenant environment**, allowing users to switch between tenants while **maintaining domain-based restrictions**.

- The **master tenant** has access to its child tenants.
- **Child tenants** may share the same domain as the master or have unique domain addresses.
- Users can **switch tenants only within the master-child scope** but cannot access tenants beyond what the master tenant owns.

This logic ensures that **authentication clients are retrieved correctly while respecting domain-based isolation**.

### **Authentication Client Selection Logic**

The system follows a structured process to determine the correct authentication client when an **end-user logs in via a web browser or an OAuth2-based authentication method**.

#### **1. Retrieve Active Authentication Clients for the Given `Client ID`**

- Filters **only active authentication clients** to ensure valid connections.
- Limits selection to **clients belonging to the master tenant or its child tenants**.
- Uses the **Workspace** table to **determine which tenants belong to the scope**.

#### **2. Prioritize Authentication Clients Based on Domain**

- If multiple authentication clients exist for the same `Client ID`, **the system prioritizes the one matching the workspace domain**.

#### **3. Sort and Select the Best Match**

- If multiple authentication clients still exist after domain filtering, the system applies a **priority-based selection process**:
  - **For Web-Based Logins:**  

**`Internal provider` → `IdPs (Identity Providers)` → `OAuth2 authentication`**
  - **For Token-Based Authentication (OAuth2 Standard):**  

**`Internal provider` → `OAuth2 authentication`** (Other IdP client types, such as Microsoft Entra, are **not supported**).
- Uses **`ROW_NUMBER()`** to **ensure only the highest-priority authentication client is selected**.

### **How the Selection Works**

#### **Step 1: Retrieve Active Authentication Clients Within Tenant Scope**

- The first step gathers **all authentication clients** that belong to the **master tenant or its child tenants**, ensuring that the user cannot retrieve authentication clients outside this scope.

#### **Step 2: Domain Filtering**

- If multiple authentication clients exist for the same `Client ID`, the system **prioritizes clients that belong to the matching workspace domain**.

#### **Step 3: Dynamic Sorting and Selection**

- If multiple authentication clients still exist after domain filtering, it applies **ordering rules**, ensuring the best match is selected.

### **Tenant Switching Logic**

The authentication system follows strict **master-child tenant rules** to control access:

| **Scenario** | **Access Behavior** |
| --- | --- |
| **Master Tenant** | Has access to all its child tenants. |
| **Child Tenant** | Can only access itself and other child tenants under the same master. |
| **Master and Child Share the Same Domain** | The selection logic ensures the correct authentication client is used based on the domain. |
| **User Tries to Access an Unauthorized Tenant** | The system prevents access to tenants beyond the master’s scope. |

---

### **Expected Behavior**

| **Scenario** | **Expected Authentication Client Selection** |
| --- | --- |
| **Single authentication client exists for the `Client ID`** | The system selects that client. |
| **Multiple authentication clients exist within scope** | The system prioritizes clients that match the workspace domain. |
| **Still multiple authentication clients exist after domain filtering** | The system applies sorting: **Web-Based (`Internal provider`, `IdPs (Identity Providers)` , `OAuth2 authentication`)**, **OAuth2 Token-Based (`Internal provider`, `OAuth2 authentication`)**. |
| **No matching authentication client found** | No result is returned. |
| **User tries to switch tenants beyond master-child scope** | The system prevents unauthorized access. |

---

### **Key Benefits**

✅ **Ensures correct authentication client selection across multi-tenant environments.** ✅ **Restricts access to only the master tenant and its child tenants.** ✅ **Supports domain-specific authentication client prioritization.** ✅ **Prevents unauthorized tenant switching beyond the master’s scope.** ✅ **Optimizes authentication flows by dynamically selecting the best client.**

This authentication selection logic ensures **secure, structured, and flexible user authentication**, aligning with **Agile.Now’s multi-tenant architecture**.