> ## Documentation Index
> Fetch the complete documentation index at: https://developers.smarterservices.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conditions

> Advanced conditional access controls for IAM policies

# Conditions

Conditions provide fine-grained control over when IAM policies apply. They allow you to specify additional constraints that must be met for a policy statement to take effect, such as time-based access, IP restrictions, or resource-specific attributes.

## Condition Structure

Conditions are specified in the `Condition` element of a policy statement:

```json theme={null}
{
  "Effect": "Allow",
  "Action": ["sp:ReadSession"],
  "Resource": ["ssrn:ss:sp::578:session/*"],
  "Condition": {
    "Equals": {
      "session:proctorAccountSid": "PA123456"
    }
  }
}
```

## Condition Operators

### String Conditions

#### Equals

Exact string match (case-sensitive).

```json theme={null}
{
  "Condition": {
    "Equals": {
      "session:proctorAccountSid": "PA123456"
    }
  }
}
```

#### NotEquals

String does not match (case-sensitive).

```json theme={null}
{
  "Condition": {
    "NotEquals": {
      "user:role": "guest"
    }
  }
}
```

#### StringLike

Pattern matching with wildcards (`*` and `?`).

```json theme={null}
{
  "Condition": {
    "StringLike": {
      "user:email": "*@university.edu"
    }
  }
}
```

#### StringNotLike

Pattern does not match.

```json theme={null}
{
  "Condition": {
    "StringNotLike": {
      "user:department": "temp-*"
    }
  }
}
```

### Numeric Conditions

#### NumericEquals

Exact numeric match.

```json theme={null}
{
  "Condition": {
    "NumericEquals": {
      "session:duration": "120"
    }
  }
}
```

#### NumericLessThan

Numeric value is less than specified.

```json theme={null}
{
  "Condition": {
    "NumericLessThan": {
      "user:loginAttempts": "5"
    }
  }
}
```

#### NumericGreaterThan

Numeric value is greater than specified.

```json theme={null}
{
  "Condition": {
    "NumericGreaterThan": {
      "assessment:score": "80"
    }
  }
}
```

### Date/Time Conditions

#### DateEquals

Exact date/time match.

```json theme={null}
{
  "Condition": {
    "DateEquals": {
      "context:currentTime": "2023-12-25T00:00:00Z"
    }
  }
}
```

#### DateGreaterThan

Current time is after specified date.

```json theme={null}
{
  "Condition": {
    "DateGreaterThan": {
      "context:currentTime": "2023-01-01T00:00:00Z"
    }
  }
}
```

#### DateLessThan

Current time is before specified date.

```json theme={null}
{
  "Condition": {
    "DateLessThan": {
      "context:currentTime": "2023-12-31T23:59:59Z"
    }
  }
}
```

### Boolean Conditions

#### Bool

Boolean value match.

```json theme={null}
{
  "Condition": {
    "Bool": {
      "context:multiFactorAuthPresent": "true"
    }
  }
}
```

### IP Address Conditions

IP address conditions use the `network:` namespace and evaluate the request's source IP address in-memory (no database query). They can be combined with other condition types using AND logic.

**Supported value formats:**

* **Exact IP**: `"192.168.1.50"` — matches a single address (treated as `/32`).
* **CIDR range**: `"10.0.0.0/8"` — matches any address in the subnet.
* **Array**: `["192.168.1.0/24", "10.0.0.0/16"]` — matches if the source IP falls within any entry (OR logic).

<Note>
  Only IPv4 addresses are supported. IPv6-mapped IPv4 addresses (e.g., `::ffff:192.168.1.50`) are automatically normalized to their IPv4 equivalent.
</Note>

#### IpAddress

Allow-list — the request must originate from one of the specified IPs or ranges. If the source IP does not match any entry, the request is denied.

```json theme={null}
{
  "Condition": {
    "IpAddress": {
      "network:sourceIp": ["192.168.1.0/24", "10.0.0.0/16"]
    }
  }
}
```

#### NotIpAddress

Deny-list — the request must **not** originate from any of the specified IPs or ranges. If the source IP matches any entry, the request is denied.

```json theme={null}
{
  "Condition": {
    "NotIpAddress": {
      "network:sourceIp": "192.168.1.100/32"
    }
  }
}
```

## Condition Keys

### Network Namespace (network:)

Keys for network-level request attributes. The `network:` namespace is used with IP address condition operators.

#### network:sourceIp

IP address of the request source. Supports exact IPs, CIDR ranges, and arrays. Used with `IpAddress` and `NotIpAddress` operators only.

```json theme={null}
{
  "Condition": {
    "IpAddress": {
      "network:sourceIp": "192.168.1.0/24"
    }
  }
}
```

### Context Namespace (context:)

Keys for request-level context attributes.

#### context:currentTime

Current date and time of the request.

```json theme={null}
{
  "Condition": {
    "DateGreaterThan": {
      "context:currentTime": "2023-01-01T09:00:00Z"
    }
  }
}
```

#### context:userAgent

User agent string of the request.

