Building Conditions in Lumos

Lumos Conditions represent a recursive query language that allows you to define complex rules for filtering and matching identities in the Lumos platform. Current Usage: Conditions are currently primarily used in Access Policies to determine which identities qualify for automatic access grants. Support for Conditions will expand to other areas of the Lumos platform in the future.

Overview

A Condition is a JSON object that evaluates to true or false based on attributes of the entities being evaluated. When used in Access Policies, conditions are evaluated against identity attributes to determine if an identity qualifies for the policy. Conditions support:

Comparison operators: equals, not equals, greater than, less than, etc.
String operators: contains, starts with, ends with
Collection operators: in, contains any
Logical composition: AND, OR, NOT
Existence checks: exists
Custom expressions: Lumos expressions

Conditions are recursive, meaning you can nest conditions within other conditions to build complex logical expressions.

Basic Structure

Every condition consists of:

An attribute - specifies which property of the entity to evaluate
An operator - defines how to compare or evaluate the attribute
A value (for most operators) - the value to compare against

Simple Condition Example

{
  "attribute": "identity.email",
  "equals": "engineer@example.com"
}

This condition evaluates to true if the identity’s email equals “engineer@example.com”.

Attributes

The attribute field specifies which property of the entity to evaluate. Attributes can be specified in two ways:

String Attribute

A simple string path to the attribute:

{
  "attribute": "identity.email",
  "equals": "engineer@example.com"
}

Common attribute paths include:

identity.email - The identity’s email address
identity.given_name - The identity’s first name
identity.family_name - The identity’s last name
identity.full_name - The identity’s full name
identity.team - The identity’s team
identity.title - The identity’s title
identity.manager.uuid - The identity’s manager’s UUID
identity.manager.email - The identity’s manager’s email=
identity.manager.full_name - The identity’s manager’s full name
identity.start_date - The identity’s start date
identity.end_date - The identity’s end date
identity.status - The identity’s status
identity.custom_attributes["Department"] - A custom attribute named “Department”
identity.groups[*].external_id - The identity’s groups

Attribute Operand

For more complex attribute selection, you can use an AttributeOperand object with a label and value:

{
  "attribute": {
    "label": "Team",
    "value": "identity.team"
  },
  "equals": "Engineering"
}

The label is a human-readable name for the attribute, while value is the actual path used for evaluation.

Attribute Types

Attributes in Lumos Conditions can be of different types, each with specific behaviors and use cases.

STRING

STRING attributes are simple text values. They work straightforwardly with string comparison operators like equals, in, contains, etc.

{
  "attribute": "identity.email",
  "equals": "engineer@example.com"
}

{
  "attribute": "identity.team",
  "equals": "Engineering"
}

{
  "attribute": "identity.custom_attributes['Department']",
  "in": ["Engineering", "Product", "Design"]
}

IDENTITY

IDENTITY attributes represent references to other identities. When accessing IDENTITY attributes, you can reference specific properties of the identity object using dot notation. Direct identity relationships:

