pos-system/services/iam-service/docs/concepts/CORE-CONCEPTS.md

IAM Core Concepts

Foundational Concepts for Identity & Access Management

This document explains the fundamental concepts, principles, and terminology used in the IAM Service.

Table of Contents

• What is IAM?
• Key Concepts
• Authentication Methods
• Authorization Models
• Security Principles
• Common Patterns

---

What is IAM?

IAM (Identity and Access Management) is a framework of policies, processes, and technologies that ensures the right individuals access the right resources at the right times for the right reasons.

The Three Pillars of IAM

graph LR
    IAM[Identity & Access<br/>Management]

    IAM --> Identity[Identity<br/>Management]
    IAM --> Access[Access<br/>Control]
    IAM --> Governance[Governance &<br/>Compliance]

    Identity --> Users[Users & Profiles]
    Identity --> Orgs[Organizations]
    Identity --> Groups[Groups]

    Access --> Auth[Authentication]
    Access --> Authz[Authorization]
    Access --> Sessions[Session Management]

    Governance --> Audit[Audit Logs]
    Governance --> Compliance[Compliance Reports]
    Governance --> Risk[Risk Management]

    style IAM fill:#e1f5fe
    style Identity fill:#f3e5f5
    style Access fill:#fff3e0
    style Governance fill:#e8f5e9

Why IAM Matters

1. Security: Prevent unauthorized access to sensitive resources
2. Compliance: Meet regulatory requirements (GDPR, SOC2, HIPAA, ISO27001)
3. Productivity: Users can access what they need, when they need it
4. Visibility: Track who did what, when, and why
5. Efficiency: Automate user provisioning and de-provisioning
6. Risk Management: Identify and mitigate access-related risks

IAM vs Authentication vs Authorization

Aspect	Authentication	Authorization	IAM
Question	Who are you?	What can you do?	Complete identity lifecycle
Scope	Identity verification	Permission checking	Identity + Access + Governance
Example	Login with password	Check if user can delete file	User creation → access → reviews → compliance
Output	User identity	Allow/Deny decision	Complete access management
Technologies	JWT, OAuth, SAML	RBAC, ABAC, ACL	Authentication + Authorization + Audit + Compliance

Simple Analogy:

• Authentication = Showing your ID at the door (proving who you are)
• Authorization = Checking if you're on the guest list (proving what you can access)
• IAM = Managing the entire event (invitations, guest lists, access levels, tracking, compliance)

---

Key Concepts

Principals

A principal is an entity that can request access to resources.

graph TD
    Principal[Principal<br/>Who wants access?]

    Principal --> User[User<br/>Human with email/password]
    Principal --> Service[Service<br/>Application with API key]
    Principal --> Device[Device<br/>Mobile/Desktop with cert]

    User --> UserTypes[User Types]
    UserTypes --> Employee[Employee]
    UserTypes --> Customer[Customer]
    UserTypes --> Partner[Partner]
    UserTypes --> Admin[Administrator]

    style Principal fill:#e1f5fe
    style User fill:#fff3e0
    style Service fill:#e8f5e9
    style Device fill:#f3e5f5

Examples:

• Human users: user@example.com
• Service accounts: payment-service
• API clients: mobile-app-v1
• IoT devices: sensor-123

Resources

A resource is an entity that can be accessed or acted upon.

Common Resources:

• Data: Users, products, orders, invoices, reports
• Functions: APIs, endpoints, services, microservices
• Infrastructure: Databases, queues, storage buckets
• Business Objects: Projects, organizations, teams

Resource Naming Convention: resource-type

• Examples: users, products, orders, payments, reports

Actions

An action is an operation that can be performed on a resource.

Standard Actions (CRUD):

• create - Create new resources
• read - View/list resources
• update - Modify existing resources
• delete - Remove resources

Extended Actions:

• list - List multiple resources
• export - Export data
• import - Import data
• approve - Approve workflows
• publish - Publish content
• archive - Archive resources

Action Naming Convention: verb

• Examples: read, create, update, delete, approve

Permissions

A permission is the right to perform an action on a resource within a specific scope.

Permission Format: resource:action:scope

