Docs

Integrations / Identity / Okta

Search System Logs

Search Okta System Log events for security, authentication, and audit investigations

Search your Okta organization's System Log for security, authentication, and audit events. This gives the Risotto agent read-only visibility into what happened in Okta — logins, MFA challenges, user lifecycle changes, admin actions, and suspicious activity — so it can investigate and answer questions directly from the source of truth.

Overview

The Okta Search System Logs tool lets an agent query the Okta System Log API and return a structured, summarized set of matching events. It is useful for:

  • Login troubleshooting: Investigate why a user can't sign in (failed logins, locked accounts, rate limits)
  • MFA investigations: See factor enrollments, challenges, and failures for a user
  • Security review: Surface suspicious sign-ins, threats, or sign-ins from unexpected locations
  • Audit lookups: Confirm when a user was created, suspended, deprovisioned, or added to a group
  • Admin-action tracing: Find configuration or policy changes and who made them

How It Works

When invoked, the tool calls the Okta System Log API (GET /api/v1/logs) with the search criteria you (or the agent) provide and returns a summary of matching events. Specifically, it:

  1. Builds a query from the supplied keywords, SCIM filter, and time range
  2. Requests events sorted most-recent-first (descending)
  3. Extracts the most relevant fields from each event — timestamp, event type, actor, target(s), outcome, client context (IP, user agent, location), and threat/security context for flagged events
  4. Returns the events as structured JSON for the agent to reason over

Prerequisites

This tool talks to Okta through Risotto's existing Okta connection by default, so most of the setup is shared with the Okta IdP integration. What you need depends on how your Okta connection authenticates.

Authentication modes

ModeWhat's required to read System Log
OAuth (API Services app)The app must be granted the okta.logs.read scope and assigned an admin role that can read the System Log (Read-only Administrator or higher).
API token (SSWS)Scopes don't apply. The token's user must have an admin role that can read the System Log (Read-only Administrator or higher).

Minimum admin role

Read-only Administrator is sufficient to read the System Log. Higher roles (Org Administrator, Super Administrator) also work but are not required for this tool.

Step-by-Step Setup

Step 1: Grant the okta.logs.read scope (OAuth only)

If your Okta connection uses an API Services app (OAuth), a Super Administrator must grant the new scope:

  1. In the Okta Admin Console, open Applications > Applications and select your Risotto API Services app
  2. Go to the Okta API Scopes tab
  3. Find okta.logs.read and click Grant

Step 2: Confirm the admin role can read the System Log

  1. On the same API Services app (OAuth) — or for the user who owns the API token (SSWS) — open the Admin roles tab / the user's admin assignments
  2. Confirm a role with System Log read access is assigned (Read-only Administrator is the minimum)

Step 3: Add the tool in Risotto

  1. In the Risotto dashboard, select Tools in the sidebar
  2. In the Tool groups list, select Okta
  3. Find Okta Search System Logs and click Enable
  4. Optionally, open the tool, click Edit, and configure it (see below)
  5. Reference the tool from a runbook

Configuration Options

Tool configuration (Risotto dashboard)

Both fields are optional. Leave them blank to use your organization's existing Okta connection — this is the recommended setup. Only fill them in if you want this tool to authenticate against a different Okta instance or with dedicated credentials.

