Privicore
  1. Policy
Privicore
  • Privicore API
  • Utility
    • Utility
    • Check server health
      GET
    • Request command id status
      GET
  • Profile
    • Profile Model and Authentication Workflow
    • Register new profile
      POST
    • Authenticate
      POST
    • Retrieve profile id
      GET
    • Change password
      POST
    • Generate qr token for authorization
      POST
    • Reauthorize authorization token
      POST
    • Revoke authorization token
      POST
    • Retrieve token expiry
      POST
  • OAuth Application
    • OAuth Application Management
    • Register OAuth Application
      POST
    • Retrieve OAuth app configuration
      POST
    • Request OAuth app authorization code
      GET
    • Retrieve OAuth app authorization code
      POST
    • Obtain OAuth app access token
      POST
    • OAuth application list
      GET
    • Retrieve OAuth application scope
      GET
    • Refresh OAuth app access token
      POST
  • Public key
    • Public and Private Key Management
    • Generate your private and public keys
    • Register public key
    • Retrieve public key
    • Retrieve CAB public key
  • Data Token
    • Data Token Management
    • Reserve token space
    • Retrieve temporary data token
    • Exchange data for token
    • Upstream file via stream auth
    • Request data via token
    • Download data
    • Configure information security risk meta
    • Configure file meta
    • List data tokens
    • Update data token
    • Delete data
  • Device
    • Device Management
    • Request unique identifier (i.e. Register new device)
    • Retrieve unique identifier
    • Retrieve profile devices
    • Configure device meta
    • Approve device
    • Reject device
    • Retrieve device configuration
    • Remove device
  • Storage
    • Storage Device Management
    • Register storage device
    • List storage devices
    • Synchronize device
    • Remove storage
  • Verified authenticator
    • Authenticator and Voting Management
    • Register authenticator
    • List verified authenticators
    • Retrieve voting strategy
    • Set quorum size
    • Set quorum strategy
    • Set voting time limit
    • Set maximum voting attempts
    • Remove authenticator
    • Register voting configuration
    • Update voting configuration
    • List voting configurations
    • Retrieve voting configuration
  • Policy
    • Policy Management
    • List policy templates
      GET
    • Register policy
      POST
    • List active policies
      GET
    • List inactive policies
      GET
    • Activate policy
      POST
    • Deactivate policy
      POST
    • Delete policy
      POST
    • List registered policies
      GET
    • Retrieve registered policy
      GET
  • Voting
    • Voting Operations
    • Create voting
    • Check pool status
  • Websockets
    • WebSocket Integration
    • Establishing Connection
    • Join Channel
    • Leave Channel
    • Command Status Messages
    • Data Download Messages
  • Schemas
    • Response
      • CommandAccepted
      • Unauthorized
      • ValidationErrors
    • Schemas
    • profileId
    • deviceIdentifier
    • directoryId
    • directoryName
    • directoryShortName
    • givenName
    • familyName
    • createdAt
    • meta
  1. Policy

Policy Management

Introduction#

Policies are the decision-making framework within Privicore that determines when operations require authorization, which voting configurations to apply, and how different workflows should be controlled. Policies enable automated, rule-based governance of system operations based on context, user attributes, and security requirements.

What Are Policies?#

A Policy is a set of rules that:
Evaluates operations as they occur in the system
Determines whether an operation requires additional authorization
Triggers voting workflows when authorization is needed
Applies specific voting configurations to different operation types
Enables automated decision-making based on predefined criteria
Policies connect the operational layer (data tokens, authentication, device management) with the authorization layer (voting, Authenticators, approval workflows).

Policy Architecture#

Policy Evaluation Flow#

Operation Initiated (e.g., login, data upload, account change)
         ↓
Policy Engine Evaluates Active Policies
         ↓
Does Policy Match Operation? → No → Operation Proceeds
         ↓ Yes
Policy Requires Voting? → No → Operation Proceeds
         ↓ Yes
Create Poll with Configured Voting Parameters
         ↓
Distribute Ballots to Authenticators
         ↓
Collect Votes
         ↓
Resolve Poll According to Strategy
         ↓
Operation Proceeds or Fails Based on Outcome

Policy Components#

Policy Template#