{
  "attribute": "identity.manager.uuid",
  "equals": {
    "label": "Jane Smith",
    "value": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "attribute": "identity.manager.full_name",
  "equals": "Jane Smith"
}

{
  "attribute": "identity.manager.email",
  "equals": "jane.smith@example.com"
}

Custom attributes of type IDENTITY:

{
  "attribute": "identity.custom_attributes['Assistant'].uuid",
  "equals": {
    "label": "John Doe",
    "value": "550e8400-e29b-41d4-a716-446655440000"
  }
}

{
  "attribute": "identity.custom_attributes['Assistant'].full_name",
  "equals": "John Doe"
}

{
  "attribute": "identity.custom_attributes['Assistant'].email",
  "equals": "john.doe@example.com"
}

GROUP

GROUP attributes represent references to groups. Groups are collections, so you typically use array notation with the [*] wildcard to access properties of groups in the collection. Accessing group external IDs:

{
  "attribute": "identity.groups[*].external_id",
  "contains_any": [
    {
      "label": "Group 1",
      "value": "group-id-1"
    },
    {
      "label": "Group 2",
      "value": "group-id-2"
    }
  ]
}

Excluding specific groups:

{
  "attribute": "identity.groups[*].external_id",
  "not": {
    "contains_any": [
      {
        "label": "Group 1",
        "value": "group-id-1"
      },
      {
        "label": "Group 2",
        "value": "group-id-2"
      }
    ]
  }
}

DATETIME

DATETIME attributes represent date and time values. When comparing DATETIME attributes, you must use ISO 8601 format strings with timezone information. Direct identity date fields:

{
  "attribute": "identity.start_date",
  "equals": "2024-01-15T00:00:00Z"
}

{
  "attribute": "identity.start_date",
  "greater_than": "2023-01-01T00:00:00Z"
}

Custom attributes of type DATETIME:

{
  "attribute": "identity.custom_attributes['Hire Date']",
  "equals": "2024-01-15T00:00:00Z"
}

{
  "attribute": "identity.custom_attributes['Last Review Date']",
  "less_than": "2024-12-31T23:59:59Z"
}

Expected datetime format:

Use ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DDTHH:MM:SS+HH:MM
Always include timezone information (use Z for UTC or offset like +05:00 for other timezones)
Examples:
- "2024-01-15T00:00:00Z" - January 15, 2024 at midnight UTC
- "2024-01-15T09:00:00-08:00" - January 15, 2024 at 9 AM PST
- "2024-12-31T23:59:59Z" - December 31, 2024 at 11:59:59 PM UTC

DATETIME attributes work with comparison operators like equals, greater_than, less_than, greater_than_or_equal, and less_than_or_equal.

Value Options

For better readability, you can use ValueOption objects instead of raw values. A ValueOption has a label (human-readable) and a value (the actual value used in evaluation):

{
  "attribute": "identity.custom_attributes['Department']",
  "equals": {
    "label": "Engineering Department",
    "value": "Engineering"
  }
}

This is particularly useful when the actual value might be a UUID or other non-human-readable identifier, but you want to display a friendly name in the UI.

Supported Value Types

Condition values can be:

Strings: "Engineering"
Numbers: 42 or 3.14
Booleans: true or false
Dates/DateTimes: "2024-01-01T00:00:00Z" (ISO 8601 format with timezone)
ValueOptions: {"label": "Friendly Name", "value": "actual_value"}

When using dates, always use ISO 8601 format with timezone information.

Operators

Comparison Operators

`equals`

Checks if the attribute equals a specific value.

{
  "attribute": "identity.custom_attributes['Department']",
  "equals": "Engineering"
}

`!=` (Not Equal To)

Checks if the attribute does not equal a specific value.

{
  "attribute": "identity.custom_attributes['Department']",
  "!=": "Sales"
}

`>` (Greater Than)

Checks if the attribute is greater than a value. Works with numbers and dates.

{
  "attribute": "identity.start_date",
  ">": "2024-01-01T00:00:00Z"
}

`>=` (Greater Than or Equal To)

{
  "attribute": "identity.start_date",
  ">=": "2024-01-01T00:00:00Z"
}

`<` (Less Than)

{
  "attribute": "identity.start_date",
  "<": "2024-01-01T00:00:00Z"
}

`<=` (Less Than or Equal To)

{
  "attribute": "identity.start_date",
  "<=": "2024-01-01T00:00:00Z"
}

String Operators

`contains`

Checks if the attribute contains a substring.

{
  "attribute": "identity.email",
  "contains": "@engineering"
}

`starts_with`

Checks if the attribute starts with a specific string.

{
  "attribute": "identity.email",
  "starts_with": "engineer"
}

`ends_with`

Checks if the attribute ends with a specific string.

{
  "attribute": "identity.email",
  "ends_with": "@example.com"
}

Collection Operators

`in`

Checks if the attribute value is in a list of values. When the right-hand side is a list, it performs exact equality matching against each item in the list.

{
  "attribute": "identity.custom_attributes['Department']",
  "in": ["Engineering", "Product", "Design"]
}

This will match identities where the Department attribute exactly equals “Engineering”, “Product”, or “Design”. You can use a single string value for substring matching:

{
  "attribute": "identity.custom_attributes['Department']",
  "in": "Engineering Team"
}

This will match identities where the Department attribute is a substring of “Engineering Team”. For example, if the Department is “Engineering”, it would match because “Engineering” is a substring of “Engineering Team”. Important: The in operator uses Python’s in operator directly. When the right-hand side is a string, it performs substring matching (not equality). When the right-hand side is a number or boolean, it will raise a TypeError and the condition will evaluate as false. For exact matching, always use an array. For example, use “in”: [“Engineering”] instead of “in”: “Engineering” if you want exact equality matching.

`contains_any`

Checks if the attribute (which should be a collection) contains any of the specified values. This operator is typically used when comparing two collections.

{
  "attribute": "identity.groups[*].external_id",
  "contains_any": [
    {
      "label": "Engineering Team",
      "value": "eng-group-id-123"
    },
    {
      "label": "Product Team",
      "value": "product-group-id-456"
    }
  ]
}

Existence Operators

`exists`

Checks whether an attribute exists (is not null or undefined).

{
  "attribute": "identity.manager",
  "exists": true
}

To check that an attribute does NOT exist:

{
  "attribute": "identity.end_date",
  "exists": false
}

Composition Operators

Conditions can be combined using logical operators to create complex expressions.

`and` (AND)

Returns true only when all conditions in the and array evaluate to true.

{
  "and": [
    {
      "attribute": "identity.custom_attributes['Department']",
      "equals": "Engineering"
    },
    {
      "attribute": "identity.custom_attributes['Level']",
      "equals": "Senior"
    }
  ]
}

This condition is true only if the identity has a Department of “Engineering” AND has a Level of “Senior”.

`or` (OR)

Returns true when at least one condition in the or array evaluates to true.

{
  "or": [
    {
      "attribute": "identity.custom_attributes['Department']",
      "equals": "Engineering"
    },
    {
      "attribute": "identity.custom_attributes['Department']",
      "equals": "Product"
    }
  ]
}

This condition is true if the identity has a Department of either “Engineering” OR “Product”.

`not` (NOT)

Negates a condition. The nested condition must evaluate to false for the overall condition to be true.

{
  "not": {
    "attribute": "identity.custom_attributes['Department']",
    "equals": "Sales"
  }
}

This condition is true if the identity does NOT have a Department of “Sales”.

Complex Nested Conditions

You can combine all composition operators to create complex logic:

{
  "and": [
    {
      "or": [
        {
          "attribute": "identity.custom_attributes['Department']",
          "equals": "Engineering"
        },
        {
          "attribute": "identity.custom_attributes['Department']",
          "equals": "Product"
        }
      ]
    },
    {
      "not": {
        "attribute": "identity.status",
        "equals": "Inactive"
      }
    },
    {
      "attribute": "identity.start_date",
      ">": "2020-01-01T00:00:00Z"
    }
  ]
}

This condition is true if:

The identity has a Department of “Engineering” OR “Product”, AND
The identity status is NOT “Inactive”, AND
The identity’s Start Date is after January 1, 2020

Advanced Operators

`lumos_expression`

The lumos_expression operator allows you to use the Lumos Expression Language (LEL) to write complex conditional logic that goes beyond what standard condition operators can express. This is particularly useful for:

Complex conditional logic with multiple conditions
Data transformations and comparisons
Fallback values and default handling
String manipulations and transformations

Important: When using lumos_expression, you reference identity attributes using the identity. prefix, which is consistent with standard condition attributes. Standard Attributes in LEL:

identity.given_name - First name
identity.family_name - Last name
identity.email - Email address

Custom Attributes in LEL:

identity.custom_attributes["Attribute Name"] - Access custom attributes

Basic Example:

{
  "lumos_expression": "identity.custom_attributes['Level'] == 'Senior' && identity.start_date > '2020-01-01'"
}

Example with Conditional Logic:

{
  "lumos_expression": "(identity.custom_attributes['Department'] == 'Engineering' || identity.custom_attributes['Department'] == 'Product') && identity.start_date > '2020-01-01'"
}

This condition checks if the identity is in Engineering or Product AND has a start date after 2020. Example with Fallback Values:

{
  "lumos_expression": "(identity.custom_attributes['Preferred Team'] or identity.team) == 'Engineering'"
}

This condition checks if the identity’s preferred team (if available) or default team equals “Engineering”. Example with String Transformations:

{
  "lumos_expression": "identity.email.split('@')[0].lower() == 'engineer'"
}

This condition checks if the email username (before the @) is “engineer” (case-insensitive). When to Use lumos_expression vs Standard Operators:

Use standard operators (equals, in, and, or, etc.) for simple, straightforward conditions. They’re easier to read and maintain.
Use lumos_expression when you need:
- Complex conditional logic that’s difficult to express with nested and/or/not
- Data transformations (string manipulation, case conversion, etc.)
- Fallback values or default handling
- Calculations or comparisons that require expressions

For more information about Lumos Expression Language, including all available transformations and functions, see the Lumos Expression Language documentation.

Common Use Cases

Access Policy: Department-Based Access

Grant access to all Engineering team members:

{
  "attribute": "identity.custom_attributes['Department']",
  "equals": "Engineering"
}

Access Policy: Multiple Departments

Grant access to Engineering, Product, or Design:

{
  "or": [
    {"attribute": "identity.custom_attributes['Department']", "equals": "Engineering"},
    {"attribute": "identity.custom_attributes['Department']", "equals": "Product"},
    {"attribute": "identity.custom_attributes['Department']", "equals": "Design"}
  ]
}

Access Policy: Senior Engineers Only

Grant access to senior engineers with start date after 2020:

{
  "and": [
    {"attribute": "identity.custom_attributes['Department']", "equals": "Engineering"},
    {"attribute": "identity.custom_attributes['Level']", "equals": "Senior"},
    {"attribute": "identity.start_date", ">": "2020-01-01T00:00:00Z"}
  ]
}

Access Policy: Active Employees in Specific Teams

Grant access to active employees in specific teams:

{
  "and": [
    {
      "attribute": "identity.status",
      "equals": "Active"
    },
    {
      "or": [
        {
          "attribute": {
            "label": "Team",
            "value": "identity.team"
          },
          "in": ["Backend", "Frontend", "Infrastructure"]
        }
      ]
    }
  ]
}

Access Policy: Direct Reports of Specific Managers

Grant access to all direct reports of specific managers:

{
  "attribute": {
    "label": "Manager",
    "value": "identity.manager.uuid"
  },
  "in": [
    {
      "label": "Jane Smith",
      "value": "550e8400-e29b-41d4-a716-446655440000"
    },
    {
      "label": "John Doe",
      "value": "660e8400-e29b-41d4-a716-446655440001"
    }
  ]
}

Access Policy: Members of Specific Groups

Grant access to identities who are members of any of the specified groups:

{
  "attribute": "identity.groups[*].external_id",
  "contains_any": [
    {
      "label": "Engineering Group",
      "value": "eng-group-id-123"
    },
    {
      "label": "Product Group",
      "value": "product-group-id-456"
    }
  ]
}

Using Conditions in Access Policies API

In the Lumos API, conditions are used in the access_condition field of Access Policies:

{
  "name": "Engineering Access Policy",
  "business_justification": "Automatic access for engineering team",
  "is_everyone_condition": false,
  "access_condition": {
    "attribute": "identity.custom_attributes['Department']",
    "equals": "Engineering"
  },
  "apps": [
    {
      "id": "app-uuid-here",
      "is_preapproved": true,
      "permissions": []
    }
  ]
}

When is_everyone_condition is true, the access_condition field is ignored and the policy applies to everyone.

Error Handling

If a condition references an attribute that doesn’t exist on an identity, the condition evaluation may fail or return false depending on the context. Always ensure your attribute paths are correct and that the identities you’re evaluating have the expected structure.

​Overview

​Basic Structure

​Simple Condition Example

​Attributes

​String Attribute

​Attribute Operand

​Attribute Types

​STRING

​IDENTITY

​GROUP

​DATETIME

​Value Options

​Supported Value Types

​Operators

​Comparison Operators

​equals

​!= (Not Equal To)

​> (Greater Than)

​>= (Greater Than or Equal To)

​< (Less Than)

​<= (Less Than or Equal To)

​String Operators

​contains

​starts_with

​ends_with

​Collection Operators

​in

​contains_any

​Existence Operators

​exists

​Composition Operators

​and (AND)

​or (OR)

​not (NOT)

​Complex Nested Conditions

​Advanced Operators

​lumos_expression

​Common Use Cases

​Access Policy: Department-Based Access

​Access Policy: Multiple Departments

​Access Policy: Senior Engineers Only

​Access Policy: Active Employees in Specific Teams

​Access Policy: Direct Reports of Specific Managers

​Access Policy: Members of Specific Groups

​Using Conditions in Access Policies API

​Error Handling