Checkboxes can describe simple choices. Real rules need a way to ask questions and combine the answers.

Imagine you manage access for a company with five thousand people. You want finance staff to use a strong proof of identity when opening the payroll system, except when they are in the office on a company laptop. You want contractors to lose access automatically on the date their contract ends. You want the app to receive each person’s department and country in a particular format. None of these wishes is exotic, yet each one needs a decision based on facts about a person.

What fixed settings cannot do

A fixed setting has only a few positions, like a light switch. It cannot say “if this and that, but not the other.” As soon as your wishes need combinations, comparisons, or small calculations, a fixed setting runs out of room. You would need to create many groups and many policies just to cover every combination, and the result would be a pile of near-duplicates that nobody can maintain.

What an expression adds

An expression is a short statement that Okta works out when it needs an answer. It looks at facts, such as the person’s department, their group memberships, or the date, and produces a result, such as yes or no, or a piece of text. Because it is evaluated on demand, it adapts to each person and each moment without you creating a separate setting for each case.

The cost of power

The same flexibility that makes expressions useful can make them dangerous. An expression that is too clever is hard to read, hard to test, and easy to break with a small change in the data. A good Okta administrator uses expressions where they truly help, and uses simple settings everywhere else.

A small set of words appears again and again in this topic. Learn them once and the rest reads easily.

Expression

An expression is a short piece of text that Okta works out to produce a value. Working it out is called evaluating it. The result might be a yes-or-no answer, a number, or a piece of text.

Attribute

An attribute is one fact about something, such as a person’s first name, department, or country. Attributes live in profiles. A user profile holds facts about a person. An application profile holds facts about a person’s account inside an app.

Namespace and object

Expressions need a way to say where a fact comes from. Okta groups data and tools under names, much like labeled drawers in a cabinet. One drawer holds facts about the user. Another holds facts about the device. Another holds helper tools for working with text. These named drawers are often called namespaces or objects.

Operator

An operator is a symbol or word that combines or compares things. Examples in plain terms: “is equal to,” “is not equal to,” “is greater than,” “and,” “or,” and “not.” Operators let you build a bigger question out of smaller ones.

Function

A function is a small ready-made tool that takes some input and gives back a result. For example, a function that checks whether a piece of text contains another piece, or one that joins two pieces of text, or one that tells you the current time. Functions are grouped by topic, such as text, lists, groups, and time.

Boolean

A boolean is a value that is either true or false. Policy conditions and group rules need booleans, because their question is always “does this apply, yes or no?”

Context

Context is the set of facts available at the moment an expression is evaluated. During a sign-in, the context might include the person, the app, the device, and the network. In another moment, such as importing a user, the context is different. An expression can only use facts that exist in its context.

Expressions show up in several places in Okta. Some are inside policy rules, and many are in the places that prepare the data policies rely on.

The title of this guide says “in policies,” and it is worth being precise about what that means. Policies make decisions using facts. Those facts come from somewhere: group membership, profile attributes, device information, and more. Expressions can appear in the policies themselves, where Okta supports it, and also in the supporting features that create the facts. A complete understanding needs both.

Why groups matter most

For most organizations, the most common and most important use of expressions near policies is group rules. A group rule says, “Put a person in this group whenever this expression is true for them.” The group is then assigned to policies, apps, or both. In effect, an expression in a group rule is a quiet policy writer: it decides, person by person, who is covered.