A policy template is a predefined policy structure provided by Privicore that addresses common authorization scenarios. Each template defines:
Name and Description: Human-readable identification and purpose
Available Events: System operations that can trigger the policy (with event identifiers and names)
Configuration Parameters: Customizable settings that control policy behavior
Voting Attributes: Attributes evaluated when creating voting polls and determining authorization requirements
Templates serve as blueprints for creating policies with consistent structure and behavior.

Template Structure#

{
  "template-identifier": {
    "name": "Template Name",
    "description": "What this policy does and when to use it",
    "events": {
      "event-identifier-1": {
        "event-name": "Login"
      },
      "event-identifier-2": {
        "event-name": "Retrieve data"
      }
    },
    "configuration": ["parameter1", "parameter2"],
    "votingAttributes": ["attribute1", "attribute2"]
  }
}

Registered Policy#

A registered policy is created from a template and configured with specific parameters for your profile. During registration:
Select a template using its identifier
Choose which events from the template will trigger the policy
Provide custom values for configuration parameters
Associate a voting configuration for authorization workflows
Registered policies can be:
Active: Currently evaluating operations and triggering workflows
Inactive: Registered but not currently enforcing rules

Policy Conditions#

Policies evaluate conditions to determine if they should trigger:
Operation type: What action is being performed (defined by selected events)
User attributes: Profile characteristics, security classifications, roles
Context: Location, time, device, network conditions
Data attributes: Classification, size, sensitivity level (from configuration parameters)

Policy Lifecycle#

Browse Policy Templates → Select Template
         ↓
Select Events from Template → Define Triggers
         ↓
Register Policy → Configure Parameters
         ↓
Policy Created (Inactive by Default)
         ↓
Activate Policy → Begins Evaluating Operations
         ↓
Policy Triggers Voting When Conditions Match
         ↓
Deactivate Policy (optional) → Stops Evaluation
         ↓
Delete Policy (optional) → Permanent Removal

Policy Use Cases#

Multi-Factor Authentication#

Scenario: Require additional authentication when logging in from new locations.
Template: Authentication policy template with login events
Policy Configuration:
Trigger Events: Login from unrecognized location
Configuration: Location tracking enabled
Voting Configuration: Affirmative strategy (single approval)
Authenticators: User's registered phone and laptop
Time Limit: 60 seconds
Workflow:
1.
User attempts login from new location
2.
Policy detects unrecognized location via configuration parameters
3.
Ballots sent to user's Authenticators based on voting attributes
4.
User approves on phone
5.
Login proceeds

High-Security Data Operations#

Scenario: Require unanimous approval for data classified as "top-secret".
Template: Data access policy template with data retrieval events
Policy Configuration:
Trigger Events: Data token exchange, data retrieval
Configuration: Security classification = "top-secret"
Voting Configuration: Unanimous strategy
Authenticators: All registered Authenticators
Time Limit: 300 seconds
Workflow:
1.
Application attempts to exchange top-secret data for token
2.
Policy detects security classification from data attributes
3.
Ballots sent to all Authenticators
4.
All devices must approve within 5 minutes
5.
Data exchange proceeds only if all approve

Account Modification Protection#

Scenario: Require majority approval for critical account changes.
Template: Account management policy template with account modification events
Policy Configuration:
Trigger Events: Password change, email change, account deletion
Configuration: Critical operations list
Voting Configuration: Consensus strategy (majority)
Authenticators: All registered Authenticators
Time Limit: 180 seconds
Workflow:
1.
User initiates account modification
2.
Policy detects critical operation from event type
3.
Ballots sent to all Authenticators
4.
Majority must approve within 3 minutes
5.
Account change proceeds if majority approves

Time-Based Access Control#

Scenario: Require approval for data access outside business hours.
Template: Time-based access policy template with data access events
Policy Configuration:
Trigger Events: Data token request
Configuration: Business hours = 9am-5pm
Voting Configuration: Affirmative strategy
Authenticators: Manager's Authenticator devices
Time Limit: 120 seconds
Workflow:
1.
User requests data at 8pm
2.
Policy detects out-of-hours access via time configuration
3.
Ballots sent to manager's devices
4.
Manager approves or rejects
5.
Data access proceeds based on manager's decision

Automated Approval Based on Context#

Scenario: Automatically approve low-risk operations, require voting for high-risk.
Template: Risk-based policy template with data exchange events
Policy Configuration:
Trigger Events: Data token exchange
Configuration: Risk thresholds - size < 1MB and classification = "internal"
Action: Auto-approve low-risk (no voting triggered)
Else: Trigger voting with consensus strategy
Workflow:
1.
Application exchanges data for token
2.
Policy evaluates data size and classification from configuration
3.
If low-risk: operation proceeds automatically
4.
If high-risk: voting workflow triggered with configured voting attributes

