iam-identity-management

What this skill does

# OCI IAM and Identity Management - Expert Knowledge

## 🏗️ Use OCI Landing Zone Terraform Modules

**Don't reinvent the wheel.** Use [oracle-terraform-modules/landing-zone](https://github.com/oracle-terraform-modules/terraform-oci-landing-zones) for IAM structure.

**Landing Zone solves:**
- ❌ Bad Practice #1: Flat compartments (Landing Zone provides hierarchical structure)
- ❌ Bad Practice #2: Administrator for daily ops (Landing Zone enforces least privilege)
- ❌ Bad Practice #6: Manual IAM policies (Landing Zone provides CIS-compliant IaC)

**This skill provides**: IAM syntax, troubleshooting, and policy patterns for resources deployed WITHIN a Landing Zone.

---

## ⚠️ OCI CLI/API Knowledge Gap

**You don't know OCI CLI commands or OCI API structure.**

Your training data has limited and outdated knowledge of:
- OCI CLI syntax and parameters (updates monthly)
- OCI API endpoints and request/response formats
- IAM service CLI operations (`oci iam policy`, `oci iam dynamic-group`)
- Policy verb/resource combinations (OCI-specific, not AWS/Azure)
- Latest IAM features and Identity Domains

**When OCI operations are needed:**
1. Use exact CLI commands from this skill's references
2. Do NOT guess OCI IAM policy syntax
3. Do NOT assume AWS/Azure IAM patterns work in OCI
4. Load reference files for detailed IAM policy documentation

**What you DO know:**
- General IAM concepts (principals, policies, groups)
- Role-based access control principles
- Least privilege security concepts

This skill bridges the gap by providing current OCI-specific IAM patterns and syntax.

---

You are an OCI IAM expert. This skill provides knowledge Claude lacks: policy syntax gotchas, permission troubleshooting, dynamic group patterns, and OCI-specific IAM operational knowledge.

## NEVER Do This

❌ **NEVER use overly broad policies (security risk)**
```
# WRONG - grants admin access to everyone
Allow any-user to manage all-resources in tenancy

# WRONG - too broad for production
Allow group Developers to manage all-resources in compartment Production

# RIGHT - least privilege, specific resources
Allow group AppDevelopers to manage instance-family in compartment AppDev where target.instance.name =~ 'dev-*'
```

❌ **NEVER forget compartment hierarchy in policies**
```
# WRONG - policy in child compartment can't access parent resources
Policy location: Compartment A/B/C
"Allow group X to read buckets in compartment A"  # Fails! Policy must be in A or above

# RIGHT - policy must be at or above target location
Policy location: Compartment A (or root)
"Allow group X to read buckets in compartment A"
```

❌ **NEVER mix up principal types (causes "not authorized" errors)**
```
# WRONG - instance is NOT a user
Allow user <instance-ocid> to read buckets in compartment X

# RIGHT - use dynamic group for instances
Allow dynamic-group app-instances to read buckets in compartment X
```

❌ **NEVER hardcode resource OCIDs in dynamic group rules**
```
# WRONG - not scalable, breaks when instance replaced
ALL {instance.id = 'ocid1.instance.oc1.phx.xxxxx'}

# RIGHT - use compartment or tag matching
ALL {instance.compartment.id = '<compartment-ocid>'}
ANY {instance.freeform-tags.environment = 'production'}
```

❌ **NEVER create circular policy dependencies**
```
# WRONG - Group A needs policy to manage Group B, but Group B policy grants access to Group A
# Creates deadlock where neither can be created first

# RIGHT - use separate administrative groups with clear hierarchy
```

❌ **NEVER use "any-user" in production policies (security audit failure)**
```
# WRONG - grants access to ALL users including future unknown users
Allow any-user to read buckets in tenancy

# RIGHT - explicit group membership
Allow group DataReaders to read buckets in compartment SharedData
```
Cost impact: $10,000+ per compliance violation finding in SOC2/HIPAA audits

## IAM Permission Troubleshooting

### "404 - NotAuthorizedOrNotFound"

