# Search System Logs

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

Search your Okta organization's [System Log](https://developer.okta.com/docs/reference/api/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.

> **Note:** This tool is **read-only**. It can search and summarize log events, but it
> cannot modify any Okta configuration, users, or sessions.

## 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

> **Tip:** Results are capped to keep the agent focused and within context limits. When
> the number of returned events equals the requested limit, the response notes
> that more matching events may exist — narrow the time range or filter to see
> them.

## 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](https://www.tryrisotto.com/docs/integrations/idp/okta). What you need depends on **how your Okta connection authenticates**.

### Authentication modes

| Mode                         | What'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).                          |

> **Note:** Both pieces matter for OAuth: the **scope** authorizes the token to request
> log access, and the **admin role** authorizes the action. Granting one without
> the other still results in a permission error.

### 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**

> **Note:** If you connect Okta with a static API token (SSWS) instead of OAuth, skip this
> step — scopes do not apply to API tokens. The token's admin role alone
> determines log access.

### 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](#using-the-tool-in-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.

| Field                          | Required | Description                                                                                                    |
| ------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------- |
| **Okta Domain URL (Optional)** | No       | Your Okta domain (e.g., `https://company.okta.com`). Leave empty to use the organization's Okta configuration. |
| **Okta API Token (Optional)**  | No       | An Okta API token with System Log read access. Leave empty to use the organization's Okta configuration.       |

> **Tip:** Leaving both fields blank reuses the connection you configured in [Settings >
> Integrations > Okta](https://www.tryrisotto.com/docs/integrations/idp/okta), so there's nothing extra to
> rotate or maintain for this tool.

### 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.

| Parameter           | Description                                                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query`             | Keywords 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_expression` | A [SCIM filter expression](https://developer.okta.com/docs/reference/api/system-log/#expression-filter) for structured queries. Can combine with `query`.          |
| `since`             | Lower time bound (ISO 8601, e.g., `2024-01-15T00:00:00Z`). If omitted, Okta defaults to 7 days ago.                                                                |
| `until`             | Upper time bound (ISO 8601, e.g., `2024-01-16T23:59:59Z`). If omitted, Okta defaults to the current time.                                                          |
| `limit`             | Maximum events to return, from 1 to 50. Defaults to 20. More events give more context but use more tokens.                                                         |

> **Note:** At least one of `query` or `filter_expression` must be provided — the tool
> will not return the entire log undirected.

> **Note:** Okta limits a freeform `query` to 10 words. The tool rejects a longer query
> before it calls Okta and tells the agent to shorten it or move structured
> criteria into `filter_expression`. If Okta rejects the request for another
> reason (a malformed filter or timestamp), the tool returns Okta's reason to
> the agent so it can correct the search. Neither case is reported as a
> connection error.

### Useful SCIM filter examples

| Goal                                | Filter expression                   |
| ----------------------------------- | ----------------------------------- |
| Failed login attempts               | `outcome.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 object  | `target.id eq "0oa1234567890"`      |
| MFA factor events                   | `eventType sw "user.mfa"`           |

> **Tip:** Common event types include `user.session.start` (login),
> `user.authentication.auth_via_mfa` (MFA challenge), `user.lifecycle.create` /
> `user.lifecycle.suspend` (lifecycle changes), and
> `application.user_membership.add` (app assignment). See Okta's [event type
> catalog](https://developer.okta.com/docs/reference/api/event-types/) for the
> full list.

## Using the Tool in a Runbook

Tools only run when an agent invokes them as part of a [runbook](https://www.tryrisotto.com/docs/dashboard/runbooks). 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.

> **Tip:** You don't type the ID by hand. Use the tool picker in the runbook editor to
> insert the reference, and the dashboard fills in the correct
> {tool:\<tool-id>} token for you. (Built-in core tools use a named form
> instead, e.g. {tool:core_handle_access}.)

### 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](https://www.tryrisotto.com/docs/integrations/tools/okta/reset_factors) runbook. If you cannot determine the cause, escalate to a human agent.

> **Tip:** Keep instructions directive: tell the agent which filter or time range to use
> for the scenario. A focused query (a specific user, a `FAILURE` filter, a
> narrow time range) returns more relevant events than a broad keyword search.

## 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

| Message                                                                                                                                          | Cause & 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](#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.

## Related

- [Okta IdP Integration](https://www.tryrisotto.com/docs/integrations/idp/okta) — set up the underlying Okta connection and grant scopes/roles
- [Reset User MFA Factors](https://www.tryrisotto.com/docs/integrations/tools/okta/reset_factors) — a complementary Okta tool for MFA recovery
- [Runbooks](https://www.tryrisotto.com/docs/dashboard/runbooks) — how to wire tools into agent workflows
- [Tools](https://www.tryrisotto.com/docs/dashboard/tools) — managing tool instances in the dashboard

## Additional Resources

- [Okta System Log API](https://developer.okta.com/docs/reference/api/system-log/)
- [System Log filter expressions](https://developer.okta.com/docs/reference/api/system-log/#expression-filter)
- [Okta event type catalog](https://developer.okta.com/docs/reference/api/event-types/)
- [Read-only Administrator role](https://help.okta.com/en-us/content/topics/security/administrators-read-only-admin.htm)

Source: https://www.tryrisotto.com/docs/integrations/tools/okta/search_system_logs