Policy Management Operations#

List Policy Templates#

Browse available policy templates to understand which events, configuration parameters, and voting attributes are available for creating policies.

Register Policy#

Create a new policy from a template by selecting specific events and providing custom configuration values.

List Active Policies#

View all policies currently enforcing authorization rules and triggering voting workflows.

List Inactive Policies#

View registered policies that are not currently active but can be activated when needed.

Activate Policy#

Enable a registered policy to begin evaluating operations and triggering voting workflows.

Deactivate Policy#

Disable an active policy, preventing it from evaluating operations without deleting the policy configuration.

Delete Policy#

Permanently remove a registered policy from your profile.

List Registered Policies#

View all policies (both active and inactive) registered under your profile.

Retrieve Registered Policy#

Get detailed configuration for a specific policy, including selected events, configuration parameters, and associated voting configuration.

Policy State Management#

Policies exist in one of three states:

Template State#

Available policy templates that can be instantiated. Templates are read-only, provided by Privicore, and define:
Available events that can trigger policies
Configuration parameters that can be customized
Voting attributes used in authorization workflows

Inactive State#

Registered policies that are configured but not currently evaluating operations. Inactive policies:
Retain all configuration (selected events, parameters, voting configuration)
Do not trigger voting workflows
Can be activated at any time
Are useful for temporarily suspending policies without losing configuration

Active State#

Registered policies that are currently enforcing rules. Active policies:
Evaluate all operations matching selected events
Trigger voting workflows when conditions are met
Apply configured voting parameters
Can be deactivated to suspend enforcement

Policy Priority and Conflicts#

When multiple active policies match the same operation:
Priority Ordering: Policies may have priority levels determining evaluation order
First Match: First matching policy triggers (default behavior)
Multiple Triggers: Multiple policies can trigger for the same operation (advanced configuration)
Conflict Resolution: System-defined rules resolve conflicts between policies

Integration with Voting Configurations#

Policies reference voting configurations to determine authorization parameters:
Policy Matches Operation
         ↓
Policy References Voting Configuration
         ↓
Voting Configuration Provides:
    - Strategy (unanimous, consensus, etc.)
    - Time Limit
    - Quorum Size
    - Authenticator Selection
         ↓
Poll Created with Voting Attributes from Template
         ↓
Poll Parameters from Voting Configuration
This separation enables:
Reusable Configurations: One voting configuration used by multiple policies
Centralized Management: Update voting parameters in one place
Flexible Authorization: Different operations use different approval requirements
Template-Driven Attributes: Voting attributes defined by template ensure consistent authorization context

Security Considerations#

Policies enable fine-grained access control based on operation events and context
Active policies automatically enforce authorization without manual intervention
Deactivate policies to temporarily suspend rules without losing configuration
Test policies in inactive state before activation
Multiple policies can create complex authorization requirements - design carefully
Templates define which events and attributes are available - review template documentation
Configuration parameters control policy behavior - validate values carefully
Balance security (strict policies) with usability (flexible policies)
Monitor policy triggers and voting outcomes for security auditing

Policy Best Practices#

Start with Templates#

Use provided policy templates as starting points rather than creating policies from scratch. Templates incorporate security best practices, define appropriate events, and specify relevant voting attributes.

Understand Template Events#

Review the events available in each template to ensure they match your authorization requirements. Select only the events you need to trigger the policy.

Configure Carefully#

Provide meaningful values for configuration parameters. These control when and how policies trigger, so incorrect configuration can result in policies that are too restrictive or too permissive.

Test Before Activating#

Register policies in inactive state, verify configuration and event selection, then activate when ready.

Use Descriptive Names#

Name policies clearly to indicate their purpose and which events they govern (e.g., "login-mfa-policy", "top-secret-data-access-policy").

Monitor Policy Impact#

Track how often policies trigger and voting outcomes to ensure policies achieve intended security goals without excessive friction.

Layer Security#

Use multiple policies for defense in depth - different policies for different event types and security levels.

Document Policy Intent#

Maintain documentation explaining why policies exist, which events they monitor, and what threats they address.
Modified at 2025-12-31 11:38:54
Previous
Retrieve voting configuration
Next
List policy templates
Built with