Actions Engine

The Actions Engine allows you to extend Auris authentication flows with custom JavaScript code. Actions are hooks that run at specific points in the authentication pipeline — before login, after login, before signup, and so on — enabling you to implement custom business logic without modifying the Auris platform itself.

Common uses for Actions include:

• Adding custom data to JWT tokens (department, subscription tier, feature flags)
• Blocking logins based on business conditions (email domain, account status in an external system)
• Logging authentication events to an external SIEM or analytics platform
• Enforcing additional validation before user registration
• Integrating with identity governance systems

Triggers

Actions are associated with a trigger, which defines when the action runs in the authentication pipeline. A single trigger can have multiple actions, which execute in configured order.

Note: Post-Login is the most commonly used trigger and the best starting point for most use cases (adding claims, logging). Use Pre-Login sparingly, as it runs for every login attempt including failed ones, which can affect performance under high load.

The Actions List

Go to Console → Actions to view all actions in your tenant.

The list shows:

Actions are sorted by trigger and execution order. Within the same trigger, the number in the Order column determines execution sequence.

Creating an Action

Writing Action Code

The Context Object

Every action receives a single context argument. Its structure depends on the trigger:

// context structure for Post-Login trigger
{
  user: {
    id: 'usr_abc123',
    email: '[email protected]',
    emailVerified: true,
    firstName: 'Alice',
    lastName: 'Smith',
    username: 'alice',
    roles: ['editor', 'viewer'],
    metadata: {
      department: 'engineering',
      subscription_tier: 'pro',
    },
    createdAt: '2024-01-15T10:30:00Z',
    lastLoginAt: '2025-02-10T08:15:00Z',
  },
  application: {
    id: 'app_xyz789',
    name: 'Main Web App',
    clientId: 'your-client-id',
    type: 'WEB',
  },
  connection: {
    strategy: 'email-password',  // or 'google', 'github', 'saml', etc.
    name: 'Username-Password-Authentication',
  },
  request: {
    ip: '203.0.113.42',
    userAgent: 'Mozilla/5.0 ...',
    geoip: {
      country: 'IT',
      region: 'Lombardy',
      city: 'Milan',
    },
  },
  tenant: {
    id: 'your-tenant-id',
    name: 'Acme Corp',
  },
}

For Pre-M2M-Token, the user field is absent and instead the context contains application and scopes (the requested M2M scopes).

The Return Value

Every action must return an ActionResult object:

type ActionResult = {
  allow: boolean        // Whether to continue the authentication flow
  message?: string      // Error message shown to the user if allow: false
  claims?: Record<string, unknown>    // Claims to add to the JWT
  metadata?: Record<string, unknown>  // User metadata updates (persisted)
}

If your action throws an unhandled exception, the authentication flow is blocked by default to fail secure. Always wrap logic that might throw in try/catch if you want failures to be non-blocking.

Example Actions

Block login by email domain

// Block logins from emails at a competitor's domain
const blockedDomains = ['competitor.com', 'blockeddomain.org']
const emailDomain = context.user.email.split('@')[1]
 
if (blockedDomains.includes(emailDomain)) {
  return {
    allow: false,
    message: 'Your organization does not have access to this application.',
  }
}
 
return { allow: true }

Add custom claims to the JWT

// Embed department and subscription tier in every token
return {
  allow: true,
  claims: {
    department: context.user.metadata?.department || 'general',
    tier: context.user.metadata?.subscription_tier || 'free',
    org_region: context.user.metadata?.region || 'eu',
  },
}

Role-based claim

// Set a 'plan' claim based on what role the user has
const roles = context.user.roles || []
 
let plan = 'free'
if (roles.includes('enterprise')) plan = 'enterprise'
else if (roles.includes('pro')) plan = 'pro'
else if (roles.includes('starter')) plan = 'starter'
 
return {
  allow: true,
  claims: { plan },
}

Log to an external webhook (fire-and-forget)

// Non-blocking log to an external system
// Use try/catch so a webhook failure doesn't block login
try {
  const payload = JSON.stringify({
    event: 'user.login',
    userId: context.user.id,
    email: context.user.email,
    ip: context.request.ip,
    timestamp: new Date().toISOString(),
  })
 
  // Note: fetch is available in the action sandbox
  fetch('https://your-siem.example.com/events', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer your-key' },
    body: payload,
  })
} catch (e) {
  // Silently ignore webhook failures — do not block login
}
 
return { allow: true }

Block M2M token if scope is not allowed for this application

// Pre-M2M-Token: only allow the 'read:reports' scope for specific applications
const allowedApps = ['app_reporting_service', 'app_analytics']
 
if (context.scopes.includes('read:reports') && !allowedApps.includes(context.application.id)) {
  return {
    allow: false,
    message: 'This application is not authorized to request the read:reports scope.',
  }
}
 
return { allow: true }

Sandboxed Execution Environment

Actions run in a restricted JavaScript sandbox. The following are available:

The following are blocked and will throw an error if used:

Timeout

Actions have a configurable timeout (default: 5000 ms). If execution exceeds the timeout, the action is terminated and the authentication flow is blocked as if allow: false was returned. Set a short timeout for actions that make external HTTP calls to avoid delaying the user’s login experience.

Execution Order

When multiple actions are associated with the same trigger, they execute sequentially in the order shown in the Actions list. If any action returns { allow: false }, execution stops and subsequent actions do not run.

Reordering Actions

On the Actions list page, filter by trigger. Drag the order handle (the six-dot icon) on any action row to change its position. The new order is saved automatically.

Blueprint Editor

For users who prefer a visual approach to defining action logic, Auris provides the Blueprint Editor — an Unreal Engine-style node-based editor for building action rules without writing code.

Access the Blueprint Editor on any action’s detail page by clicking the Blueprint tab.

Node Types

Using the Blueprint Editor

1. The Trigger node is placed automatically at the left
2. Click Add Condition in the toolbar to place a condition node. Connect it to the trigger or a logic gate.
3. Click Add Logic Gate to combine multiple conditions with AND/OR logic
4. Connect condition outputs to action nodes (Deny, Set Claims, etc.)
5. Click Auto-Layout to reorganize nodes automatically
6. Click Save — the blueprint is serialized to JavaScript and saved as the action’s code

The Blueprint Editor and code editor are synchronized. Switching between them shows the code representation of the current blueprint. Code written manually may not always be representable in the Blueprint Editor — complex expressions are preserved as code but not visually editable.

Action Logs

The Logs tab on any action’s detail page shows the execution history for that action.

Click any log entry to expand it and see:

• Full context data passed to the action (with sensitive fields redacted)
• Return value from the action
• Console output (console.log calls from within the action code)
• Error stack trace (if an error occurred)

Filtering Logs

Use the date range picker and status filter at the top of the Logs tab to narrow the view. Logs are retained for 30 days by default.

Related Guides

• Hosted Login Flow — Where Actions fit in the OAuth 2.0 authorization code flow
• Custom Claims — Alternative claim configuration without code (for static/attribute-based claims)
• Actions API — Manage actions programmatically
• Webhook Integration — Outbound webhooks as an alternative for event-driven integrations without code in the auth path