FieldRequiredDescription
Okta Domain URL (Optional)NoYour Okta domain (e.g., https://company.okta.com). Leave empty to use the organization's Okta configuration.
Okta API Token (Optional)NoAn Okta API token with System Log read access. Leave empty to use the organization's Okta configuration.

Search parameters (set by the agent at runtime)

When the agent uses this tool, it can supply the following parameters. You don't set these in the dashboard — they're chosen per request, though your runbook instructions can guide how the agent uses them.

ParameterDescription
queryKeywords to search for (case-insensitive), at most 10 words. Matches across event type, actor, target, and other fields. Leave empty if using filter_expression.
filter_expressionA SCIM filter expression for structured queries. Can combine with query.
sinceLower time bound (ISO 8601, e.g., 2024-01-15T00:00:00Z). If omitted, Okta defaults to 7 days ago.
untilUpper time bound (ISO 8601, e.g., 2024-01-16T23:59:59Z). If omitted, Okta defaults to the current time.
limitMaximum events to return, from 1 to 50. Defaults to 20. More events give more context but use more tokens.

Useful SCIM filter examples

GoalFilter expression
Failed login attemptsoutcome.result eq "FAILURE"
All session starts (logins)eventType eq "user.session.start"
Events for a specific actor (by ID)actor.id eq "00u1234567890"
Events targeting a specific objecttarget.id eq "0oa1234567890"
MFA factor eventseventType sw "user.mfa"

Using the Tool in a Runbook

Tools only run when an agent invokes them as part of a runbook. Reference the tool from your runbook instructions with a {tool:<tool-id>} token, where <tool-id> is the unique ID of your configured tool instance.

Example runbook

Title: Investigate Okta login problems

When (Conditions):

A user reports they cannot log in to Okta or a connected application, or asks why they were locked out or repeatedly prompted for MFA.

Then (Instructions):

  1. Use the {tool:<tool-id>} tool to look up recent events for the requestor. Search by their email with query set to their address, and set filter_expression to outcome.result eq "FAILURE" to focus on failures.
  2. Review the returned events for failed logins, MFA challenges, account lockouts, or sign-ins from unexpected locations or IP addresses.
  3. Use {tool:core_leave_internal_comment} to post the log details for the support team: the events, the policy or rule, the device, and the IP address.
  4. Tell the user in plain language when the failures happened and the likely cause (wrong password, MFA failure, lockout). Do not name any policy, rule, group, device ID, IP address, or log event.
  5. If the cause is a lost or broken MFA device, hand off to the Reset User MFA Factors runbook. If you cannot determine the cause, escalate to a human agent.

Response Format

On a successful search, the tool returns a count, a summary of the search criteria, and the matching events as structured JSON. Each event includes:

  • published — event timestamp
  • eventType and displayMessage — what happened
  • actor — who performed the action (type, display name, email)
  • targets — what was affected
  • outcome — result (SUCCESS / FAILURE) and reason
  • client — IP address, user agent, and geographic location (when available)
  • securityContext — threat flag and level (only for flagged events)
  • debugDetails — error codes and request details (when present)

The tool returns only these fields. securityContext comes back only for events that Okta flags as a threat, and then holds only the threat flag and level. Its isp, asOrg, isProxy, and domain fields are not returned. debugDetails holds only the reason, errorCode, errorSummary, and requestUri keys of Okta's debugContext.debugData. Other debugData keys, authenticationContext, and transaction are not returned. No tool setting adds fields.

When the number of events returned equals the requested limit, the response notes that more matching events may exist.

Error Messages

MessageCause & resolution
Failed to search Okta system logs: at least one of 'query' or 'filter_expression' must be provided.The search ran with no criteria. Provide a keyword query or a SCIM filter.
Failed to connect to Okta. Check the tool configuration.Risotto couldn't build an Okta client. Verify the Okta connection (or the tool's optional URL/token) is valid.
Received unexpected response format from Okta.Okta returned something other than a list of events. Usually transient — retry; if it persists, check the Okta domain URL.
No Okta system log events found matching ...The search succeeded but matched nothing. Broaden the keywords, relax the filter, or widen the time range.
Failed to search Okta system logs: the 'query' parameter has N words, but Okta allows at most 10 words in a freeform search.The keyword query is too long. Shorten it to the most distinctive keywords, or move structured criteria into filter_expression.
Failed to search Okta system logs: Okta rejected the search parameters (...)Okta returned a validation error (400) for the query, filter, or time bounds. Correct the value named in the message and retry.
Failed to search Okta system logs: Okta denied access to the system logs. The configured Okta credentials lack permission to read system logs.Okta returned 403. See Troubleshooting below.
Failed to search Okta system logs due to an API error.Another Okta API error. Retry. If it continues, check the Okta connection.

Troubleshooting

"Okta denied access to the system logs" (permission denied)

This is the most common setup issue. Okta returns a 403 when the request isn't authorized to read the System Log. The tool cannot tell which grant is missing. Check both of these:

  1. OAuth connections: the okta.logs.read scope is granted on the Risotto API Services app (a Super Administrator must do this).
  2. Both connection types: the admin role (app role for OAuth, token user's role for SSWS) includes System Log read access — Read-only Administrator at minimum.

After granting the scope, allow a short delay for the new token to pick it up — Risotto caches Okta tokens for up to ~1 hour, but they refresh automatically on expiry.

No events found for a user you expect to see

  • Confirm you're searching the right identifier — try the user's email as the query.
  • Widen the time range with since — by default Okta only looks back 7 days.
  • Remember the System Log retains events for a limited window (Okta's standard retention is 90 days).

Results seem truncated

The tool returns at most 50 events (default 20) to stay within the agent's context. If the response says more events may exist, narrow the search with a tighter filter_expression or a smaller time window rather than raising the limit.

Security Considerations

  • Read-only by design. This tool can only search logs; it cannot change Okta state.
  • Least privilege. Read-only Administrator plus okta.logs.read is all this tool needs — don't over-grant the connection for log search alone.
  • Sensitive data in logs. System Log events can contain IP addresses, locations, and identifiers. Event summaries are passed to the agent to answer the request and are subject to the same encryption and handling as other ticket data.
  • What the requestor sees. The tool gives the agent the full events, including targets, outcome reasons, IP addresses, and locations. The agent has no built-in rule that hides these details from the requestor. To keep policy names and other internal details private, tell the runbook to post them with leave_internal_comment and to give the requestor only the outcome, as in the example runbook. The requestor never sees an internal comment.
  • Auditability. Reads against the System Log API are themselves recorded in Okta, preserving a trail of automated access.

Additional Resources

Something wrong or missing? Report an issue · View as Markdown