# 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?](#what-is-iam) - [Key Concepts](#key-concepts) - [Authentication Methods](#authentication-methods) - [Authorization Models](#authorization-models) - [Security Principles](#security-principles) - [Common Patterns](#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 ```mermaid graph LR IAM[Identity & Access
Management] IAM --> Identity[Identity
Management] IAM --> Access[Access
Control] IAM --> Governance[Governance &
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. ```mermaid graph TD Principal[Principal
Who wants access?] Principal --> User[User
Human with email/password] Principal --> Service[Service
Application with API key] Principal --> Device[Device
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` ```mermaid graph LR Permission[Permission
users:read:all] Permission --> Resource[Resource
users] Permission --> Action[Action
read] Permission --> Scope[Scope
all] Scope --> Own[own
Only your resources] Scope --> Team[team
Your team's resources] Scope --> All[all
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. ```mermaid graph TD Policy[Policy
Business Hours Access] Policy --> Resource[Resource
sensitive_data] Policy --> Conditions[Conditions] Policy --> Effect[Effect
ALLOW/DENY] Conditions --> Time[Time Condition
9am - 5pm] Conditions --> Day[Day Condition
Monday - Friday] Conditions --> Location[Location Condition
Office IP ranges] Effect --> Allow[ALLOW
Grant access] Effect --> Deny[DENY
Block access] style Policy fill:#e1f5fe style Conditions fill:#fff3e0 style Effect fill:#e8f5e9 ``` **Policy Example** (JSON Logic): ```json { "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: ```mermaid graph TD Decision{Access Decision
Allow or Deny?} Principal[Principal
WHO wants access?
user@example.com] Resource[Resource
WHAT is being accessed?
sensitive_data] Action[Action
WHAT operation?
read] Principal --> Decision Resource --> Decision Action --> Decision Decision --> Context[Context
WHEN, WHERE, HOW?] Context --> Time[Time
During business hours?] Context --> Location[Location
From office IP?] Context --> Device[Device
Trusted device?] Context --> Risk[Risk Level
Low risk score?] Decision -->|All conditions met| Allow[ALLOW
Access Granted] Decision -->|Any condition fails| Deny[DENY
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 ```mermaid graph LR MFA[Multi-Factor
Authentication] MFA --> Something[Something
You Know] MFA --> SomethingHave[Something
You Have] MFA --> SomethingAre[Something
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. ```mermaid 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
All user operations] RolePerm2 --> Perm2[products:*:all
All product operations] RolePerm3 --> Perm3[orders:read:team
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. ```mermaid graph TD Request[Access Request] --> Evaluate[Evaluate Policy] Evaluate --> UserAttrs[User Attributes
department, level, location] Evaluate --> ResourceAttrs[Resource Attributes
classification, owner, sensitivity] Evaluate --> EnvironmentAttrs[Environment Attributes
time, IP, device, risk score] UserAttrs --> Decision{Policy Decision} ResourceAttrs --> Decision EnvironmentAttrs --> Decision Decision -->|All conditions met| Allow[ALLOW
Access Granted] Decision -->|Condition fails| Deny[DENY
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" ```mermaid 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
Normal Access] Decision -->|Medium Risk| MFA[Require MFA] Decision -->|High Risk| Deny[DENY
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. ```mermaid graph TB Attack[Attack Attempt] --> Layer1[Layer 1: Network
Firewall + TLS] Layer1 --> Layer2[Layer 2: Zero-Trust
Device + Location + Behavior] Layer2 --> Layer3[Layer 3: Rate Limiting
Prevent Brute Force] Layer3 --> Layer4[Layer 4: Authentication
Verify Identity] Layer4 --> Layer5[Layer 5: Authorization
Check Permissions] Layer5 --> Layer6[Layer 6: Input Validation
Prevent Injection] Layer6 --> Layer7[Layer 7: Audit Logging
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**: ```json { "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. ```mermaid 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
(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). ```mermaid graph TD IAM[IAM Service
Single Instance] IAM --> Org1[Organization 1
Company A] IAM --> Org2[Organization 2
Company B] IAM --> Org3[Organization 3
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](../ARCHITECTURE.en.md)** - System architecture and diagrams - **[DATA-MODEL.md](./DATA-MODEL.md)** - Database schema and relationships - **[SECURITY-MODEL.md](./SECURITY-MODEL.md)** - Security architecture and threat model - **[GETTING-STARTED.md](../guides/01-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