flowchart LR
    PR["User profile
attributes"] --> GR["Group rule
expression decides membership"]
    GR --> GM["Group
membership"]
    GM --> PO["Policy or app
assigned to the group"]
    PR --> MAP["Attribute mapping
expression builds values"]
    MAP --> APP["App profile and
token claims"]
    PR --> RC["Policy rule
custom expression, where supported"]
    RC --> PO
    

The diagram shows three paths from the user profile. One goes through a group rule to group membership, and then to policies and apps. One goes through an attribute mapping to the app profile and token claims. A third goes straight into a policy rule, where custom expressions are supported. All three start with the same facts, and all three use the same language.

Every expression, however long, is built from the same few kinds of pieces.

You can read any expression by splitting it into four kinds of parts. First, references: places where the expression points at a fact, like the person’s department. Second, literals: fixed values written directly, such as the word “Sales” or the number 18. Third, operators: the words or symbols that compare or combine. Fourth, function calls: uses of ready-made tools. A longer expression is just these parts joined together.

Reading an expression in words

Take an idea such as “the person’s department is Sales and their employment type is not Contractor.” In plain words, that has two small questions joined by “and.” The first compares a reference (department) with a literal (Sales) using “is equal to.” The second compares another reference (employment type) with a literal (Contractor) using “is not equal to.” The “and” demands that both be true. That is the whole structure.

flowchart TD
    E["Whole expression"] --> A["Left question
department is Sales"]
    E --> J["Joiner
and"]
    E --> B["Right question
type is not Contractor"]
    A --> A1["Reference: department"]
    A --> A2["Operator: is equal to"]
    A --> A3["Literal: Sales"]
    B --> B1["Reference: employment type"]
    B --> B2["Operator: is not equal to"]
    B --> B3["Literal: Contractor"]
    

Nesting and grouping

Questions can be placed inside bigger questions, using grouping marks, much like brackets in arithmetic. Brackets tell Okta which parts to work out first. Without them, Okta follows its own order of precedence, which means some operators are applied before others. When in doubt, use brackets. They cost nothing and make your intent clear to both Okta and the next reader.

What an expression returns

Every expression ends up as a single value. In a group rule or a policy condition, that value must be true or false. In an attribute mapping, the value might be text or a number. If an expression returns the wrong kind of value for its job, Okta will reject it or behave unexpectedly. Knowing what each place expects is part of using EL well.

Facts come in different shapes. Mixing the shapes is one of the most common sources of surprise.

Every value in EL has a type, which is its shape. Treating a value as the wrong shape leads to wrong answers or errors, so it helps to know the main ones.

Text

Text, also called a string, is a series of characters, such as a name or a department. Text comparisons are usually sensitive to capital letters, so “Sales” and “sales” may not be treated as equal. Text may also hide trailing spaces that you cannot see but that change the result.

Numbers

Numbers are used for counts, levels, and amounts. They can be compared in the usual ways: greater than, less than, equal. A number stored as text, like “42” in quotation marks, is not a number, and comparing it as one can fail or give odd results.

True or false

Booleans are the yes-or-no values. Some profile attributes are boolean, such as “is this account a service account.” Policy conditions must finally produce a boolean.

Lists

Lists, also called arrays or collections, hold several values together. A person might have several group memberships, several phone numbers, or several roles. Functions exist to check whether a list contains a value, how many items it holds, and to combine lists.

Dates and times

Dates and times are often stored as text in a particular format. To compare them, you usually convert them into a form that can be measured, such as a count of days. Time-based rules are powerful but need extra care about time zones and formats.

Nothing at all

Sometimes a fact has no value. The attribute was never filled in, or the person has no manager. This empty state is called null. Dealing with null is so important that it gets its own chapter later.

Before an expression can decide anything, it must point at facts. Okta organizes those facts into named places.

The exact list of available names depends on where the expression is used and on your version of Okta, so this chapter describes the main kinds in words. When you write the real thing, check the documentation for the names that apply to your situation.

User data

The most used source is the user profile: first name, last name, email, department, manager, country, employee type, and any custom attributes your organization added. Almost every group rule and many mappings start here. There are also facts about the user that are not in the profile, such as status or group memberships.

Application user data

When an expression runs for an app, it can often also reach the person’s account profile in that app. This is useful for building usernames and attributes that follow the app’s own conventions. It lets you combine facts about the person with facts about their app account.

Application and organization data

Some expressions can look at details of the app itself or of your organization, such as the org’s domain name. These help in building values like email-style usernames.

Device, session, and risk context

In policy evaluation contexts, additional objects may be available that describe the device, the session, or the assessed risk of the request. These allow rules such as “when the device is registered” or “when the risk level is high.” Their availability depends heavily on policy type, engine, and license.

Helper tools

Beside data, there are namespaces of tools: text helpers, list helpers, group helpers, time helpers, and conversion helpers. We cover these in the next chapters.

flowchart TB
    EX["Expression"] --> U["User facts"]
    EX --> AU["App user facts"]
    EX --> ORG["App and org facts"]
    EX --> CTX["Device, session, risk
where the context has them"]
    EX --> TL["Helper tools
text, lists, groups, time"]
    

Operators are the glue of expressions. A handful of them cover almost everything you will need.

Comparison operators

Comparison operators ask how two values relate. Is one equal to the other? Not equal? Greater? Smaller? Greater or equal? Smaller or equal? These produce a true or false answer. They are the building blocks of nearly every condition. For text, equality usually considers capital letters, so you may need a helper to normalize case before comparing.

Logical operators

Logical operators combine true-or-false answers. “And” demands that both sides be true. “Or” demands that at least one side be true. “Not” flips an answer. These let you build compound questions such as “in Sales and not a contractor,” or “in Finance or in Legal.”

The conditional choice

Many versions of EL offer a compact way to choose between two results depending on a test, sometimes called a ternary or conditional operator. It reads like “if this is true, give me that, otherwise give me the other.” It is useful in attribute mappings, where you want to compute a value, such as using a nickname if one exists and the first name otherwise.

Joining text

A plus sign or a text-joining function is commonly used to glue pieces of text together, as in building a display name from a first name and a last name with a space between. When joining, remember that missing values can turn into odd results.

Order of operations

When several operators appear together, Okta applies them in a defined order of precedence. For example, “and” is typically applied before “or,” just as multiplication comes before addition in arithmetic. Relying on memory of this order is risky. Use brackets to make your meaning explicit.

flowchart TD
    Q["Is the person eligible?"] --> A{"In Sales?"}
    A -->|"Yes"| B{"Not a contractor?"}
    A -->|"No"| N["Not eligible"]
    B -->|"Yes"| Y["Eligible"]
    B -->|"No"| N
    

The diagram shows how “and” behaves: the person must pass the first question and then the second. An “or” would instead let a person pass if either question was answered yes. Drawing a compound expression as a small decision path is a good way to check that you wrote what you meant.

Text is the most common kind of data in profiles, so text helpers are the functions you will meet most often.

Okta groups its helper functions into namespaces by topic. The text helpers live in a namespace usually named for strings. The exact list may grow over time, so the documentation is the authority. Here are the common jobs, described in words.

Checking text

Helpers can check whether a piece of text contains another piece, starts with it, or ends with it. They can also check whether the whole text matches a pattern, using a compact pattern language called a regular expression. Regular expressions are powerful but famously hard to read, so use them sparingly and document them well.

Changing text

Helpers can change text to all capitals or all lowercase, trim away spaces at the beginning and end, replace parts, or take a slice from a certain position. Normalizing case and trimming spaces before comparing is a very good habit, because people and systems enter data inconsistently.

Measuring and joining

Helpers can tell you how long a piece of text is, and can join several pieces together, sometimes with a separator between them. Joining is how you assemble usernames, display names, and email-like identifiers.

Extracting parts

A frequent job is pulling a piece out of text, such as the part of an email address before the at sign, or the domain after it. Text helpers can find a position and slice around it. When extracting, always consider what happens if the text does not have the shape you expected.

Why normalizing helps policies

Data in profiles often comes from many sources: an HR system, a directory, manual typing. One source writes “Sales,” another writes “sales,” a third writes “Sales ” with a trailing space. A group rule that expects exact equality will miss two of the three. A good expression normalizes first, so that all three variants count as the same department.

Policies are mostly about groups of people. Group and list helpers let expressions ask group-shaped questions.

Working with lists

List helpers let you ask whether a list contains a certain value, whether it contains any of several values, how many items it holds, and whether it is empty. They also let you combine lists or take a single item from one. Because many profile attributes can hold several values, list helpers are often the right tool when a plain comparison fails.

Group membership helpers

A dedicated set of helpers focuses on groups. In plain words, they answer questions like “is this person a member of the group with this identifier,” “is this person a member of the group with this name,” and “is this person a member of any of these groups.” There are also helpers that gather the groups a person belongs to, sometimes narrowed by a name pattern, which is useful when building group claims for tokens.

Names versus identifiers

Groups have a human-friendly name and a stable identifier. Names can be renamed. Identifiers do not change. An expression that uses a name will break if someone renames the group. An expression that uses the identifier survives renames but is harder to read. Many teams use identifiers for important rules and add a note beside them saying which group each identifier stands for.

Careful with membership timing

Group membership can change by rule or by import, and those changes take time to apply. An expression that asks “is the person in this group” sees the membership as it stands at the moment of evaluation. If a person was just added, the expression may not yet see it. This is another reason to test with real timing.

sequenceDiagram
    participant R as Rule or Mapping
    participant E as Expression Engine
    participant G as Group Data
    participant U as User Data
    R->>E: Evaluate for this person
    E->>U: Read profile facts
    E->>G: Ask about group membership
    G-->>E: Current memberships
    E-->>R: True, false, or computed value
    

Besides text and lists, EL offers helpers for the clock, for changing types, and for a few special jobs.

Time helpers

Time helpers can report the current time, convert text to a date, and measure the distance between two dates. These are the ingredients of rules like “a contractor whose end date has passed,” or “an account created in the last thirty days.” Time-based expressions are evaluated when Okta runs them, so the answer can change from day to day for the same person without any profile change.

Conversion helpers

Conversion helpers change one type into another, such as text into a number, a number into text, or a text date into a date value. They solve the common problem where a value looks like the right kind but is stored as the wrong kind. Convert first, then compare.

Country and region helpers

Some helpers translate between country codes and country names, which is useful when different systems use different spellings. They save you from maintaining your own long list of countries.

Directory helpers

When Okta is connected to a directory such as Active Directory, special helpers can reach directory-specific facts. These are used in mappings and are only meaningful when a directory is in use.

flowchart LR
    T["Contract end date
stored as text"] --> C["Convert to a date"]
    C --> D["Measure days from today"]
    D --> Q{"Is it less than zero?"}
    Q -->|"Yes"| X["Contract has ended"]
    Q -->|"No"| Y["Contract still active"]
    

The diagram shows a typical time expression, drawn as a little pipeline. The date starts as text. A conversion helper turns it into a real date. A time helper measures the distance from today. A comparison decides the outcome. Building complex expressions step by step like this makes them easier to design and check.

Real data is incomplete and inconsistent. Expressions that ignore this fail in the most annoying ways.

Null, empty, and missing

There are three related states. A missing attribute means the profile has no such field. A null value means the field exists but holds nothing. An empty text means the field holds text of zero length. These can look the same on screen but behave differently in expressions. A comparison that expects text may fail or return an unexpected result when given nothing at all.

Guard first, then use

The safest habit is to guard: first check that the value exists, then use it. In words: “if the manager is set, and the manager’s department is Sales.” If the guard is false, the rest is not evaluated in many contexts, so it cannot fail. Without a guard, the expression may crash or return false for the wrong reason.

Defaults

In mappings, you can supply a default for missing values. For example, “use the nickname if there is one, otherwise the first name.” This keeps the app from receiving an empty field. Defaults should be sensible and visible, not made-up values that hide a data problem.

Case and spaces

As discussed, capitals and trailing spaces cause subtle mismatches. Normalize before comparing. Also be aware of unusual characters copied from documents, such as non-breaking spaces or fancy quotation marks, which look normal but do not match.

Multi-valued confusion

If an attribute can hold a list, a single value comparison will not behave as you expect. Check the declared type and use list helpers where needed.

For most organizations, the single most valuable use of EL near policies is the group rule.

A group rule is an automatic membership instruction. It says, “Whenever a person’s profile satisfies this expression, place them in that group; whenever it no longer does, remove them.” Because policies and app assignments are very often tied to groups, a group rule is an indirect way to say, “this policy applies to people who satisfy this expression.”

Why dynamic groups are powerful

Without group rules, administrators add and remove people by hand. People change roles, leave, or join, and the groups slowly drift from the truth. With group rules, the group follows the data. When HR updates a person’s department, the person moves to the right group, and with it to the right policy. This keeps access aligned with reality and reduces manual work.

What group rule expressions look like in words

A typical group rule expression compares one or more profile attributes with fixed values: department equals Sales, country is one of a list, employee type is not Contractor. They are intentionally simple. Group rules are meant to be easy to read, because they quietly affect many people. Okta also validates them when you save and may limit their length and complexity.

The timing of group rules

Group rules are processed by Okta in the background. After you create or change one, it is activated, and then the membership is recalculated. A change in a person’s profile also triggers re-evaluation. These processes take some time, so membership may lag behind. Plan around that delay in your testing and your communications.

Excluding people

Group rules can also name people to exclude, who never join the group even if the expression is true. Use exclusions sparingly, and document why each person is excluded, since an exclusion is an exception that others cannot see in the expression itself.

flowchart TD
    CH["Profile changes
for example department"] --> EV["Group rule evaluates
the expression"]
    EV --> T{"True for this person?"}
    T -->|"Yes"| ADD["Person joins the group"]
    T -->|"No"| REM["Person leaves the group"]
    ADD --> POL["Policies and apps tied
to the group now apply"]
    REM --> POL2["Policies and apps tied
to the group stop applying"]
    

Where Okta allows it, you can place a custom expression directly into a policy rule as one of its conditions.

Policy rules normally use built-in conditions: group, network zone, device state, risk level, and so on. These are quick to set and easy to read. Sometimes they cannot express what you need. Some policy screens therefore offer a place to add a custom expression as an extra condition. The expression must produce a true or false answer. When it is true, along with all the other conditions, the rule applies.

When a custom expression helps

Custom expressions are most useful for conditions the built-in options do not cover. Examples in words: “the person’s profile says they are a manager and their cost center begins with a certain code,” or “the device’s operating system version is above a certain number and the person is not in a given group,” or “the request arrives on a weekday.” They let one rule capture a combination that would otherwise need extra groups and extra rules.

How it fits into rule evaluation

A custom expression is just another condition in the rule. All of a rule’s conditions must be true together. So a custom expression narrows the rule, never widens it. The rule’s position in the list still decides when it is read. First match still wins. An expression does not change the ordering logic, it only changes whether the rule matches.

flowchart TD
    R["Rule is read in order"] --> C1{"Built-in conditions true?
group, zone, device"}
    C1 -->|"No"| NEXT["Skip to the next rule"]
    C1 -->|"Yes"| C2{"Custom expression true?"}
    C2 -->|"No"| NEXT
    C2 -->|"Yes"| ACT["Rule wins
apply its action"]
    

What can go wrong

Custom expressions add power and risk in equal measure. They can reference data that is not available at the moment of evaluation. They can hide complexity inside a single field that few people will inspect. And they are easy to get subtly wrong, such as a wrong capital letter or a missing guard for empty values. A rule with a broken expression may never match, or may match when it should not.

An expression can only use facts that exist at the moment it runs. This is the most common hidden reason expressions fail.

Okta evaluates expressions at many different moments: when a group rule recalculates, when a person is imported, when a person signs in, when an app is opened, when a token is created. At each moment, a different set of facts is available. Think of each moment as a different room with different furniture.

Examples of differing context

During a group rule calculation, the user profile is available, but there is no device and no network, because nobody is signing in. During a sign-in policy evaluation, device and network facts may be available, as well as the user. During a token creation, facts about the app and the requested access may be available. During an attribute mapping at import, the source profile may be available, but not any live session.

The consequence

An expression written for one room may point at furniture that does not exist in another. If you copy a device-based expression into a group rule, it will fail, because group rules run without a device. The same applies the other way round: not every profile detail is available to every policy screen.

flowchart LR
    subgraph G["Group rule room"]
        G1["User profile"]
    end
    subgraph S["Sign-in policy room"]
        S1["User profile"]
        S2["Groups"]
        S3["Device and network"]
        S4["Risk"]
    end
    subgraph T["Token room"]
        T1["User profile"]
        T2["Client app"]
        T3["Scopes"]
    end
    

The diagram shows three rooms with different contents. The profile appears in all three, which is why profile-based expressions are the most portable. Device and risk appear only in the sign-in room, which is why expressions using them cannot be used elsewhere.

Understanding the evaluation steps helps you predict results and find mistakes.

When Okta meets an expression, it does a short series of steps. First it reads the text and checks that it is well formed, like checking that a sentence has proper grammar. This step is called parsing. If the grammar is wrong, Okta refuses it, often right when you save. Second, it gathers the facts the expression references from the current context. Third, it works out the pieces from the inside outward, calling functions, applying operators, and respecting brackets. Fourth, it checks that the final value has the shape the place expects, such as a boolean for a condition. Finally, it uses the result.

sequenceDiagram
    participant A as Admin
    participant P as Parser
    participant C as Context
    participant V as Evaluator
    participant U as Feature using it
    A->>P: Save the expression
    P->>P: Check grammar and known names
    P-->>A: Accepted or rejected
    U->>V: Need an answer for this person
    V->>C: Fetch referenced facts
    C-->>V: Values or nothing
    V->>V: Work out pieces inside out
    V-->>U: Final value
    

Save time versus run time

The diagram separates two moments. At save time, Okta checks the grammar and that names exist. A passing save does not prove that the expression behaves correctly. At run time, Okta uses real data, which may be missing, oddly formatted, or of an unexpected type. Many errors only show up then. This is why saving successfully is only the first step of testing.

Short-circuiting

For “and” and “or,” Okta often stops as soon as the answer is certain. If the first part of an “and” is false, the whole thing is false, so the second part may never be worked out. This is why guards work: put the safety check first, and the risky part is skipped when the check fails. Do not rely on short-circuiting for side effects, since expressions should be calculations without lasting side effects.

Evaluation is repeated

Expressions are not stored as answers. They are worked out again each time they are needed, with the facts of that moment. This is what makes them adaptive. It also means a change in the data can change the result without anyone editing the expression.

Many policy problems start long before the policy, in how the underlying attributes were prepared.

Profiles in Okta can come from many sources: a directory, an HR system, an application, manual entry. Attribute mappings define how values are copied from one profile to another. A mapping can be a straight copy, or it can be an expression that calculates the value. The result is the attribute that group rules, policies, and apps later rely on.

Typical mapping jobs

Common jobs include building a display name from first and last name, building a username in the form an app expects, turning a department code into a friendly department name, choosing between a nickname and a first name, and converting country names into standard codes. Each job is a small expression over the source profile.

Mapping direction

Mappings have a direction. Some copy from an outside source into the Okta profile. Others copy from the Okta profile to an app profile. The direction decides which facts are available and when the mapping runs. Mappings can also be set to apply only on creation, or on every update, which changes how often your expression is worked out.

Why this matters for policies

If the department attribute is wrong, the group rule that depends on it is wrong, and the policy assigned to that group is wrong. A policy cannot be better than the data that feeds it. Spending effort on clean, consistent attributes, prepared by simple mapping expressions, is often the most effective way to improve policy accuracy.

flowchart LR
    SRC["Source system
HR or directory"] --> MAP1["Inbound mapping
expression cleans values"]
    MAP1 --> PROF["Okta user profile"]
    PROF --> GR["Group rules and policies
test the clean values"]
    PROF --> MAP2["Outbound mapping
expression builds app values"]
    MAP2 --> APP["Application profile"]
    

After a person signs in, expressions also decide what facts are passed to the app.

Claims in tokens

A claim is a statement about a person carried inside a token, such as their email or group list. On authorization servers, administrators can define custom claims whose values come from expressions. The expression is worked out when the token is created. A claim might hold the person’s department, a list of their group names matching a pattern, or a computed role label.

Statements for SAML apps

For apps that sign in using SAML, administrators define attribute statements and group attribute statements. Values can come from expressions over the user profile. The app then receives these facts and may use them to decide what the person sees or can do.

Policy meets claims

Access policies on an authorization server decide whether a token is issued at all. Claim expressions decide what goes inside it. Together they shape the app’s view of the person. If an app grants powers based on a role claim, then the expression that produces that claim is as sensitive as any access policy.

Keep claims small and necessary

Every claim adds to token size and exposes information. Include only what the app needs. A group claim that lists hundreds of groups can make tokens too large to handle. Use filters, such as matching only groups with a certain naming pattern, to keep it focused.

Now we zoom out to see how the pieces involved in expressions fit together.

Expressions are not a separate product. They are a shared capability that many Okta features call on. Understanding the parts helps you reason about where a problem lives.

flowchart TB
    subgraph Authoring["Where expressions are written"]
        GRU["Group rules"]
        MAPS["Attribute mappings"]
        POLR["Policy rule conditions"]
        CLM["Claims and statements"]
    end
    subgraph Core["Expression capability"]
        PARSE["Parser
checks grammar"]
        EVAL["Evaluator
works out values"]
        LIB["Function library
text, lists, groups, time"]
    end
    subgraph Data["Facts"]
        PROF["User and app profiles"]
        GRP["Group memberships"]
        CTX["Device, session, risk context"]
    end
    GRU --> PARSE
    MAPS --> PARSE
    POLR --> PARSE
    CLM --> PARSE
    PARSE --> EVAL
    EVAL --> LIB
    PROF --> EVAL
    GRP --> EVAL
    CTX --> EVAL
    EVAL --> OUT["Result: true or false,
or a computed value"]
    OUT --> LOG["System Log and previews"]
    

The parts, one by one

Because the parser, evaluator, and function library are shared, learning EL once pays off in every feature. What differs from feature to feature is which facts are available and what kind of result is expected. When something breaks, ask which feature the expression lives in, what facts it had, and what kind of result the feature wanted.

The best way to learn is to walk through real situations. Each example below is described in words, not code, and followed through step by step.

Example 1: A group for full-time sales staff

The goal: place every full-time person in the Sales department into a group called “Sales Full-Time,” so that a stricter sign-in policy for customer data applies to them. In plain words, the group rule’s expression says: the department is Sales, and the employment type is Full-Time. Two small questions joined by “and.”

Now consider three people. Rohan is in Sales and Full-Time. Both questions are true, so he joins the group. Sneha is in Sales but a contractor. The second question is false, so she does not join. Imran is in Sales and Full-Time, but his department was typed as “sales” in lowercase by mistake. The first question compares exact text, so it is false, and Imran is missed. The fix is either to clean his data at the source or to make the expression normalize case before comparing.

Example 2: Contractors whose contract has ended

The goal: automatically move contractors out of an access group when their contract end date has passed. In words: the employment type is Contractor, and the end date is set, and the end date is earlier than today. The guard, “the end date is set,” comes before the date comparison, so that contractors with no end date do not cause errors.

Consider two contractors. Leela has an end date last week. All three parts are true, so the rule applies. Mark has no end date recorded. The guard fails and the rule does not apply. Whether Mark should lose access or keep it is a policy decision, not a technical one. The example shows why you decide, in advance, how missing data should be treated.

Example 3: Building a username for an app

The goal: send an app a username made from the person’s first name, a dot, and the last name, all in lowercase. In words: take the first name, make it lowercase, add a dot, add the last name made lowercase. This is a mapping expression, not a condition, so it returns text.

For “Asha Rao,” the result is the lowercase first name, a dot, and the lowercase last name. For a person whose last name contains a space, or an accent, the result may not suit the app. A careful designer checks several real names, including awkward ones, before saving.

Example 4: A custom condition in a sign-in rule

The goal: in a rule for a sensitive app, apply a stricter requirement when the person is a manager and the sign-in is not from the office network. If the policy screen supports custom expressions, the “manager” part can be written as a profile test, while the office network part uses the built-in network zone condition. Using both together keeps the expression small and the rule readable.

An expression that works today but nobody can read tomorrow is a liability.

Keep each expression small

A short expression is easier to read, test, and fix. If you find yourself writing a long chain of conditions, ask whether part of it could become its own group, its own attribute, or its own rule. Splitting a big idea into two or three small pieces is nearly always better than one clever expression.

Prefer clean attributes to clever expressions

If you often write the same awkward expression to cope with messy data, consider adding a clean attribute that prepares the data once. An attribute called “Access tier” with values like High and Standard is far easier to use in many rules than repeating a complicated test everywhere.

Name and describe

Give every group rule, mapping, and policy rule a name that describes its purpose, not its mechanics. Add a plain-language description saying who it is for, why it exists, and who owns it. In the description, write the expression’s meaning in one sentence. The expression says how. The description says why.

Make assumptions visible

Every expression assumes something: that a value is filled in, that text is lowercase, that a group has a certain identifier. Write those assumptions down. When the data changes, the assumption is the first place to look.

Use identifiers for stability, with notes

For groups and similar objects, use identifiers where stability matters, and keep a short note of what each identifier means. For readability, names are friendlier but fragile.

flowchart TD
    BIG["One long clever expression"] --> SPLIT{"Can it be split?"}
    SPLIT -->|"Yes"| P1["Small expression A
prepare an attribute"]
    SPLIT -->|"Yes"| P2["Small expression B
group rule"]
    SPLIT -->|"Yes"| P3["Simple policy rule
uses the group"]
    SPLIT -->|"No"| KEEP["Keep it, but document it well"]
    

Expressions decide who is covered by security rules. Mistakes in them are security mistakes.

Expressions as hidden access control

A group rule that puts people into an administrators group is an access control, even though it looks like a small formula. Anyone who can edit that expression can effectively grant admin rights. Treat the right to create or edit group rules and custom conditions as a privileged capability, and limit it to a small trusted set of administrators.

Trusting the data behind the expression

An expression is only as trustworthy as the attribute it tests. If people can edit their own profile attributes, and an expression grants access based on one of them, then a person might promote themselves by changing their own department. Make sure the attributes used for security decisions can only be changed by trusted sources, such as the HR system, and not by the person themselves.

Failure direction

Think about what happens when the expression cannot be evaluated. For an allow rule, failure usually means no match, which is safe. For a rule meant to block or tighten, failure may mean that the stricter rule does not apply and people slip through. Where possible, build blocking behavior so that failure is safe, for example by making the catch-all rule restrictive.

Least privilege in group rules

Write group rules as narrowly as possible. A rule that says “department contains Eng” may unexpectedly match “Engagement,” “Engineering,” and “Genealogy.” Exact matches and well-defined lists are safer than loose pattern matching.

Information in claims

Tokens and statements travel to other systems. Limit the facts you place in them. Avoid including sensitive personal data. Review claims whenever an app’s needs change, so that old, unnecessary claims do not linger.

Change control and audit

Require a review for changes to expressions that affect access, and keep a change record. The System Log keeps a trail of administrative changes, and your own notes should explain the reason for each. This is what you will lean on during an audit.

A successful save proves only that the grammar is fine. Testing proves that the logic is.

Use the tools Okta provides

Okta offers helpful checks in several places. When you save a group rule or a mapping, the system validates it and reports errors in grammar or unknown names. In the profile editor, a preview can show what a mapping would produce for a chosen person. Some policy screens offer simulation or preview tools. The availability of these tools varies, so look for them in your console.

Test with real people, on purpose

Choose a handful of real or realistic test profiles: one who should match, one who should not, one with missing data, one with unusual capitalization, and one who belongs to many groups. Walk each through the expression and write down the expected outcome before you test. Then compare.

Test in a safe place

Use a preview or test organization if you have one. Create test users with the edge-case data. Try the group rule or mapping there, and see who ends up where. Only then repeat the change in production.

Stage the rollout

For group rules, there is a useful safe path. Create the rule, check what it would do before activating it, and then activate it. After activation, look at the group’s membership and compare it to your expectation. Check both the count and a sample of names.

When an expression misbehaves, you need to see what it saw and what it returned.

Where to look

Several places can tell you the story. The System Log records administrative changes, such as who edited a group rule and when, and many events about sign-ins and policy decisions. The group itself shows its membership and, in some views, how each person came to be a member. The profile editor preview shows what a mapping would compute. The user’s profile page shows the actual attribute values the expression saw.

A debugging routine

Start with the person, not the expression. Look at the person’s actual attribute values, including capitalization and empty fields. Then read the expression in words and trace it using those values. Most surprises come from data that is not what you assumed. Next, check the group or policy result: is the person in the group, did the rule apply? Finally, check timing: has enough time passed for background processing, and does a live session explain the delay?

Watching for drift

Over time, groups driven by expressions can drift as data changes. Watch group sizes. A sudden jump or drop is a signal. If the Sales group doubles overnight, something changed in the data or in the rule. Set up simple reports that list group counts and review them regularly.

flowchart TD
    S["Surprising result"] --> A["Look at the person's actual attribute values"]
    A --> B["Trace the expression in words with those values"]
    B --> C{"Does the trace match the result?"}
    C -->|"Yes"| D["Fix the data or the intent"]
    C -->|"No"| E["Check context, timing, and other rules"]
    E --> F["Check System Log and group membership"]
    

Expressions are a sharp tool. Use them where they cut well and avoid them where they do not.

Choosing the right tool

For any need, work down a ladder from simplest to most powerful. First try a built-in condition. Then try a group, perhaps filled by a simple group rule. Then try a small expression in a mapping to prepare a clean attribute. Only then consider a custom expression in a policy rule. At each step, the cost of understanding and maintaining grows.

flowchart TD
    N["A new access need"] --> Q1{"Can a built-in condition do it?"}
    Q1 -->|"Yes"| U1["Use the built-in condition"]
    Q1 -->|"No"| Q2{"Can a group express it?"}
    Q2 -->|"Yes"| U2["Use a group, with a simple group rule if needed"]
    Q2 -->|"No"| Q3{"Can a clean attribute express it?"}
    Q3 -->|"Yes"| U3["Prepare the attribute with a mapping"]
    Q3 -->|"No"| U4["Use a custom expression with tests and review"]
    

A pattern is a proven way of solving a problem that keeps coming back. These patterns help you use expressions with confidence.

Pattern: Guard, then act

Before using a value, first check that it exists. In words: “if the end date is set, and it is earlier than today.” The guard comes first so that the second part never meets an empty value. Because Okta stops reading a chain of “and” tests once one of them is false, the guard protects the part that follows it.

Pattern: Normalize, then compare

Text can be written many ways: capital letters, small letters, extra spaces. Before comparing, make both sides look the same. For example, trim the spaces and make the text lowercase, then compare. This pattern removes a whole family of silent mismatches.

Pattern: Prepare once, use everywhere

If several rules need the same awkward calculation, do it once. Create a clean attribute, perhaps “Access tier,” filled by a mapping. Then every group rule and policy can simply test that attribute. Fixes happen in one place instead of ten.

Pattern: Group as the bridge

Use a group rule to turn profile facts into group membership, and let policies reference the group. The group is the readable name for an idea. Policy rules then say “people in the Finance Approvers group,” which anyone can understand.

Pattern: Explicit default

When an expression produces a value, decide what the fallback is. If the department is missing, should the person land in a “Needs review” bucket? Choosing a deliberate fallback is much better than leaving the outcome to chance.

Pattern: Lists over long chains

If you need “department is Sales or Support or Marketing or Success,” consider a list-based test, such as “department is one of this list.” A list is shorter, and adding a new item means adding one word instead of another clause.

flowchart LR
    DATA["Messy profile data"] --> NORM["Normalize
trim and lowercase"]
    NORM --> GUARD{"Value present?"}
    GUARD -->|"Yes"| TEST["Compare or test"]
    GUARD -->|"No"| FALL["Explicit fallback"]
    TEST --> GRP["Group membership"]
    FALL --> GRP
    GRP --> POL["Policy rule uses the group"]
    

An anti-pattern is a habit that looks sensible but causes trouble later. Each card below names one, shows how it appears, and how to fix it.

This chapter gathers the habits that separate calm administrators from frantic ones.

Best practices

Common mistakes

These short stories use made-up companies to show how the ideas appear in daily work. They are teaching examples, not descriptions of any real organization.

What the scenarios share

Each problem came from a quiet assumption about data: spelling, blanks, unusual names, or who could edit a field. Each fix combined a clearer expression, a cleaner data source, and a test person who would have caught the problem earlier.

Short answers to common questions. Where details depend on your license, engine, or release, confirm them in your own console and the official documentation.

Here is the whole story in a few lines you can carry with you.

Okta Expression Language is a small formula language that lets Okta make decisions from profile data. It reads facts, applies functions and operators, and returns either a yes or no answer or a piece of text. You meet it in group rules, attribute mappings, claims and statements, and in places where policy screens allow custom conditions. Because the same words can mean different things in different places, and because the data behind them can be messy, the habits that matter most are simple: keep expressions small, guard against blanks, normalize text, protect the data that security relies on, and test with real sample people.

Use the simplest tool that works. Built-in conditions and groups come first, clean attributes next, and custom expressions last. Whatever you build, write it first as a plain sentence, give it a name and an owner, and review it on a schedule. With these habits, expressions become a quiet, dependable part of your access design instead of a hidden source of surprises.