Skip to main content

Using the OAuth Analyst Agent

How to turn on the OAuth Analyst Agent, configure what it does with each verdict, and act on what it finds.

Written by Velizar Demirev

What the OAuth Analyst Agent does

Every time someone connects a third-party app to Google Workspace or Microsoft 365, that app gets a set of permissions. Some are harmless. Some can read every message in a mailbox. Reviewing each one by hand doesn't scale, so risky grants tend to sit active for days or weeks.

The OAuth Analyst Agent reviews new integration grants for you. Within minutes of discovery, it evaluates the requested scopes alongside app reputation, vendor security posture, scope sensitivity, and user context, then produces a verdict with reasoning you can read and check. You decide how much the agent does on its own and how much comes to you.

What's in scope: OAuth integration grants authorized through Google Workspace and Microsoft Entra ID. Login-only grants ("Sign in with Google") and grants authorized through other identity providers aren't analyzed.


Turn on the agent

The agent is off by default. Nothing is analyzed until you enable it.

Go to the Automations > Agents in the left nav and find the OAuth Analyst Agent card. There you can enable the agent toggle.

From that point, every newly detected grant is queued for analysis, and analysis starts within five minutes of detection under normal load. Turning the agent back off stops new analyses — it doesn't undo actions already taken.


Start in Observe mode

If you're turning the agent on for the first time, start here. Observe mode is a single toggle that lets you watch the agent work before it touches anything.

With Observe mode on, the agent analyzes grants and logs verdicts exactly as it normally would, but the effective action for every verdict becomes Automatically permit. Nothing is revoked. Nothing is queued for review. No employee gets nudged.

A few things worth knowing:

  • Observe mode locks your per-verdict settings so you can't accidentally configure something that fires the moment you switch it off.

  • It never overwrites those settings. Uncheck the box and they return to whatever you had configured.


The three verdicts

Every analysis ends in exactly one verdict, with human-readable reasoning attached: which permissions were flagged, why, and what evidence the agent used.

Verdict

What it means

Default response

Permit

The grant looks safe.

Marked reviewed. No action needed from you.

Justify

The risk depends on how the app is actually used, and only the employee can tell you that.

The granting employee is nudged for justification, then the grant comes to you.

Revoke

The grant looks dangerous.

You're nudged to approve or reject the revocation. Nothing is revoked without your say-so.


Review a grant that needs your decision

When a grant routes to you, you get a nudge with the grant details, the agent's reasoning, and three ways to respond:

  • Approve the revocation. The grant is revoked, the employee is notified, and the outcome is recorded.

  • Reject the revocation. The grant stays active and is marked as analyzed. Your override is recorded, and the agent learns from it.

  • Nudge the user. Ask the employee for context before you decide. This starts the justification flow described below.

You always have the final word. The agent never locks you out of a decision, and you can revoke a grant it permitted or keep one it wanted gone.

Choose who gets these nudges in the OAuth grant risk agent configuration section. Only users with the Administrator role, or Organization View with offboarding, are eligible.


Ask the employee for context

Not every risky grant is a bad one. When the risk depends on how someone actually uses an app, the missing information lives with the person who authorized it.

The justification flow asks them. It starts either automatically from a Justify verdict, or when you select Nudge user on a grant awaiting your decision. Both paths behave the same way.

What the employee sees

An email/Slack/Teams nudge that names the app, names the permissions driving the risk, explains what they're being asked to clarify, and gives them a text box to answer in. No security jargon, no ticket to file.

What you get back

  • They respond. The grant comes to you with their justification presented next to the original analysis. The agent doesn't re-analyze the grant — the judgement is yours.

  • They don't respond. After the response timeout (24 hours by default), the grant escalates to you flagged "User unresponsive to justification nudge." You're never left waiting indefinitely.

  • They can't be reached. If the employee is deactivated or offboarded, or the nudge can't be delivered, the grant escalates immediately with the reason attached instead of waiting out the timeout.

You can run the flow again on the same grant, after an unanswered first request, or when a justification doesn't tell you enough. Each run is recorded separately with whoever started it. A response that arrives after escalation gets attached to the grant and logged, but the decision stays with you.

If you'd rather never involve employees, turn off User justification nudges. Justify verdicts then route straight to you, flagged as unjustified.


Track what the agent has done

Select View all activity to open the OAuth grant activity table — one row per analyzed grant, showing the integration and source identity provider, the requesting user, risk, outcome, who allowed it, and the date. Sort, search, and filter by risk, user, app, outcome, or date range.

Select a row to open the grant detail, which shows:

  • The agent's analysis summary and the reasoning behind the verdict

  • A step-by-step timeline: discovery, analysis started and completed with its recommendation, every nudge and its response status, your review, and the final resolution with the name of whoever — or whatever — acted

  • A link to the underlying OAuth grant record

Grants still in flight show the timeline up to the current step with a pending state, so you can always see where something is waiting.


Tell the agent when it's wrong

Mark any verdict correct or incorrect, with an optional note, from the verdict detail when a grant comes to you for review. Your overrides count too — rejecting a recommended revocation, or revoking a grant the agent permitted, is captured automatically as feedback. All of it is stored with the analysis and used to tune verdict quality.


If analysis of a grant fails

If an analysis errors out or the agent can't reach a confident verdict, the grant is flagged for manual review and you're nudged. No grant ever silently skips review.


A recommended rollout

  1. Enable the agent with Observe mode on. Let it run for a week or two. Nothing is acted on.

  2. Read the activity table. Compare the shadow actions against what you would have decided yourself. Review the verdicts you disagree with.

  3. Turn Observe mode off and keep the defaults. Safe grants clear themselves, unclear ones go to the employee first, and dangerous ones wait for you.

Did this answer your question?