```json theme={null}
{
  "Condition": {
    "StringLike": {
      "context:userAgent": "SmarterServices-*"
    }
  }
}
```

#### context:multiFactorAuthPresent

Whether multi-factor authentication was used.

```json theme={null}
{
  "Condition": {
    "Bool": {
      "context:multiFactorAuthPresent": "true"
    }
  }
}
```

### Service-Specific Condition Keys

#### Session Namespace (session:)

##### session:proctorAccountSid

Proctor account assigned to the session.

```json theme={null}
{
  "Condition": {
    "Equals": {
      "session:proctorAccountSid": "PA123456"
    }
  }
}
```

##### session:schedulingModule

Scheduling system used for the session.

```json theme={null}
{
  "Condition": {
    "Equals": {
      "session:schedulingModule": "register-blast"
    }
  }
}
```

##### session:status

Current status of the session.

```json theme={null}
{
  "Condition": {
    "Equals": {
      "session:status": "active"
    }
  }
}
```

##### session:examType

Type of exam being proctored.

```json theme={null}
{
  "Condition": {
    "StringLike": {
      "session:examType": "final-*"
    }
  }
}
```

#### User Namespace (user:)

##### user:role

User's role in the system.

```json theme={null}
{
  "Condition": {
    "Equals": {
      "user:role": "instructor"
    }
  }
}
```

##### user:department

User's department affiliation.

```json theme={null}
{
  "Condition": {
    "StringLike": {
      "user:department": "engineering-*"
    }
  }
}
```

##### user:accountType

Type of user account.

```json theme={null}
{
  "Condition": {
    "NotEquals": {
      "user:accountType": "trial"
    }
  }
}
```

#### Assessment Namespace (assessment:)

##### assessment:type

Type of assessment.

```json theme={null}
{
  "Condition": {
    "Equals": {
      "assessment:type": "placement"
    }
  }
}
```

##### assessment:status

Current status of the assessment.

```json theme={null}
{
  "Condition": {
    "NotEquals": {
      "assessment:status": "draft"
    }
  }
}
```

## Multiple Conditions

### AND Logic (Multiple Operators)

All conditions must be true.

```json theme={null}
{
  "Condition": {
    "Equals": {
      "session:proctorAccountSid": "PA123456"
    },
    "DateGreaterThan": {
      "context:currentTime": "2023-01-01T00:00:00Z"
    },
    "IpAddress": {
      "network:sourceIp": "192.168.1.0/24"
    }
  }
}
```

### OR Logic (Multiple Values)

Any value can match.

```json theme={null}
{
  "Condition": {
    "Equals": {
      "user:role": ["instructor", "admin", "proctor"]
    }
  }
}
```

### Complex Logic

Combining AND and OR logic.

```json theme={null}
{
  "Condition": {
    "Equals": {
      "user:role": ["instructor", "admin"]
    },
    "StringLike": {
      "user:department": ["math-*", "science-*"]
    },
    "DateGreaterThan": {
      "context:currentTime": "2023-01-01T00:00:00Z"
    }
  }
}
```

## Common Use Cases

### Time-Based Access

#### Business Hours Only

```json theme={null}
{
  "Version": "2023-01-01",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["sm:*"],
      "Resource": ["ssrn:ss:sm::578:*"],
      "Condition": {
        "DateGreaterThan": {
          "context:currentTime": "09:00:00Z"
        },
        "DateLessThan": {
          "context:currentTime": "17:00:00Z"
        }
      }
    }
  ]
}
```

#### Exam Period Access

```json theme={null}
{
  "Condition": {
    "DateGreaterThan": {
      "context:currentTime": "2023-05-01T00:00:00Z"
    },
    "DateLessThan": {
      "context:currentTime": "2023-05-15T23:59:59Z"
    }
  }
}
```

### Location-Based Access

#### Campus Network Only

Only allow access from campus IP ranges.

```json theme={null}
{
  "Condition": {
    "IpAddress": {
      "network:sourceIp": [
        "192.168.0.0/16",
        "10.0.0.0/8",
        "172.16.0.0/12"
      ]
    }
  }
}
```

#### Block Specific IPs

Deny access from specific IP addresses or ranges.

```json theme={null}
{
  "Effect": "Deny",
  "Action": ["*"],
  "Resource": ["*"],
  "Condition": {
    "IpAddress": {
      "network:sourceIp": ["192.168.100.0/24"]
    }
  }
}
```

#### Subnet Carve-Out

Allow a broad range but deny a specific subnet within it. Both conditions must be true (AND logic).

```json theme={null}
{
  "Condition": {
    "IpAddress": {
      "network:sourceIp": "10.0.0.0/8"
    },
    "NotIpAddress": {
      "network:sourceIp": "10.99.0.0/16"
    }
  }
}
```

#### Deny All Except Trusted Networks

Use a Deny statement with `NotIpAddress` to block everything outside the allowed ranges.

```json theme={null}
{
  "Effect": "Deny",
  "Action": ["*"],
  "Resource": ["*"],
  "Condition": {
    "NotIpAddress": {
      "network:sourceIp": ["192.168.0.0/16", "10.0.0.0/8"]
    }
  }
}
```

