---
title: "Users & Identity Governance"
description: "Documentation for Users"
---

## Table of Contents
1. [Overview & Identity Architecture](#1-overview--identity-architecture)
2. [Business & Operational Significance](#2-business--operational-significance)
3. [🎯 User Roles & Key Capabilities](#3--user-roles--key-capabilities)
4. [Visual Interface & Layout](#4-visual-interface--layout)
5. [Field Reference & User Configuration Parameters](#5-field-reference--user-configuration-parameters)
6. [Cryptographic Security & Session Governance](#6-cryptographic-security--session-governance)
7. [The Four-Pillar Access Control Binding](#7-the-four-pillar-access-control-binding)
8. [Troubleshooting & Verification](#8-troubleshooting--verification)
9. [Model Context Protocol (MCP) AI Integration](#9-model-context-protocol-mcp-ai-integration)
10. [Glossary](#10-glossary)

---

## 1. Overview & Identity Architecture

In **Ring2All SBC**, the **Users** module provides enterprise-grade identity lifecycle management, zero-trust authentication, and administrative access governance across the session border controller. Every administrative identity in the platform is anchored by an immutable identifier (numeric `id` and `uuid`) and governed by an orthogonal access framework that separates UI permissions, audit logging, and artificial intelligence capabilities.

```
                  ┌─────────────────────────────────────────────────┐
                  │                 USER ACCOUNT                    │
                  │   (Auth: Argon2id, JWT, MFA, Multi-Tenant)      │
                  └────────┬────────────────┬────────────────┬──────┘
                           │                │                │
          ┌────────────────▼───┐  ┌─────────▼──────────┐  ┌──▼────────────────┐
          │    ROLE PROFILE    │  │    LOG PROFILE     │  │   MCP TOOL ROLE   │
          │   (RBAC Modules)   │  │ (Audit & Notif.)   │  │   (AI Tools RBAC) │
          ├────────────────────┤  ├────────────────────┤  ├───────────────────┤
          │ • Read / List      │  │ • Log Create       │  │ • Kamailio RPC    │
          │ • Create / Insert  │  │ • Log Edit         │  │ • RTPEngine QoS   │
          │ • Edit / Update    │  │ • Log Delete       │  │ • Dispatchers     │
          │ • Delete / Destroy │  │ • Push / Email Not.│  │ • CDR Telemetry   │
          └────────────────────┘  └────────────────────┘  └───────────────────┘
```

Authentication credentials are encrypted using the **Argon2id** password hashing algorithm (64 MB RAM, 3 iterations), offering state-of-the-art resistance against GPU-accelerated brute force attacks and side-channel vulnerabilities.

---

## 2. Business & Operational Significance

* **Zero-Trust Administrative Perimeter**: Restricts access to sensitive telecom routing tables, TLS private keys, and Kamailio memory registers to explicitly authenticated and authorized staff.
* **Segregation of Duties (SoD)**: Ensures that network engineers can manage SIP trunks and carriers without granting them permission to alter audit log profiles or generate administrative API keys.
* **Non-Repudiation & Audit Attribution**: Binds every SIP routing modification, dispatcher reload, or IP unban action directly to a verifiable user account, satisfying telecom compliance mandates (SOX, ISO 27001, PCI-DSS).
* **Immutable Identity Governance**: Strictly utilizes immutable numeric IDs (`user_id`) and UUIDs rather than mutable usernames or slugs, preventing permission inheritance errors and privilege escalation during administrative updates.

---

## 3. 🎯 User Roles & Key Capabilities

| Role | Primary Use Case | Key Capabilities |
| :--- | :--- | :--- |
| **SBC Super Administrator** | Global Identity & Security Oversight | Provision administrative accounts, assign root role profiles, reset multi-factor credentials, and revoke sessions. |
| **NOC Team Lead** | Operational Workforce Onboarding | Create operator accounts for Tier-1/2 engineers, assign standard telemetry view roles, and monitor shift logins. |
| **Security & Compliance Auditor** | Access Governance & Credential Auditing | Inspect inactive accounts, enforce password expiration policies, and verify orthogonal profile allocations. |
| **Systems Administrator** | Multi-Tenant Partitioning | Assign tenant scopes to accounts, restricting visibility to dedicated carrier trunks and private domain groups. |
| **AI Platform Copilot / Administration Agent** | Automated Identity Governance & Status Auditing | Programmatically query operator accounts, audit role mappings, verify superuser segregation, and toggle compromised accounts via MCP. |

---

## 4. Visual Interface & Layout

The Users interface consists of a centralized DataGrid view showing all platform users and their profile assignments, along with a high-density configuration form for user onboarding.

### 4.1 Users Management List View
Displays all registered user accounts, active statuses, assigned role profiles, log profiles, MCP roles, and last login timestamps.

![Users Management List View](/screenshots/sbc/admin/users/users-list.png)

### 4.2 User Configuration Form
Presents account identity fields, Argon2id password controls, and dropdown selectors for the three orthogonal security profiles.

![User Configuration Form](/screenshots/sbc/admin/users/users-form.png)

---

## 5. Field Reference & User Configuration Parameters

| Field Name | Type | Options / Format | Description |
| :--- | :--- | :--- | :--- |
| **Username** | String | Alphanumeric (e.g., `admin`, `noc_tier2`) | Unique login identifier used during authentication. |
| **Email Address** | Email | Standard email format | Official contact address used for system alarm notifications and password resets. |
| **Password** | Password | Strong password format | Plaintext password input, automatically hashed with Argon2id upon form submission. |
| **Account Status** | Switch | `Active` / `Disabled` | Toggle to immediately permit or suspend system access without deleting historical records. |
| **Role Profile** | Select | Foreign Key (`role_profiles.id`) | Assigns the RBAC module permission profile determining accessible menus and CRUD actions. |
| **Log Profile** | Select | Foreign Key (`log_profiles.id`) | Assigns the audit logging policy determining which actions by this user are recorded in `audit_log`. |
| **MCP Tool Role** | Select | Foreign Key (`mcp_roles.id`) | Assigns the AI copilot governance role restricting which telephony tools an assistant can call. |
| **Tenant ID** | Select / Int | Nullable Integer | Multi-tenant partition. `NULL` grants global superadmin scope across all SBC domains and trunks. |
| **Timezone** | Select | Standard IANA (e.g., `UTC`, `America/New_York`) | Localizes timestamps across CDRs, SIP trace ladder diagrams, and system audit views. |

---

## 6. Cryptographic Security & Session Governance

Ring2All SBC enforces strict cryptographic standards across the authentication pipeline:

```typescript
// Argon2id Password Hashing Standard
export async function hashPassword(password: string): Promise<string> {
  return await argon2.hash(password, {
    type: argon2.argon2id,
    memoryCost: 65536, // 64 MB
    timeCost: 3,       // 3 iterations
    parallelism: 1,
  });
}
```

* **Stateless JWT Authorization**: API sessions utilize signed JSON Web Tokens (JWT) containing user UUID, role permissions, and tenant scope.
* **Token Rotation**: Refresh tokens are stored with one-way SHA-256 hashes and rotated upon every renewal cycle.
* **Slug Prohibition**: User identification in SQL queries and API middleware is executed strictly via numeric `id` or `uuid`. Mutable fields (`username`) are strictly prohibited as database foreign keys.

---

## 7. The Four-Pillar Access Control Binding

Every account created on the SBC must link to four discrete authorization pillars:

1. **Identity & Tenant Pillar (`users.tenant_id`)**: Isolates database queries and SIP routing policies so operators only see their assigned domains and carrier groups.
2. **RBAC Module Pillar (`users.role_profile_id`)**: Dictates front-end UI element rendering and REST endpoint authorization (`GET`, `POST`, `PUT`, `DELETE`).
3. **Audit Logging Pillar (`users.log_profile_id`)**: Determines whether routine actions (viewing a CDR or toggling a carrier) trigger detailed database audit entries or email alerts.
4. **AI Tool Governance Pillar (`users.mcp_role_id`)**: Dictates the tool execution boundaries of the AI NOC Copilot when operating in the user's context.

---

## 8. Troubleshooting & Verification

### Inspecting User Accounts via Database Console
To verify user profile mappings on the SBC host:
```bash
sudo -u postgres psql -d sbc_admin -c "
SELECT u.id, u.username, u.email, u.is_active, 
       r.name AS role_profile, 
       l.name AS log_profile, 
       m.name AS mcp_role
FROM users u
LEFT JOIN role_profiles r ON r.id = u.role_profile_id
LEFT JOIN log_profiles l ON l.id = u.log_profile_id
LEFT JOIN mcp_roles m ON m.id = u.mcp_role_id;
"
```

### Resetting Administrator Credentials via CLI
If the master administrative password is lost:
```bash
node -e "
const argon2 = require('argon2');
argon2.hash('NewSecurePassword123!', { type: argon2.argon2id, memoryCost: 65536, timeCost: 3 })
  .then(h => console.log('UPDATE users SET password_hash = \'' + h + '\' WHERE username = \'admin\';'));
" | sudo -u postgres psql -d sbc_admin
```

---

## 9. Model Context Protocol (MCP) AI Integration

Ring2All SBC exposes dedicated Model Context Protocol (MCP) tools enabling AI agents, autonomous NOC bots, and administrative copilot assistants to query, audit, and manage user operator accounts securely.

### Available MCP Tools

| Tool Name | Operation | Risk Level | Description |
| :--- | :--- | :--- | :--- |
| `list_sbc_users` | Read | Low (`read`) | List operator user accounts in Ring2All SBC with assigned role profiles, log profiles, MCP tool profiles, status, and last login. |
| `get_sbc_user` | Read | Low (`read`) | Retrieve comprehensive profile, timezone, language, and permission matrix for a specific user by UUID or username. |
| `update_sbc_user_status` | Mutate | High (`operational`) | Enable or disable an administrative operator account to immediately grant or revoke SBC management access. |

### Tool Schemas & Parameter Definitions

#### `list_sbc_users`
```json
{
  "name": "list_sbc_users",
  "description": "List operator user accounts in Ring2All SBC, including assigned role profiles, log profiles, MCP tool profiles, account status, and last login timestamps.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Optional filter by username, email, or full name"
      },
      "limit": {
        "type": "number",
        "description": "Maximum number of users to return (default 50)"
      },
      "offset": {
        "type": "number",
        "description": "Pagination offset (default 0)"
      }
    }
  }
}
```

#### `get_sbc_user`
```json
{
  "name": "get_sbc_user",
  "description": "Get detailed profile and permission settings for a specific SBC user by UUID or username.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "identifier": {
        "type": "string",
        "description": "User UUID or username to query"
      }
    },
    "required": ["identifier"]
  }
}
```

#### `update_sbc_user_status`
```json
{
  "name": "update_sbc_user_status",
  "description": "Enable or disable an administrative operator user account in Ring2All SBC.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "identifier": {
        "type": "string",
        "description": "User UUID or username"
      },
      "isActive": {
        "type": "boolean",
        "description": "True to activate, false to suspend/disable"
      }
    },
    "required": ["identifier", "isActive"]
  }
}
```

### Realistic Payload Examples

#### Query Request (`get_sbc_user`)
```json
{
  "identifier": "admin"
}
```

#### Successful Response (`get_sbc_user`)
```json
{
  "success": true,
  "data": {
    "user": {
      "uuid": "4f18d7a3-b09e-4a6f-99c7-542e7b89d102",
      "username": "admin",
      "email": "admin@ring2all.com",
      "full_name": "SBC Super Administrator",
      "is_active": true,
      "is_superuser": true,
      "timezone": "America/New_York",
      "language": "en",
      "last_login_at": "2026-09-08T11:20:00Z",
      "created_at": "2026-01-15T08:00:00Z",
      "updated_at": "2026-09-08T11:20:00Z",
      "role_uuid": "e2a1b94d-1763-4cbb-9271-9dfa542b01c3",
      "role_name": "Super Administrator",
      "role_slug": "super-admin",
      "log_uuid": "b8f41029-47aa-4831-a068-3e5fa809d841",
      "log_name": "Full Verbose Audit",
      "log_level": "DEBUG",
      "mcp_role_uuid": "d3b4e720-c9fa-47eb-9403-99b821a8cd34",
      "mcp_role_name": "SBC NOC Super Administrator (Full Access)",
      "mcp_role_slug": "super-admin"
    }
  }
}
```

### Natural Language Prompt Scenarios

#### English (NOC Security Audit)
> *"Check the list of all active operator accounts on Ring2All SBC and verify if any account has been inactive for more than 30 days or is lacking a role profile assignment."*

#### Spanish (Mitigación Inmediata de Cuenta Comprometida)
> *"Desactiva de inmediato la cuenta del operador 'noc_guest' debido a múltiples intentos fallidos de autenticación detectados en el firewall perimetral."*

### Enterprise AI Safety Guardrails
* **Zero Credential Exposure**: Password hashes (`password_hash`, Argon2id salts) and raw session tokens are strictly omitted from all MCP data serialization pipelines.
* **Superuser Deactivation Immunity**: The system prevents autonomous agents from disabling the final active superuser account, guaranteeing that human administrators can never be locked out of SBC governance.

---

## 10. Glossary

* **Argon2id**: The winner of the Password Hashing Competition (PHC), combining resistance against side-channel and GPU cracking attacks.
* **RBAC (Role-Based Access Control)**: An access security mechanism that restricts system access to authorized users based on their organizational roles.
* **MCP (Model Context Protocol)**: An open standard protocol that enables AI models to interact securely with local telephony tools and databases.
* **Immutable Identifier**: A database key (such as an integer sequence or UUID v4) that remains constant throughout an entity's lifecycle.