graph LR
    Permission[Permission<br/>users:read:all]

    Permission --> Resource[Resource<br/>users]
    Permission --> Action[Action<br/>read]
    Permission --> Scope[Scope<br/>all]

    Scope --> Own[own<br/>Only your resources]
    Scope --> Team[team<br/>Your team's resources]
    Scope --> All[all<br/>All resources]

    style Permission fill:#e1f5fe
    style Resource fill:#f3e5f5
    style Action fill:#fff3e0
    style Scope fill:#e8f5e9

Permission Examples:

Permission	Meaning
users:read:all	Read all users
users:update:own	Update own user profile
products:create:team	Create products for team
orders:delete:all	Delete any order (admin)
reports:export:team	Export team reports
payments:approve:all	Approve all payments

Policies

A policy is a set of rules that determine access based on attributes and conditions.

graph TD
    Policy[Policy<br/>Business Hours Access]

    Policy --> Resource[Resource<br/>sensitive_data]
    Policy --> Conditions[Conditions]
    Policy --> Effect[Effect<br/>ALLOW/DENY]

    Conditions --> Time[Time Condition<br/>9am - 5pm]
    Conditions --> Day[Day Condition<br/>Monday - Friday]
    Conditions --> Location[Location Condition<br/>Office IP ranges]

    Effect --> Allow[ALLOW<br/>Grant access]
    Effect --> Deny[DENY<br/>Block access]

    style Policy fill:#e1f5fe
    style Conditions fill:#fff3e0
    style Effect fill:#e8f5e9

Policy Example (JSON Logic):

{
  "name": "Business Hours Only",
  "resource": "sensitive_data",
  "condition": {
    "and": [
      {">=": [{"var": "hour"}, 9]},
      {"<=": [{"var": "hour"}, 17]},
      {"in": [{"var": "day"}, [1, 2, 3, 4, 5]]},
      {"in": [{"var": "ip"}, ["192.168.1.0/24", "10.0.0.0/8"]]}
    ]
  },
  "effect": "ALLOW",
  "priority": 100
}

The Access Decision Triangle

Every access decision involves three key elements:

graph TD
    Decision{Access Decision<br/>Allow or Deny?}

    Principal[Principal<br/>WHO wants access?<br/>user@example.com]
    Resource[Resource<br/>WHAT is being accessed?<br/>sensitive_data]
    Action[Action<br/>WHAT operation?<br/>read]

    Principal --> Decision
    Resource --> Decision
    Action --> Decision

    Decision --> Context[Context<br/>WHEN, WHERE, HOW?]

    Context --> Time[Time<br/>During business hours?]
    Context --> Location[Location<br/>From office IP?]
    Context --> Device[Device<br/>Trusted device?]
    Context --> Risk[Risk Level<br/>Low risk score?]

    Decision -->|All conditions met| Allow[ALLOW<br/>Access Granted]
    Decision -->|Any condition fails| Deny[DENY<br/>Access Denied]

    style Decision fill:#fff3e0
    style Principal fill:#e1f5fe
    style Resource fill:#f3e5f5
    style Action fill:#e8f5e9
    style Allow fill:#c8e6c9
    style Deny fill:#ffcdd2

---

Authentication Methods

Authentication is the process of verifying the identity of a user, service, or device.

Authentication Factors

graph LR
    MFA[Multi-Factor<br/>Authentication]

    MFA --> Something[Something<br/>You Know]
    MFA --> SomethingHave[Something<br/>You Have]
    MFA --> SomethingAre[Something<br/>You Are]

    Something --> Password[Password]
    Something --> PIN[PIN]
    Something --> SecurityQ[Security Questions]

    SomethingHave --> Phone[Phone/SMS]
    SomethingHave --> Token[Hardware Token]
    SomethingHave --> App[Authenticator App]

    SomethingAre --> Fingerprint[Fingerprint]
    SomethingAre --> Face[Face Recognition]
    SomethingAre --> Voice[Voice Recognition]

    style MFA fill:#e1f5fe
    style Something fill:#fff3e0
    style SomethingHave fill:#e8f5e9
    style SomethingAre fill:#f3e5f5

1. Password-Based Authentication

How it works:

1. User provides email + password
2. System hashes password with bcrypt
3. Compare hash with stored hash
4. Generate JWT token if match

Security Features:

• Bcrypt hashing (cost factor 12)
• Password complexity requirements
• Rate limiting (5 attempts per 15 minutes)
• Account lockout after failed attempts

Use Cases:

• Traditional web applications
• Internal employee systems
• Admin portals

2. Social Authentication (OAuth 2.0)

How it works:

1. User clicks "Sign in with Google/Facebook/GitHub"
2. Redirect to OAuth provider
3. User authorizes app
4. Receive authorization code
5. Exchange code for access token
6. Create or link user account

Benefits:

• No password management
• Faster signup/login
• Higher conversion rates
• Trust in established providers

Supported Providers:

• Google OAuth 2.0
• Facebook OAuth
• GitHub OAuth
• Apple Sign-In (future)
• Microsoft OAuth (future)

3. OpenID Connect (OIDC)

How it works:

• Extension of OAuth 2.0 for authentication
• Provides ID tokens (JWT) with user claims
• Supports discovery and dynamic registration

Modes:

• OIDC Provider: IAM acts as identity provider for other apps
• OIDC Client: IAM consumes other identity providers

Use Cases:

• Single Sign-On (SSO)
• Enterprise authentication
• Federation across organizations

4. Multi-Factor Authentication (MFA)

TOTP (Time-based One-Time Password):

• Generate 6-digit code every 30 seconds
• Works with Google Authenticator, Authy, 1Password
• No internet connection required
• Backup codes for account recovery

WebAuthn/FIDO2 (future):

• Hardware security keys (YubiKey, Titan)
• Platform authenticators (Touch ID, Face ID, Windows Hello)
• Phishing-resistant
• No shared secrets

When to Require MFA:

• High-risk actions (money transfer, data export)
• Privileged accounts (admins, developers)
• Sensitive resource access
• First login from new device
• Risk-based triggers (unusual location, device)

5. API Keys & Service Authentication

For Service-to-Service Communication:

• Long-lived API keys
• Short-lived JWT tokens
• Mutual TLS (mTLS)
• Service mesh identity

Use Cases:

• Microservice communication
• CI/CD pipelines
• Scheduled jobs
• Third-party integrations

---

Authorization Models

Authorization is the process of determining what an authenticated user can do.

RBAC (Role-Based Access Control)

Concept: Users are assigned roles, roles have permissions.

graph LR
    User1[User: Alice] --> UserRole1[UserRole]
    User2[User: Bob] --> UserRole2[UserRole]

    UserRole1 --> Admin[Role: ADMIN]
    UserRole2 --> Manager[Role: MANAGER]

    Admin --> RolePerm1[RolePermission]
    Admin --> RolePerm2[RolePermission]
    Manager --> RolePerm3[RolePermission]

    RolePerm1 --> Perm1[users:*:all<br/>All user operations]
    RolePerm2 --> Perm2[products:*:all<br/>All product operations]
    RolePerm3 --> Perm3[orders:read:team<br/>Read team orders]

    style User1 fill:#e1f5fe
    style User2 fill:#e1f5fe
    style Admin fill:#ffccbc
    style Manager fill:#fff3e0
    style Perm1 fill:#c8e6c9
    style Perm2 fill:#c8e6c9
    style Perm3 fill:#c8e6c9

Advantages:

• Simple to understand and manage
• Easy to audit ("Who has the ADMIN role?")
• Scalable for large organizations
• Supports role hierarchies

Limitations:

• Coarse-grained (all ADMINs have same permissions)
• Hard to handle exceptions
• Role explosion for complex scenarios

Best Practices:

• Principle of least privilege
• Regular role reviews
• Temporary role assignments with expiration
• Separate roles for different responsibilities

ABAC (Attribute-Based Access Control)

Concept: Access decisions based on attributes of user, resource, action, and context.

graph TD
    Request[Access Request] --> Evaluate[Evaluate Policy]

    Evaluate --> UserAttrs[User Attributes<br/>department, level, location]
    Evaluate --> ResourceAttrs[Resource Attributes<br/>classification, owner, sensitivity]
    Evaluate --> EnvironmentAttrs[Environment Attributes<br/>time, IP, device, risk score]

    UserAttrs --> Decision{Policy Decision}
    ResourceAttrs --> Decision
    EnvironmentAttrs --> Decision

    Decision -->|All conditions met| Allow[ALLOW<br/>Access Granted]
    Decision -->|Condition fails| Deny[DENY<br/>Access Denied]

    style Evaluate fill:#e1f5fe
    style UserAttrs fill:#fff3e0
    style ResourceAttrs fill:#e8f5e9
    style EnvironmentAttrs fill:#f3e5f5
    style Allow fill:#c8e6c9
    style Deny fill:#ffcdd2

Advantages:

• Fine-grained control
• Dynamic decisions based on context
• Handles exceptions easily
• Supports complex business rules

Limitations:

• More complex to configure
• Harder to audit
• Performance considerations

Use Cases:

• Time-based access (business hours only)
• Location-based access (office IP only)
• Resource classification (access sensitive data only if cleared)
• Risk-based access (require MFA if risky)

Hybrid Model (RBAC + ABAC)

The IAM Service uses a hybrid approach combining the best of both:

Authorization Hierarchy:

1. Direct User Permissions (HIGHEST PRIORITY)
   ↓
2. Role Permissions (RBAC)
   ↓
3. Group Permissions
   ↓
4. ABAC Policies (context-based)
   ↓
5. Default Deny (LOWEST PRIORITY)

Example Flow:

1. Check if user has direct permission (e.g., explicit grant or deny)
2. If not, check user's roles for permission
3. If not, check user's groups for permission
4. If not, evaluate ABAC policies with context
5. If no match, default to DENY

Benefits:

• RBAC for common cases (fast, simple)
• ABAC for exceptions and context (flexible)
• Best of both worlds

---

Security Principles

1. Zero Trust Architecture

Principle: "Never trust, always verify"

graph LR
    Request[Every Request] --> Verify[Verify Identity]
    Verify --> ValidateDevice[Validate Device]
    ValidateDevice --> CheckLocation[Check Location]
    CheckLocation --> AnalyzeBehavior[Analyze Behavior]
    AnalyzeBehavior --> CalculateRisk[Calculate Risk]
    CalculateRisk --> Decision{Risk Level?}

    Decision -->|Low Risk| Allow[ALLOW<br/>Normal Access]
    Decision -->|Medium Risk| MFA[Require MFA]
    Decision -->|High Risk| Deny[DENY<br/>Block Access]

    MFA --> Allow

    style Request fill:#e1f5fe
    style Decision fill:#fff3e0
    style Allow fill:#c8e6c9
    style MFA fill:#ffe082
    style Deny fill:#ffcdd2

Implementation:

• Every request authenticated
• Device fingerprinting
• IP address validation
• Behavioral analysis
• Continuous risk assessment

2. Least Privilege

Principle: Users should have the minimum permissions necessary to do their job.

Practice:

• Start with no permissions
• Grant permissions as needed
• Review permissions regularly
• Remove unused permissions
• Use time-limited permissions for temporary access

3. Defense in Depth

Principle: Multiple layers of security controls.

graph TB
    Attack[Attack Attempt] --> Layer1[Layer 1: Network<br/>Firewall + TLS]

    Layer1 --> Layer2[Layer 2: Zero-Trust<br/>Device + Location + Behavior]

    Layer2 --> Layer3[Layer 3: Rate Limiting<br/>Prevent Brute Force]

    Layer3 --> Layer4[Layer 4: Authentication<br/>Verify Identity]

    Layer4 --> Layer5[Layer 5: Authorization<br/>Check Permissions]

    Layer5 --> Layer6[Layer 6: Input Validation<br/>Prevent Injection]

    Layer6 --> Layer7[Layer 7: Audit Logging<br/>Track All Actions]

    Layer7 --> Resource[Protected Resource]

    style Attack fill:#ffcdd2
    style Layer1 fill:#ffccbc
    style Layer2 fill:#ff9999
    style Layer3 fill:#ffb74d
    style Layer4 fill:#fff176
    style Layer5 fill:#aed581
    style Layer6 fill:#4dd0e1
    style Layer7 fill:#9575cd
    style Resource fill:#c8e6c9

Layers in IAM Service:

1. Network security (Traefik Gateway, TLS)
2. Zero-trust validation (device, location, behavior)
3. Rate limiting (prevent brute force)
4. Authentication (verify identity)
5. Authorization (check permissions)
6. Input validation (prevent injection attacks)
7. Audit logging (track all actions)

4. Separation of Duties

Principle: No single user should have complete control over critical processes.

Examples:

• Different users for approval and execution
• Code review before deployment
• Multi-person approval for financial transactions
• Separate roles for read and write operations

5. Audit Everything

Principle: Log all authentication and authorization events for security, compliance, and troubleshooting.

What to Log:

• User logins (success and failure)
• Permission checks (allow and deny)
• Permission changes (grant, revoke)
• Role assignments
• Policy changes
• Session creation and termination
• MFA events
• Risk calculations

Log Format:

{
  "eventType": "LOGIN_SUCCESS",
  "userId": "user-123",
  "email": "user@example.com",
  "ipAddress": "192.168.1.100",
  "deviceFingerprint": "abc123",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "correlationId": "req-456"
}

---

Common Patterns

1. Single Sign-On (SSO)

Concept: Log in once, access multiple applications.

sequenceDiagram
    participant User
    participant App1 as Application 1
    participant IAM as IAM Service
    participant App2 as Application 2

    User->>App1: Access App1
    App1->>IAM: Redirect to login
    User->>IAM: Login (email/password)
    IAM->>IAM: Create session
    IAM->>App1: Redirect with token
    App1->>User: Access granted

    Note over User,App2: Later, access App2

    User->>App2: Access App2
    App2->>IAM: Check session
    IAM->>IAM: Session exists
    IAM->>App2: Return user info
    App2->>User: Access granted<br/>(no login required)

Benefits:

• Better user experience (one login)
• Reduced password fatigue
• Centralized access control
• Easier offboarding

Protocols:

• OAuth 2.0 + OIDC (modern, JSON-based)
• SAML 2.0 (enterprise, XML-based)
• Kerberos (legacy, Windows)

2. Multi-Tenancy

Concept: Single instance serves multiple organizations (tenants).

graph TD
    IAM[IAM Service<br/>Single Instance]

    IAM --> Org1[Organization 1<br/>Company A]
    IAM --> Org2[Organization 2<br/>Company B]
    IAM --> Org3[Organization 3<br/>Company C]

    Org1 --> Users1[Users]
    Org1 --> Groups1[Groups]
    Org1 --> Policies1[Policies]

    Org2 --> Users2[Users]
    Org2 --> Groups2[Groups]
    Org2 --> Policies2[Policies]

    style IAM fill:#e1f5fe
    style Org1 fill:#fff3e0
    style Org2 fill:#e8f5e9
    style Org3 fill:#f3e5f5

Data Isolation:

• Organization ID on every record
• Row-level security in queries
• Separate databases (optional, for high security)

Benefits:

• Cost-effective (shared infrastructure)
• Easier maintenance (single codebase)
• Faster onboarding (no deployment needed)

3. Just-In-Time (JIT) Access

Concept: Grant temporary access only when needed.

Flow:

1. User requests access to resource
2. Manager/system approves
3. Access granted for limited time (e.g., 2 hours)
4. Access automatically revoked after expiry

Use Cases:

• Emergency database access
• Temporary admin privileges
• Contractor access
• Incident response

4. Privileged Access Management (PAM)

Concept: Special controls for high-privilege accounts.

Features:

• Check-out/check-in of privileged credentials
• Session recording
• Just-in-time privilege elevation
• Approval workflows
• Automated password rotation

Use Cases:

• Database admin accounts
• Cloud infrastructure accounts
• Root/Administrator accounts
• Service accounts with high privileges

5. Access Reviews & Certification

Concept: Periodic review of who has access to what.

Process:

1. Generate review campaign (quarterly, annually)
2. Assign reviewers (managers, resource owners)
3. Reviewers certify or revoke access
4. Automatically revoke uncertified access
5. Generate compliance report

Benefits:

• Prevent privilege creep
• Compliance (SOC2, ISO27001)
• Discover orphaned accounts
• Identify over-privileged users

---

Next Steps

Now that you understand the core concepts, explore:

• ARCHITECTURE.md - System architecture and diagrams
• DATA-MODEL.md - Database schema and relationships
• SECURITY-MODEL.md - Security architecture and threat model
• GETTING-STARTED.md - Hands-on tutorial

---

Glossary

Term	Definition
Principal	Entity requesting access (user, service, device)
Resource	Entity being accessed (data, API, file)
Action	Operation being performed (read, write, delete)
Permission	Right to perform action on resource in scope (resource:action:scope)
Role	Named collection of permissions
Policy	Rule-based access control using attributes and conditions
RBAC	Role-Based Access Control
ABAC	Attribute-Based Access Control
MFA	Multi-Factor Authentication
SSO	Single Sign-On
OIDC	OpenID Connect
JWT	JSON Web Token
TOTP	Time-based One-Time Password
Zero Trust	Security model: never trust, always verify
Least Privilege	Minimum permissions necessary
Defense in Depth	Multiple layers of security

---

Last Updated: January 2026 Version: 1.0.0 Status: Production Ready