security-roles

# Security & Roles ## Purpose Security configuration determines who can see what, do what, and when. In enterprise systems, security is not an afterthought -- it is a compliance requirement. Auditors examine it. Regulators mandate it. A misconfigured role can expose financial data, violate privacy laws, or allow fraudulent transactions. Builders need this skill when: - Setting up user roles and permissions for a new ERP•AI deployment - Designing access control for sensitive data (financial records, PII, health data) - Implementing segregation of duties to prevent fraud - Configuring single sign-on (SSO) and multi-factor authentication (MFA) - Meeting compliance requirements (SOX, GDPR, HIPAA, SOC 2) - Designing API security for integration endpoints - Setting up audit logging and monitoring Security is the one area where "it works" is not sufficient. It must also be provably correct, auditable, and aligned with the organization's risk posture. ## Key Concepts ### Role-Based Access Control (RBAC) RBAC assigns permissions to **roles**, and roles to **users**. Users inherit permissions from their assigned roles. Core RBAC components: - **Permission**: A granular right to perform an action on a resource. Example: `Invoice.Create`, `Invoice.Read`, `Invoice.Update`, `Invoice.Delete`, `Invoice.Approve`. - **Role**: A named collection of permissions that corresponds to a job function. Example: "AP Clerk" has `Invoice.Create`, `Invoice.Read`, `Invoice.Update`. "AP Manager" adds `Invoice.Approve` and `Invoice.Delete`. - **User**: A person or service account assigned one or more roles. - **Role hierarchy**: Roles can inherit from parent roles. "AP Manager" inherits all permissions from "AP Clerk" and adds additional ones. Hierarchies reduce duplication but increase complexity -- keep the hierarchy shallow (3 levels max). RBAC design principles: - **Least privilege**: Grant the minimum permissions needed for the job function. Do not give "Admin" to everyone. - **Role per job function**: Model roles after actual job titles/functions in the organization. "Accounts Payable Clerk", "Sales Manager", "Warehouse Operator" -- not generic roles like "User" or "Power User." - **No permission by default**: Start with zero access and add permissions explicitly. - **Separate administrative roles**: System administration (user management, configuration) should be a distinct role from business operations. ### Permission Levels ERP•AI supports permissions at multiple levels of granularity: | Level | What It Controls | Example | |---|---|---| | **Entity-level (CRUD)** | Create, Read, Update, Delete on an entire entity type | AP Clerk can Create and Read Invoices | | **Field-level** | Read or Write access to specific fields within an entity | AP Clerk can read `invoice_total` but cannot edit it (system-calculated) | | **Record-level (Row-level)** | Access restricted to specific records based on ownership, department, or other attributes | Sales Rep can only see Opportunities they own or that belong to their territory | | **Action-level** | Permission to perform specific business actions beyond CRUD | AP Manager can execute the "Approve" action; AP Clerk cannot | ### Field-Level Security Field-level security (FLS) controls visibility and editability of individual fields. Use cases: - **Salary field on Employee**: Visible only to HR and the employee's manager. Hidden from peers and other departments. - **Cost price on Product**: Visible to Procurement and Finance. Hidden from Sales (who see only the sell price). - **SSN / Tax ID**: Visible only to HR and Payroll. Masked (last 4 digits) for others with partial access. Fully hidden for everyone else. FLS configuration in ERP•AI: - For each sensitive field, define which roles can **read** it, which can **write** it, and which see it **masked** (partial value displayed). - FLS applies everywhere the field appears: forms, reports, API responses, exports. - Fields hidden by FLS must also be excluded from search indexes to prevent leaking values through search. ### Row-Level Security (Record Ownership) Row-level security (RLS) restricts which records a user can access based on record attributes. Common RLS patterns: | Pattern | How It Works | Example | |---|---|---| | **Owner-based** | User sees only records they own (created or assigned to them) | Sales Rep sees only their Opportunities | | **Team-based** | User sees records owned by anyone in their team/group | Sales Team sees all team Opportunities | | **Hierarchy-based** | Manager sees their own records plus all records of their direct and indirect reports | VP of Sales sees all Opportunities under their org | | **Territory/Region** | User sees records matching their assigned territory | EMEA Sales sees European customers only | | **Tenant-based** | User sees only records for their tenant/company | Multi-tenant SaaS isolation (always enforced in ERP•AI) | RLS is enforced at the query level -- the database returns only permitted records. This is more secure than filtering in the application layer. ### Segregation of Duties (SoD) SoD prevents a single person from controlling all steps of a critical business process. It is a core internal control for fraud prevention and a key requirement of SOX compliance. SoD examples: | Process | Conflicting Roles | Why | |---|---|---| | Payments | "Create Vendor" + "Approve Payment" | A person could create a fake vendor and approve payments to themselves | | Purchasing | "Create Purchase Order" + "Receive Goods" + "Approve Invoice" | One person could order goods, confirm receipt, and approve payment without oversight | | Financial Reporting | "Post Journal Entry" + "Approve Journal Entry" | A person could post and approve fraudulent entries | | User Management | "Create User" + "Assign Roles" + "Approve Transactions" | A person could create a phantom user, give it approver rights, and use it to approve their own transactions | **SoD Conflict Matrix**: A table that cross-references all roles and flags which role combinations are prohibited. ERP•AI's Security module includes an SoD conflict detector that alerts administrators when a user is assigned conflicting roles. SoD resolution options: - **Prevent**: Block the conflicting role assignment entirely. - **Alert**: Allow the assignment but generate an alert for the security administrator. - **Mitigate**: Allow the assignment with a compensating control (e.g., enhanced monitoring, additional approval step for transactions by this user). ### Authentication Authentication verifies the user's identity. | Method | How It Works | When to Use | |---|---|---| | **Username + Password** | Traditional credentials stored (hashed + salted) in the system. | Standalone deployments without an identity provider. Least preferred. | | **SSO (SAML 2.0 / OIDC)** | Users authenticate via the organization's Identity Provider (Okta, Azure AD, Google Workspace). ERP•AI receives a signed assertion. | Any organization with an existing IdP. Default recommendation. | | **Multi-Factor Authentication (MFA)** | After password/SSO, user must present a second factor (TOTP, push notification, hardware key). | All production environments. Mandatory for users with administrative or financial roles. | | **Passwordless (WebAuthn / FIDO2)** | User authenticates with a biometric (fingerprint, face) or hardware security key. No password. | Modern deployments prioritizing security and UX. Eliminates password-related attacks. | | **Service Account / API Key** | Non-interactive authentication for integrations and automated processes. | System-to-system integrations. Always pair with IP allowlisting and key rotation. | ERP•AI supports SAML 2.0 and OIDC for SSO, TOTP and WebAuthn for MFA, and OAuth 2.0 for API authentication. Configure SSO as the primary method; fall back to username/password only for break-glass scenarios. ### Session Management Session management controls how long a user stays authenticated and what happens when they are idle. | Setting | Recommendation | Why | |---|---|---| | **Session timeout (idle)** | 15-30 minutes for standard users; 5-10 minutes for privileged users | Reduces risk of unattended session misuse | | **Session timeout (absolute)** | 8-12 hours (one business day) | Forces re-authentication at least daily | | **Concurrent sessions** | Limit to 2-3 | Detects credential sharing or theft | | **Session binding** | Bind to IP address and user agent | Prevents session hijacking | | **Logout behavior** | Destroy session token on logout; do not preserve in browser | Prevents session reuse after logout | ### API Security APIs exposed by ERP•AI for integrations must be secured separately from UI access. API security layers: 1. **Authentication**: OAuth 2.0 bearer tokens (preferred) or API keys. Never basic auth for production APIs. 2. **Authorization**: API tokens carry scopes that limit which endpoints and operations are permitted. Scope examples: `invoices:read`, `invoices:write`, `users:admin`. 3. **Rate limiting**: Protect against abuse and accidental overload. Set rate limits per API key/token. Typical: 100-1000 requests per minute depending on the endpoint. 4. **IP allowlisting**: Restrict API access to known IP addresses/ranges for server-to-server integrations. 5. **Input validation**: Validate all inputs against expected types, lengths, and patterns. Reject malformed requests before they reach business logic. 6. **TLS**: All API traffic must be HTTPS. Minimum TLS 1.2. Prefer TLS 1.3. 7. **CORS**: Configure allowed origins for browser-based API consumers. Do not use `*` in production. ### Audit Logging Audit logs record who did what, when, and from where. They are essential for security investigations, compliance, and operational troubleshooting. **What to log**: | Event Category | Examples | |---|---| | Authentication events | Login success/failure, logout, MFA challenge, SSO assertion, password reset | | Authorization events | Permission denied, role assignment change, SoD override | | Data access | Read of sensitive records (PII, financial), bulk export, report generation | | Data changes | Create, update, delete on all entities. Log old value and new value for updates. | | Configuration changes | Role definition changes, workflow changes, integration configuration changes | | Administrative actions | User creation/deactivation, system setting changes, data migration execution | **Log format**: Each log entry should contain: `timestamp` (UTC), `user_id`, `user_role`, `action`, `entity_type`, `record_id`, `field_name` (for updates), `old_value`, `new_value`, `source_ip`, `session_id`, `result` (success/failure), `correlation_id`. **Retention**: Keep audit logs for a minimum period based on regulatory requirements: | Regulation | Minimum Retention | |---|---| | SOX | 7 years | | GDPR | As long as needed for the purpose, then delete | | HIPAA | 6 years | | SOC 2 | 1 year (minimum) | | General best practice | 3-5 years | **Tamper-proofing**: Audit logs must be immutable. Users (including administrators) must not be able to modify or delete audit log entries. ERP•AI writes audit logs to an append-only store with cryptographic hash chaining. Optionally export to a SIEM (Splunk, Elastic, Sumo Logic) for independent storage. ### Data Encryption Encryption protects data confidentiality at rest and in transit. | Encryption Layer | What It Protects | Implementation | |---|---|---| | **In transit (TLS)** | Data moving between client and server, or between services | TLS 1.2+ on all connections. Certificate pinning for mobile apps. | | **At rest (volume/disk)** | Database files on disk, backups, file storage | AES-256 encryption managed by the infrastructure (AWS RDS encryption, Azure TDE). | | **Field-level encryption** | Individual sensitive fields (SSN, bank account, health records) | Application-level encryption before storage. Separate encryption keys per tenant. Enables "right to erasure" by destroying the key. | | **Backup encryption** | Database and file backups | Same encryption as at-rest, with key management for backup lifecycle. | **Key management**: Use a dedicated key management service (AWS KMS, Azure Key Vault, HashiCorp Vault). Never store encryption keys in application code, config files, or the same database as the encrypted data. ### Compliance-Driven Security Requirements Different regulations impose specific security requirements. **SOX (Sarbanes-Oxley)**: - User access reviews: Quarterly review of who has access to financial systems. Managers must certify that their team members' access is appropriate. - SoD enforcement: Conflicting roles must be detected and remediated. - Change management: All configuration changes to financial modules must be logged and approved. - IT general controls: Password policies, access provisioning/deprovisioning, audit log integrity. **GDPR (General Data Protection Regulation)**: - Right to access: Users can request a copy of all their personal data. The system must be able to export a user's PII. - Right to erasure ("right to be forgotten"): Users can request deletion of their personal data. Field-level encryption enables this by destroying the encryption key. - Data minimization: Collect only the PII necessary for the business purpose. - Consent management: Track and enforce consent for data processing. - Data breach notification: Detect and report breaches within 72 hours. Audit logs enable detection. **HIPAA (Health Insurance Portability and Accountability Act)**: - PHI (Protected Health Information) must be encrypted at rest and in transit. - Access to PHI must be logged and auditable. - Minimum necessary access: Users see only the PHI needed for their job function (field-level + row-level security). - Business associate agreements (BAAs) with vendors who handle PHI. **SOC 2**: - Security, availability, processing integrity, confidentiality, and privacy controls. - Requires documented policies, access control procedures, change management, and incident response. - Annual audit by an independent assessor. ## Workflow ### 1. Identify Security Requirements - Interview stakeholders to understand the organization's regulatory landscape (SOX, GDPR, HIPAA, SOC 2, industry-specific). - Document data classification: what data is public, internal, confidential, restricted? - Identify sensitive entities and fields (PII, financial data, health data, trade secrets). - Review the organization's existing security policies and standards. - **Tool**: Security requirements questionnaire, data classification matrix. - **Watch out for**: Assuming one-size-fits-all security. Different modules (Finance vs Marketing) have different security needs. - **Output**: Security requirements document with data classification and regulatory mapping. ### 2. Design the Role Model - List all job functions that will use ERP•AI. - For each job function, define the entity-level permissions (CRUD per entity). - Identify fields requiring field-level security and assign read/write/masked access per role. - Identify record-level security requirements (owner-based, team-based, hierarchy-based). - Build the role hierarchy (keep it to 3 levels max). - **Tool**: ERP•AI's Role Designer. Start with a RACI-style matrix (Responsible, Accountable, Consulted, Informed) per entity per role. - **Watch out for**: Roles that are too broad ("Super User" with all permissions) or too narrow (one role per person). Aim for 8-15 roles for a typical enterprise deployment. - **Output**: Role definitions with permission sets, documented in ERP•AI. ### 3. Define Segregation of Duties Rules - Identify critical business processes (payments, purchasing, financial reporting, user management). - For each process, list the steps and the roles that perform them. - Build the SoD conflict matrix: which role pairs must not be assigned to the same user. - Configure SoD rules in ERP•AI (prevent, alert, or mitigate for each conflict). - **Tool**: ERP•AI's SoD Conflict Detector. - **Watch out for**: SoD rules that are so strict they block legitimate work. Small organizations may need controlled exceptions with compensating controls. - **Output**: SoD conflict matrix with resolution strategy per conflict. ### 4. Configure Authentication and Session Management - Configure SSO with the organization's Identity Provider (SAML 2.0 or OIDC). - Enable MFA for all users (TOTP or WebAuthn). Require hardware keys for admin roles. - Set session timeout policies (idle and absolute). - Configure concurrent session limits. - Set up break-glass accounts (local admin accounts for IdP outage scenarios). Store credentials in a secure vault with dual-custody access. - **Tool**: ERP•AI's Authentication Settings, IdP admin console (Okta, Azure AD). - **Watch out for**: Locking out all users if SSO misconfiguration occurs. Always maintain a break-glass local admin account. - **Output**: Authentication configuration with SSO, MFA, and session policies. ### 5. Configure Audit Logging - Enable audit logging for all event categories (authentication, authorization, data access, data changes, configuration, administration). - Configure log retention periods based on regulatory requirements. - Set up log export to SIEM for tamper-proof storage and alerting. - Configure alerts for critical events: multiple failed logins, SoD override, bulk data export, admin role changes. - **Tool**: ERP•AI's Audit Log Configuration, SIEM integration (Splunk, Elastic). - **Watch out for**: Logging too verbosely (logging every field-read on high-traffic entities) can create performance issues and storage costs. Focus on sensitive data and critical actions. - **Output**: Audit logging configuration with retention and alerting rules. ### 6. Implement Encryption - Verify that TLS 1.2+ is enforced on all connections (ERP•AI does this by default). - Verify that at-rest encryption is enabled on the database (infrastructure-level). - Identify fields requiring field-level encryption and configure them in ERP•AI. - Set up key management in the organization's KMS. - Test that encrypted fields are readable only by authorized roles and unreadable (not just hidden) to others. - **Tool**: ERP•AI's Encryption Configuration, KMS console. - **Watch out for**: Performance impact of field-level encryption. Encrypted fields cannot be searched or indexed by the database. Design accordingly (use surrogate identifiers for lookups). - **Output**: Encryption configuration with key management procedures. ### 7. Test and Validate - Test each role by logging in as a test user with that role and verifying: can access permitted entities/fields/records, cannot access restricted ones. - Test SoD rules: attempt to assign conflicting roles and verify the system blocks or alerts. - Test authentication flows: SSO, MFA, session timeout, concurrent session blocking. - Test audit logging: perform actions and verify they appear in the audit log with correct details. - Run a penetration test or security review if the deployment handles highly sensitive data. - **Tool**: ERP•AI's Security Test Suite, manual testing with role-specific test accounts. - **Watch out for**: Testing only positive cases (verifying access works). Negative testing (verifying access is denied) is more important for security. - **Output**: Security test results with pass/fail for each role and scenario. ### 8. Operationalize - Document the access provisioning process: how new users get roles assigned (request -> approval -> assignment). - Document the access deprovisioning process: how departing employees lose access (HR termination triggers automatic deactivation). - Schedule quarterly user access reviews (SOX requirement). - Establish an incident response process for security events. - **Tool**: ERP•AI's User Lifecycle Management, integration with HR system for automated provisioning/deprovisioning. - **Watch out for**: "Orphaned" accounts -- users who have left the organization but still have active system access. Automate deprovisioning via HR integration. - **Output**: Security operations procedures, access review schedule, incident response plan. ## Decision Guide ### When to Use Field-Level Security vs Separate Entities | Factor | Field-Level Security | Separate Entity | |---|---|---| | Sensitive fields are a small subset of the entity | Yes -- hide those fields by role | Overkill | | Entire categories of data have different audiences | Adds too many FLS rules | Yes -- split into separate entities with different permissions |