This error means **EITHER**:
1. Resource doesn't exist, OR
2. User lacks permission to see if resource exists

**Troubleshooting decision tree**:
```
404 NotAuthorizedOrNotFound?
│
├─ Does resource definitely exist?
│  ├─ YES → Permission issue
│  │  └─ Check: Does user have 'inspect' or 'read' permission?
│  │     └─ Check: Is policy in correct compartment (at or above target)?
│  └─ NO → Resource doesn't exist
│     └─ Verify OCID, compartment, region
│
├─ Using dynamic group/instance principal?
│  └─ Check: Is instance in dynamic group?
│     └─ `oci compute instance get --instance-id <ocid>` (shows compartment, tags)
│     └─ Verify matching-rule matches instance properties
│
└─ Cross-compartment access?
   └─ Policy must be in compartment that CONTAINS both source and target
      OR in root compartment
```

### "403 - NotAuthorized"

**Clear permission denied**. User/principal identified but lacks permission.

**Common causes**:
1. **Missing verb**: Policy has `read` but action needs `use` or `manage`
2. **Wrong resource-type**: Policy grants `instance-family` but trying to access `volume-family`
3. **Condition doesn't match**: Policy has `where target.instance.name = 'prod-*'` but instance is `dev-web-1`
4. **Policy not in effect yet**: Policies take 10-60 seconds to propagate

**Verb hierarchy** (each includes permissions below):
```
inspect < read < use < manage
```

## Policy Syntax Gotchas

### Resource Type Families (Often Confused)

| Family | Includes | Common Mistake |
|--------|----------|----------------|
| `instance-family` | instances, instance-consoles, instance-console-connections, vnics, vnic-attachments | Thinking it includes volumes (it doesn't) |
| `volume-family` | volumes, volume-backups, volume-attachments | Separate from instances |
| `object-family` | buckets, objects | Objects are separate resources |
| `database-family` | db-systems, databases, autonomous-databases | Very broad |
| `all-resources` | Everything | **Use sparingly** - security risk |

### Location Syntax

```
# Compartment (specific)
in compartment <compartment-name or ocid>

# Compartment + descendants
in compartment <compartment-name> where target.compartment.id = <ocid>

# Tenancy (root)
in tenancy

# Specific resource (rare, for delegation)
in resource <resource-ocid>
```

### Conditions (WHERE clause)

```hcl
# Tag-based conditions
where target.resource.tag.environment = 'production'
where target.resource.freeform-tags.CostCenter = 'Engineering'

# Resource name patterns
where target.instance.name =~ 'web-*'  # Regex match

# Request properties
where request.operation = 'LaunchInstance'
where request.region = 'us-phoenix-1'

# Multiple conditions
where all {target.resource.tag.env = 'prod', target.compartment.name = 'AppProd'}
where any {target.instance.shape = 'VM.Standard.E4.Flex', target.instance.shape = 'VM.Standard.A1.Flex'}
```

## Dynamic Group Patterns

### Matching Rules Best Practices

**By Compartment** (most common):
```
ALL {instance.compartment.id = '<compartment-ocid>'}
```

**By Tag** (flexible):
```
ANY {instance.freeform-tags.app = 'webserver'}
```

**By Multiple Criteria** (restrictive):
```
ALL {instance.compartment.id = '<comp-ocid>', instance.freeform-tags.environment = 'production'}
```

**Common Mistake**: Using `instance.id` (specific instance) instead of `instance.compartment.id` (all instances in compartment)

### Testing Dynamic Group Membership

```bash
# 1. Get instance details to see compartment/tags
oci compute instance get --instance-id <instance-ocid>

# 2. Check dynamic group matching rule
oci iam dynamic-group get --dynamic-group-id <group-ocid>

# 3. Verify rule matches instance properties
# Example: If rule is "instance.compartment.id = X"
# Check instance's compartment_id matches X

# 4. Test with actual API call from instance
# SSH to instance and run:
oci os ns get  # Should work if instance principal configured correctly
```

## Compartment Strategy Anti-Patterns

❌ **WRONG: Flat structure (no organization)**
```
Tenancy
├─ Applicatio