User Management

SoCMate uses role-based access control (RBAC) to manage what each user can do on the platform. Users authenticate via Azure Entra ID and are automatically provisioned on first login with the default analyst role.

Roles

SoCMate has two roles:

Role	Description
Analyst	Standard user role for security analysts. Can create and view investigations, search, access the knowledge graph, and manage their own profile and settings.
Admin	Full platform access. All analyst permissions plus user management, SIEM provider configuration, LLM model management, API key management, and API client management.

Permissions by Role

Analyst
Admin

Area	Permissions
Investigations	Start, view, follow-up, fork, pin, delete own sessions
Incidents	View synced Sentinel incidents
Search	Full-text and semantic search across investigations
Knowledge Graph	Query entity neighborhoods and investigation subgraphs
Schedules	Create, manage, and view own scheduled investigations
Profile	Update own profile, settings, and notification preferences
Admin	No access to admin pages or endpoints

Area	Permissions
All Analyst Permissions	Everything an analyst can do
User Management	List all users, view user details, modify roles
SIEM Providers	Add, test, configure, and delete SIEM provider connections
LLM Models	Add, test, configure default, and delete LLM models
API Keys	Create, rotate, list, and disable long-lived API keys
API Clients	Create, list, regenerate secrets, and disable OAuth2 clients

User Provisioning

Users are automatically created in SoCMate on their first login via Azure Entra ID:

User clicks Sign In and authenticates with Azure Entra ID
SoCMate exchanges the authorization code for tokens
A new user record is created with:
- Azure Entra ID subject identifier
- Email address and display name from the ID token
- Default role: analyst
- Default settings (dark theme, notifications enabled)
The user is redirected to the dashboard

No manual user creation is required. Any user in your Azure Entra ID tenant with access to the SoCMate App Registration can log in.

Listing Users

Admins can view all platform users with optional search and pagination:

curl -X GET "https://api.socmate.yourcompany.com/api/admin/users?search=analyst&limit=50" \
  -H "Authorization: Bearer <admin_token>"

Response:

{
  "users": [
    {
      "id": "6507f1f77bcf86cd799439011",
      "email": "jane.analyst@example.com",
      "name": "Jane Analyst",
      "roles": ["analyst"],
      "profile": {
        "avatar_url": null,
        "department": "Security Operations",
        "job_title": "SOC Analyst L2",
        "timezone": "America/New_York"
      },
      "created_at": "2026-01-15T09:00:00Z",
      "updated_at": "2026-03-27T10:00:00Z"
    },
    {
      "id": "6507f1f77bcf86cd799439012",
      "email": "admin@example.com",
      "name": "Platform Admin",
      "roles": ["admin"],
      "profile": {
        "avatar_url": null,
        "department": "Security Engineering",
        "job_title": "Security Engineer",
        "timezone": "UTC"
      },
      "created_at": "2026-01-10T09:00:00Z",
      "updated_at": "2026-03-27T10:00:00Z"
    }
  ],
  "total": 2,
  "skip": 0,
  "limit": 50
}

Query parameters:

Parameter	Type	Default	Description
`search`	string	—	Filter by name or email
`skip`	integer	`0`	Pagination offset
`limit`	integer	`50`	Maximum results (max 100)

User Profile

Each user has a profile with optional metadata:

Field	Description
`avatar_url`	URL to the user’s avatar image
`department`	Organizational department (e.g., Security Operations)
`job_title`	Job title (e.g., SOC Analyst L2)
`timezone`	User’s timezone for schedule display and notifications

Users can update their own profile:

curl -X PATCH https://api.socmate.yourcompany.com/api/user/profile \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "department": "Security Operations",
    "job_title": "SOC Analyst L3",
    "timezone": "America/Chicago"
  }'

User Settings

Each user has configurable settings:

curl -X GET https://api.socmate.yourcompany.com/api/user/settings \
  -H "Authorization: Bearer <token>"

Response:

{
  "theme": "dark",
  "notifications": {
    "email_enabled": true,
    "sms_enabled": false,
    "push_enabled": true,
    "in_app_enabled": true
  },
  "security_alert_level": "medium",
  "email_digest_frequency": "daily",
  "quiet_hours": {
    "start": "22:00",
    "end": "08:00"
  },
  "dashboard_layout": {}
}

Update settings:

curl -X PATCH https://api.socmate.yourcompany.com/api/user/settings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "theme": "light",
    "security_alert_level": "high",
    "notifications": {
      "email_enabled": true,
      "push_enabled": false
    }
  }'

Settings Reference

Setting	Type	Default	Description
`theme`	string	`dark`	UI theme: `dark` or `light`
`security_alert_level`	string	`medium`	Minimum severity for notifications: `low`, `medium`, `high`, `critical`
`email_digest_frequency`	string	`daily`	Email digest: `realtime`, `daily`, `weekly`, `none`
`quiet_hours.start`	string	`22:00`	Start of quiet hours (no notifications)
`quiet_hours.end`	string	`08:00`	End of quiet hours

Access Control Enforcement

Role checks are enforced at the API layer. Any request to an admin endpoint without the required role returns 403 Forbidden:

{
  "detail": "Insufficient permissions"
}

UI Access Control

The SoCMate UI enforces role-based visibility:

Pages require authentication
Admin pages require the admin role
Admin navigation items are only visible to users with the admin role
Attempting to access an admin page as an analyst redirects to the dashboard

Default Role Assignment

New users receive the analyst role automatically. To change a user’s role, an admin must update it through the admin panel.

​Roles

​Permissions by Role

​User Provisioning

​Listing Users

​User Profile

​User Settings

​Settings Reference

​Access Control Enforcement

​UI Access Control

​Default Role Assignment