About the Okta Expression Language

Event hooks now include filtering support and a new creation flow. These are Beta features. See Beta Programs. To provide feedback on event hook filtering, complete the Feedback form.

Okta Expression Language (EL) enables you to receive only certain events from Okta event hooks. When creating or modifying an event hook, you can use Okta EL expressions to:

  • Define a filter to allow a subset of events that are triggered by an event hook.

  • Receive only events that you are interested in viewing.

  • Reduce the noise to the external web service handling your event hook.

Configuration information

  • Ensure that your expression evaluates to a Boolean when defining a filter for your event hook.

  • Start with simple expressions and gradually add conditions. This approach helps to make sure that your expression works as expected.

Use

  • == to denote the Equality operator.
  • != to denote the Inequality operator.
  • && to denote the And operator.
  • || to denote the Or operator.

Define group conditions

Use the Okta EL to define a list of groups that can activate an event hook. Make sure that your expression evaluates to a Boolean: True to include groups or False to prevent the event hook from activating.

The following example uses the Okta EL to activate an event hook for a group called: Sales:

event.target.?[type eq 'UserGroup' && displayName eq 'Sales'].size()> 0

Copy
...
   "target": [
      {
        "id": "00gsnc3qy7Uy6JZfy0h7",
        "type": "UserGroup",
        "alternateId": "unknown",
        "displayName": "Sales"
      }
    ],
...

Use the following event types with group conditions:

  • group.user_membership.add

  • group.user_membership.remove

  • group.lifecycle.create

  • group.lifecycle.delete

  • group.profile.update

  • group.privilege.revoke

  • group.privilege.grant

  • system.import.group.create

  • system.import.group.delete

Sample expressions

Use case Sample expression
Activate an event hook for specific group names event.target.?[type eq 'UserGroup' && displayName eq 'Sales'].size()> 0 || event.target.?[type eq 'UserGroup' && displayName eq 'Marketing'].size()> 0
Activate an event hook for specific group IDs event.target.?[type eq 'UserGroup' && id eq '00gsnc3qy7Uy6JZfy0h7'].size()> 0 || event.target.?[type eq 'UserGroup' && id eq '032gs2nc3qy7Uy6JZfasd3'].size()> 0
Use a combination of user attributes and groups to define complex expressions to include when a specific user is added to a specific group event.target.?[type eq 'User' && id eq '00usnkgbd0FFDxYaj0h7'].size()>0 && event.target.?[type eq 'UserGroup' && displayName eq 'Admin'].size()> 0

Define application conditions

Use the Okta EL to define a list of applications that can activate an event hook. Make sure that your expression evaluates to a Boolean: True to include applications or False to prevent the event hook from activating.

The following example uses the Okta EL to activate an event hook for a Bookmark application named My COMPANY Bookmark App:

event.target.?[type eq 'AppInstance' && alternateId eq 'My COMPANY Bookmark App'].size()> 0

