ilbee/okta-event

Symfony bundle that integrates Okta webhooks and dispatches typed Symfony events.

v1.0.1 2026-03-27 09:20 UTC

Requires

• php: >=8.4
• phpdocumentor/reflection-docblock: ^5.6
• symfony/config: ^6.4|^7.0
• symfony/dependency-injection: ^6.4|^7.0
• symfony/framework-bundle: ^6.4|^7.0
• symfony/http-kernel: ^6.4|^7.0
• symfony/property-info: ^6.4|^7.0
• symfony/routing: ^6.4|^7.0
• symfony/serializer: ^6.4|^7.0
• symfony/yaml: ^6.4|^7.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.75
• phpdocumentor/type-resolver: ^1.8
• phpstan/phpstan: ^2.1
• phpstan/phpstan-phpunit: ^2.0.5
• phpstan/phpstan-symfony: ^2.0
• phpunit/phpunit: ^12.2
• symfony/browser-kit: ^6.4|^7.0
• symfony/phpunit-bridge: ^6.4|^7.0
• symfony/property-access: ^7.4

MIT

• Julien Prigent

README

A Symfony bundle that receives Okta Event Hooks and dispatches typed Symfony events you can listen to in your application.

Table of Contents

• Features
• Installation
• Configuration
• Okta Setup
• Usage
• Security Recommendations
• Contributing
• License
• Full Documentation

Features

• Automatic webhook endpoint registration (GET verification + POST processing)
• 200+ typed events covering the full Okta Event Hook catalog:

Category	Examples
User Lifecycle	activate, create, deactivate, suspend, delete, password reset, profile update
User Authentication	session start/end, MFA enroll/reset, SSO, password change, account lock
Group Management	member add/remove, group create/delete, profile update
Application	user assign/unassign, app create/activate/deactivate, OAuth2 consent
Admin Privileges	role grant/revoke, IAM resource set/role/permission changes
Security	risk detection, breached credentials, suspicious activity, session context change
Policy	policy/rule activate/deactivate/update, trusted server changes
Device	device enroll/activate/suspend/delete, device trust, user add/remove
Access Request	request create/resolve/reject/expire, conditions, sequences
And more...	IdP lifecycle, log streams, inline hooks, rate limits, certifications, entitlements

• Duplicate event detection (pluggable store, cache-based or null)
• Configurable payload size and event count limits
• GenericOktaEvent fallback for unhandled event types

Installation

composer require ilbee/okta-event

If you don't use Symfony Flex, register the bundle manually in config/bundles.php:

Ilbee\Okta\Event\OktaEventBundle::class => ['all' => true],

Configuration

# config/packages/okta_event.yaml
okta_event:
  # Required - shared secret configured in the Okta Event Hook
  webhook_secret: '%env(OKTA_WEBHOOK_SECRET)%'

  # Optional - defaults shown
  # route: '/okta/webhook'
  # verification_enabled: true
  # max_payload_size: 1048576      # 1 MB
  # max_events_per_request: 100

Okta Setup

1. In Okta Admin, go to Workflow > Event Hooks > Create Event Hook.
2. Set the URL to your endpoint (e.g. https://example.com/okta/webhook).
3. Set Authentication field to X-Auth-Token and provide the same secret as webhook_secret.
4. Subscribe to the events you need.
5. Save — Okta sends a one-time GET verification that the bundle handles automatically. You can disable it afterwards with verification_enabled: false.

Usage

Listen to any typed event using Symfony's #[AsEventListener]:

use Ilbee\Okta\Event\Event\UserLifecycle\OktaUserDeactivatedEvent;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;

#[AsEventListener]
class OnUserDeactivated
{
    public function __invoke(OktaUserDeactivatedEvent $event): void
    {
        $email = $event->userEmail;
        $actor = $event->actor;
        // ...
    }
}

You can also listen to group-level events to handle an entire category:

use Ilbee\Okta\Event\Event\UserLifecycle\OktaUserLifecycleEvent;

#[AsEventListener]
class OnAnyUserLifecycleChange
{
    public function __invoke(OktaUserLifecycleEvent $event): void
    {
        // Fired for any user.lifecycle.* event
    }
}

For unknown/unhandled event types, a GenericOktaEvent is dispatched as fallback:

use Ilbee\Okta\Event\Event\GenericOktaEvent;

#[AsEventListener]
class OnUnknownOktaEvent
{
    public function __invoke(GenericOktaEvent $event): void
    {
        $rawEvent = $event->oktaEvent; // OktaEvent DTO with full payload
    }
}

Security Recommendations

For production, restrict traffic to Okta's IP ranges at the reverse proxy level:

location /okta/webhook {
    allow 100.21.118.0/24;
    allow 52.2.12.0/24;
    deny all;
    proxy_pass http://your-app;
}

Contributing

composer install
vendor/bin/phpunit
vendor/bin/phpstan analyse
vendor/bin/php-cs-fixer check ./src --diff --allow-risky=yes

License

MIT