### Role-Based Conditions

#### Department-Specific Access

```json theme={null}
{
  "Condition": {
    "Equals": {
      "user:department": "mathematics"
    },
    "StringLike": {
      "assessment:subject": "math-*"
    }
  }
}
```

#### Instructor-Only Features

```json theme={null}
{
  "Condition": {
    "Equals": {
      "user:role": "instructor"
    },
    "Bool": {
      "user:verified": "true"
    }
  }
}
```

### Session-Specific Conditions

#### Assigned Proctor Only

```json theme={null}
{
  "Condition": {
    "Equals": {
      "session:assignedProctor": "${user.proctorId}"
    }
  }
}
```

#### Specific Scheduling Systems

```json theme={null}
{
  "Condition": {
    "Equals": {
      "session:schedulingModule": ["register-blast", "canvas-integration"]
    }
  }
}
```

### Security Conditions

#### MFA Required for Sensitive Actions

```json theme={null}
{
  "Effect": "Allow",
  "Action": ["sm:DeleteUser", "sp:DeleteSession"],
  "Resource": ["*"],
  "Condition": {
    "Bool": {
      "context:multiFactorAuthPresent": "true"
    }
  }
}
```

#### Trusted User Agents Only

```json theme={null}
{
  "Condition": {
    "StringLike": {
      "context:userAgent": [
        "SmarterServices-Web/*",
        "SmarterServices-Mobile/*"
      ]
    }
  }
}
```

## Advanced Patterns

### Conditional Deny

Deny access unless conditions are met.

```json theme={null}
{
  "Effect": "Deny",
  "Action": ["sp:ViewRecording"],
  "Resource": ["*"],
  "Condition": {
    "NotEquals": {
      "session:assignedProctor": "${user.proctorId}"
    }
  }
}
```

### Time-Window Access

Allow access only during specific time windows.

```json theme={null}
{
  "Condition": {
    "DateGreaterThan": {
      "context:currentTime": "${exam.startTime}"
    },
    "DateLessThan": {
      "context:currentTime": "${exam.endTime}"
    }
  }
}
```

### Dynamic Resource Access

Access based on resource attributes.

```json theme={null}
{
  "Condition": {
    "Equals": {
      "assessment:createdBy": "${user.id}"
    }
  }
}
```

## Best Practices

### 1. Use Specific Conditions

```json theme={null}
// ✅ Specific condition
{
  "Condition": {
    "Equals": {
      "user:department": "engineering"
    }
  }
}

// ❌ Too broad
{
  "Condition": {
    "StringLike": {
      "user:department": "*"
    }
  }
}
```

### 2. Combine Multiple Conditions

```json theme={null}
{
  "Condition": {
    "Equals": {
      "user:role": "proctor"
    },
    "Bool": {
      "user:verified": "true"
    },
    "IpAddress": {
      "network:sourceIp": "192.168.1.0/24"
    }
  }
}
```

### 3. Use Deny for Security

```json theme={null}
{
  "Effect": "Deny",
  "Action": ["*"],
  "Resource": ["*"],
  "Condition": {
    "NotIpAddress": {
      "network:sourceIp": ["192.168.0.0/16"]
    }
  }
}
```

### 4. Test Conditions Thoroughly

Always test conditions in a development environment before deploying to production.

## Troubleshooting

### Common Issues

1. **Case Sensitivity**: String conditions are case-sensitive
2. **Date Formats**: Use ISO 8601 format for dates
3. **IP Ranges**: Use CIDR notation for IP addresses (e.g., `192.168.1.0/24`)
4. **Multiple Values**: Use arrays for OR logic
5. **Variable Substitution**: Ensure variables are properly formatted
6. **IP Operator Namespace**: `IpAddress` and `NotIpAddress` operators only work with the `network:` namespace — they cannot be used with `session:` or other namespaces
7. **Missing Source IP**: If the source IP cannot be determined from the request, the condition will fail closed (access denied)

### IP Address Troubleshooting

1. **Invalid CIDR notation**: Ensure IP ranges use valid CIDR format (e.g., `10.0.0.0/8`, not `10.0.0.0/33`). Invalid CIDR values will cause the condition to fail closed.
2. **IPv4 only**: Only IPv4 addresses are supported. IPv6-mapped IPv4 addresses (`::ffff:x.x.x.x`) are automatically normalized, but pure IPv6 addresses are not supported.
3. **Proxy headers**: When behind a load balancer or proxy, the source IP is extracted from the `X-Forwarded-For` header (leftmost entry). Ensure your proxy is correctly setting this header.
4. **Unexpected denials**: If requests are unexpectedly denied, verify the client's actual IP address matches the CIDR range in the policy. Remember that a single IP like `192.168.1.50` is treated as `192.168.1.50/32`.

### Debugging Tips

1. **Log Condition Evaluations**: Enable detailed logging
2. **Test Individual Conditions**: Test each condition separately
3. **Validate Syntax**: Use JSON validators for policy syntax
4. **Check Variable Values**: Verify variable substitution works correctly