# 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<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.

```mermaid
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`

```mermaid
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.

```mermaid
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):
```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<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

```mermaid
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.

```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<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.

```mermaid
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"

```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<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.

```mermaid
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**:
```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<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).

```mermaid
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](../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