Copy
...
     "target": [
        {
          "id": "0oat26meilfdn0Em90h7",
          "type": "AppInstance",
          "alternateId": "MY COMPANY Bookmark App",
          "displayName": "Bookmark App"
        },
...

Use the following event types with application conditions:

  • application.lifecycle.create

  • application.lifecycle.update

  • application.lifecycle.delete

  • application.lifecycle.activate

  • application.lifecycle.deactivate

  • application.user_membership.add

  • application.user_membership.remove

  • application.user_membership.change_password

  • application.provision.user.sync

  • app.oauth2.as.consent.grant

Sample expressions

Use case Sample expression
Activate an event hook for specific application names event.target.?[type eq 'AppInstance' && alternateId eq 'My Company Bookmark App'].size()> 0 || event.target.?[type eq 'AppInstance' && alternateId eq 'My OIDC App'].size()> 0
Activate an event hook for specific application IDs event.target.?[type eq 'AppInstance' && id eq '00gsnc3qy7Uy6JZfy0h7'].size()> 0 || event.target.?[type eq 'AppInstance' && id eq '032gs2nc3qy7Uy6JZfasd3'].size()> 0
Use a combination of user attributes and groups to define complex expressions to include when a specific user is added to a specific application event.target.?[type eq 'User' && id eq '00usnkgbd0FFDxYaj0h7'].size()>0 && (event.target.?[type eq 'AppInstance' && alternateId eq 'My Admin App'].size()> 0

Define user profile conditions

Use the Okta EL to define a list of user profile attributes that activate an event hook. Ensure that your expression evaluates to a Boolean: True to include applications or False to prevent the event hook from activating.

The following example uses the Okta EL to activate an event hook for a user whose email has been updated:

event.debugData.changedAttributes.contains('email')

Copy
..
     "debugContext": {
        "debugData": {
          "requestId": "XyMjlc1OvvWkZPMA7QazbwAAFIs",
          "threatSuspected": "false",
          "requestUri": "/api/v1/users/00ut27as6fbC0K3rS0h7",
          "changedAttributes": "email",
          "targetEventHookIds": "whot1dekaabE2suVh0h7",
          "url": "/api/v1/users/00ut27as6fbC0K3rS0h7?"
        }
      },
...

The following represents the most common event type for profile conditions:

  • user.account.update_profile

Sample expressions

Use case Sample expression
Activate an event hook when specific user profile attributes are updated event.debugData.changedAttributes.contains('email') || event.debugData.changedAttributes.contains('manager') || event.debugData.changedAttributes.contains('department')

Define login conditions

Use the Okta EL to define specific sign in conditions that activate an event hook. Make sure that your expression evaluates to a Boolean: True to include applications or False to prevent the event hook from activating.

This list provides available outcome options: SUCCESS, FAILURE, SKIPPED, UNKNOWN, CHALLENGE, DENY.

The following example uses the Okta EL to activate an event hook for a successful user sign in:

event.outcome.result =='SUCCESS'

The following example uses the Okta EL to activate an event hook for a failed user sign in:

event.outcome.result =='FAILURE'

The following represents the most common event type for a sign in condition:

  • user.session.start

Sample expressions

Use case Sample expression
Activate an event hook for a successful sign in event.outcome.result == 'SUCCESS'

Activate an event hook for a failed sign in

event.outcome.result == 'FAILURE'

Activate an event hook for a specific user's email address

event.actor.alternateId == 'myAdmin@company.com'

Activate an event hook for a specific user ID

event.actor.id == '00usnkgbd0FFDxYaj0h7'

Activate an event hook for failed sign in attempts for a specific user

event.actor.alternateId == 'myAdmin@company.com' &&

event.outcome.result == 'FAILURE'

Define MFA factor conditions

Use the Okta EL to define a list of MFA factors that can activate an event hook. Make sure that your expression evaluates to a Boolean: True to include applications or False to prevent the event hook from activating.

The following example uses the Okta EL to activate an event hook when a security question is used as an MFA Factor:

event.outcome.reason.contains( 'SECURITY_QUESTION')

Use the following event types with application conditions:

  • user.mfa.factor.activate

  • user.mfa.factor.deactivate

  • user.mfa.factor.suspend

  • user.mfa.factor.unsuspend

  • user.authentication.auth_via_mfa

Sample expressions

Use case Sample expression

Activate an event hook for a specific MFA factor. The following are the available factor types:

  • SECURITY_QUESTION

  • SMS_FACTOR

  • CALL_FACTOR

  • OKTA_VERIFY_PUSH

  • EMAIL_FACTOR

  • OKTA_SOFT_TOKEN

  • SECURID_FACTOR

  • YUBIKEY_OTP_FACTOR

  • DUO_SECURITY

event.outcome.reason.contains('SECURITY_QUESTION')

Related topics

About event hooks

Create an event hook