SecurityPrincipal

Represents any entity that can be authenticated and authorized in the system, providing a unified abstraction for users, service accounts, API clients, and automated systems. A security principal is anything that can have permissions and make requests - it could be a human user, a microservice, an IoT device, a scheduled job, or an external system. This abstraction allows the access control system to treat all these entities consistently while maintaining their unique characteristics. Each principal has credentials for authentication (passwords, certificates, keys), attributes for authorization decisions (clearance level, department, trust score), and a security context that defines their capabilities. Service principals enable machine-to-machine authentication without user involvement, essential for automated workflows and microservices. System principals represent internal components that need controlled access to resources. External principals handle third-party integrations with limited, scoped access. The entity tracks the principal's lifecycle from creation through various trust states to eventual deactivation. It maintains security posture information like last security review, compliance status, and risk assessments. This unified approach simplifies access control policies - a single policy can apply to users, services, and systems without separate implementations. It's fundamental for zero-trust architectures where every request must be authenticated and authorized regardless of source.

34 properties
Schema

Properties

PropertyTypeModeDescriptionRequired
principalIduuid
stored

Unique identifier for this security principal

Required
principalTypestring
enum

Category of security principal

Values: user, service, application, device, system, external, federated

Required
principalNamestring
stored

Unique name identifier across all principals

Example: "svc_payment_processor"

Required
displayNamestring
stored

Human-friendly name for display

Example: "Payment Processing Service"

Required
descriptionstring
stored

Purpose and function of this principal

Example: "Automated service for processing customer payments and refunds"

Optional
authenticationMethodstring
enum

How this principal authenticates

Values: password, certificate, api_key, oauth, saml, kerberos, biometric, hardware_token

Required
credentialHashstring
stored

Hashed credential for authentication

Optional
certificateThumbprintstring
stored

Certificate identifier for cert-based auth

Optional
publicKeystring
stored

Public key for asymmetric authentication

Optional
realmstring
stored

Authentication realm or domain

Example: "corporate.example.com"

Optional
trustLevelinteger
stored

Trust score from 0 (untrusted) to 100 (fully trusted)

Optional
clearanceLevelinteger
stored

Security clearance level

Optional
ownerUser
stored

User responsible for this principal

Optional
organizationstring
stored

Organization this principal belongs to

Optional
departmentstring
stored

Department or team

Optional
attributesstring
stored

JSON attributes for policy evaluation

Example: "{\"location\":\"us-east-1\",\"environment\":\"production\",\"data_classification\":\"sensitive\"}"

Optional
allowedIpRangesstring
stored

JSON array of permitted IP ranges

Optional
allowedTimeWindowsstring
stored

JSON array of time-based access windows

Optional
maxConcurrentSessionsinteger
stored

Maximum simultaneous active sessions

Optional
statusstring
enum

Current status of the principal

Values: active, inactive, suspended, locked, expired, pending_approval

Optional
activatedAtDateTime
stored

When principal became active

Optional
expiresAtDateTime
stored

When principal access expires

Optional
lastAuthenticationAtDateTime
stored

Last successful authentication

Optional
lastActivityAtDateTime
stored

Last recorded activity

Optional
lastSecurityReviewDateTime
stored

Last security assessment date

Optional
nextReviewDateDateTime
stored

When next security review is due

Optional
complianceStatusstring
stored

Compliance assessment status

Optional
riskScoreinteger
stored

Current risk assessment score

Optional
isSystemboolean
stored

Whether this is a system principal

Optional
canImpersonateboolean
stored

Whether principal can act as other principals

Optional
tagsstring
stored

JSON array of tags for categorization

Optional
createdAtDateTime
stored

When principal was created

Required
createdByUser
stored

Who created this principal

Optional
metadataobject
stored

Additional principal configuration

Optional

Examples

Example 1

{
  "@type": "SecurityPrincipal",
  "principalId": "prin_svc_001",
  "principalType": "service",
  "principalName": "svc_data_pipeline",
  "displayName": "Data Pipeline Service",
  "description": "ETL service that processes and transforms customer data between systems",
  "authenticationMethod": "certificate",
  "certificateThumbprint": "3f:2a:45:67:89:ab:cd:ef:12:34:56:78:90:ab:cd:ef:12:34:56:78",
  "realm": "services.internal",
  "trustLevel": 85,
  "clearanceLevel": 3,
  "owner": "user_data_team_lead",
  "organization": "DataEngineering",
  "department": "Analytics",
  "attributes": "{\"service_type\":\"etl\",\"data_access_level\":\"full\",\"pii_handler\":true,\"sox_compliant\":true}",
  "allowedIpRanges": "[\"10.0.0.0/8\",\"172.16.0.0/12\"]",
  "maxConcurrentSessions": 5,
  "status": "active",
  "activatedAt": "2024-01-01T00:00:00Z",
  "expiresAt": "2025-01-01T00:00:00Z",
  "lastAuthenticationAt": "2024-03-15T14:00:00Z",
  "lastActivityAt": "2024-03-15T14:30:00Z",
  "lastSecurityReview": "2024-02-15T00:00:00Z",
  "nextReviewDate": "2024-05-15T00:00:00Z",
  "complianceStatus": "compliant",
  "riskScore": 25,
  "isSystem": false,
  "canImpersonate": false,
  "tags": "[\"production\",\"critical\",\"data_processor\",\"gdpr_scope\"]",
  "createdAt": "2024-01-01T00:00:00Z",
  "metadata": {
    "kubernetes_namespace": "data-services",
    "service_account": "data-pipeline-sa"
  }
}

Example 2

{
  "@type": "SecurityPrincipal",
  "principalId": "prin_ext_002",
  "principalType": "external",
  "principalName": "ext_partner_api",
  "displayName": "Partner Integration - TechCorp",
  "description": "External partner API client for inventory synchronization",
  "authenticationMethod": "api_key",
  "realm": "partners.external",
  "trustLevel": 60,
  "clearanceLevel": 1,
  "organization": "TechCorp",
  "attributes": "{\"partner_id\":\"PARTNER_123\",\"integration_type\":\"inventory\",\"rate_limit\":\"1000/hour\"}",
  "allowedIpRanges": "[\"203.0.113.0/24\"]",
  "allowedTimeWindows": "[{\"days\":[\"mon\",\"tue\",\"wed\",\"thu\",\"fri\"],\"hours\":\"00:00-23:59\"}]",
  "maxConcurrentSessions": 3,
  "status": "active",
  "activatedAt": "2024-02-01T00:00:00Z",
  "expiresAt": "2024-08-01T00:00:00Z",
  "lastAuthenticationAt": "2024-03-15T10:00:00Z",
  "lastActivityAt": "2024-03-15T10:15:00Z",
  "lastSecurityReview": "2024-02-01T00:00:00Z",
  "nextReviewDate": "2024-04-01T00:00:00Z",
  "complianceStatus": "under_review",
  "riskScore": 45,
  "isSystem": false,
  "canImpersonate": false,
  "tags": "[\"partner\",\"external\",\"limited_access\",\"inventory_only\"]",
  "createdAt": "2024-02-01T00:00:00Z",
  "metadata": {
    "contract_id": "CONTRACT_2024_001",
    "data_sharing_agreement": "DSA_2024_TC"
  }
}