OneLogin Security: Hardening Admin, MFA and App Access

A OneLogin tenant decides who reaches every connected application, so the people, roles and API credentials that administer it deserve the strongest controls in the estate. OneLogin gives customers a clear set of levers for this: delegated administration through privileges, scoped API credentials, user policies that carry MFA requirements, Smart Hooks that can change the login flow, and an Events API for monitoring. This guide explains how those pieces fit together, which settings to configure first, how to log and review them, and how to roll changes out without locking people out. It is written for identity engineers and security teams who run OneLogin in production and want a practical, customer-side hardening baseline.

This is an independent guide from NHI Mgmt Group, based on OneLogin's public documentation as of November 2026. It is not sponsored or reviewed by OneLogin. Product features change, so confirm settings against OneLogin's current documentation.

Key takeaways

• Build admin access from narrow privileges, because OneLogin privileges deny everything by default and grant only the class:Operation actions and resource scopes you list.
• Reserve the wildcard privilege for a very small group, since a statement with "Action": ["*"] and "Scope": ["*"] is what OneLogin itself describes as a Super User privilege.
• Pick the lowest API credential scope that works: Authentication Only, Read Users, Manage users, Read All or Manage All, and treat Manage All credentials as privileged secrets.
• Use user policies and groups to enforce MFA for everyone, starting with administrators, and use the pre-authentication Smart Hook to raise requirements on risk, device or location signals.
• Pull events continuously into your SIEM, using the v2 Events API with cursor pagination, and alert on privilege, credential, policy and hook changes.

How identity and access work in OneLogin

OneLogin is a cloud identity service. Each customer has a tenant reached at <subdomain>.onelogin.com, and the same subdomain is the base for the admin portal and the API. Users sign in once and reach applications through SAML, OpenID Connect and other connectors. Four building blocks shape access:

• Users and groups: people and their group membership. OneLogin's own setup guidance recommends assigning a user security policy through a group, with individual assignment as an exception on the user's Authentication tab.
• Roles: collections that grant application access and can also be the target of privileges, so a role can carry both "what apps you get" and, through a privilege, "what you can administer".
• User policies: the policy attached to a user or group defines how they authenticate, including the MFA tab where factors such as OneLogin Protect are enabled with "OTP Auth Required" and enforcement settings.
• Privileges: JSON statements that grant administrative actions. A privilege grants nothing until it is assigned to a user or a role.

Machine access runs through API credential pairs (client ID and client secret) that use the OAuth 2.0 client_credentials grant against /auth/oauth2/v2/token. OneLogin documents that an access token is valid for 10 hours. Smart Hooks add customer code to the login path. For the general principles of identity provider protection, see the Identity Provider and SSO Security Guide; this page stays with the OneLogin specifics.

Admin roles and privileged access

OneLogin's delegated administration model is built on privileges. Each privilege has a name, an optional description and a privilege object with Version 2018-05-18 and a Statement array. Every statement contains three parts:

• Effect: always "Allow". Everything is denied by default, so a statement only adds permissions.
• Action: strings in the form class:Operation, for example users:List, users:Get, users:Unlock, users:ResetPassword or Users:ForceLogout. OneLogin recommends one class per statement and separate statements for separate classes.
• Scope: resources the actions apply to, in the form class/ID, such as apps/1234, or * for every resource of the class. A roles/{role_id} scope can be paired with user or app actions, which lets you delegate administration of the users in one role.

Action classes documented by OneLogin cover apps, users, roles, reports, events, groups and policies. That gives enough granularity to model real admin jobs instead of handing out full control. The privileges feature requires a OneLogin subscription that includes Delegated Administration.

A practical privilege model

Practical points for the privileged tier:

• Keep the wildcard tier tiny: list every holder of a Super User style privilege by name and review it monthly. Pair it with a documented emergency account, following the Break-Glass Account Guide.
• Assign privileges to roles, not individuals: a role-based assignment makes joiner, mover and leaver changes and access reviews far simpler.
• Give administrators their own policy: attach a user policy to admin groups that requires MFA at every login, using the strongest factor you have deployed. See the Phishing-Resistant MFA Guide for factor selection.
• Separate daily and admin identities where your operating model allows, so privileged sessions are deliberate rather than the default.
• Review delegated scopes: a helpdesk privilege scoped to * on users can reset any password, including other administrators' passwords. Scope it to the roles that helpdesk actually supports.

Integrations, API tokens and service accounts

API credential pairs are the main non-human identity in a OneLogin tenant. OneLogin documents five scopes, from least to most privileged:

Lifecycle facts from OneLogin's documentation that shape how you manage these credentials:

• Creation: an account owner or administrator creates the pair under Developers, API Credentials, gives it a meaningful name and selects a scope. Name each pair after the system and owner that use it.
• Tokens: access tokens from the client_credentials grant are valid for 10 hours. The refresh_token in the response is marked deprecated for this grant, so do not build logic on it.
• Revocation: deleting or disabling a pair revokes the tokens it generated. Disable is reversible and takes effect after a few minutes; delete is permanent and immediate. Use delete when a secret may have been exposed.
• Ownership: credentials are tied to the user who created them, and if that user is deleted the credentials stop working. Create long-lived integration credentials from a managed, documented account and plan the hand-over when people leave.
• Storage: OneLogin advises keeping credentials secure and out of shared code. Store client secrets in a secrets manager and inject them at runtime. See the API Key Management Guide.

For SIEM collection, a Read All pair is enough; a collector rarely needs Manage All. For provisioning, prefer Manage users, which excludes password setting and role assignment. Keep an inventory of every pair with owner, scope, consuming system and last review date. For SCIM-based provisioning design, see the SCIM Provisioning Guide.

Smart Hooks

Smart Hooks are JavaScript functions that OneLogin hosts and runs when a hook fires. They are created through the Smart Hooks API, submitted as base64, and run on a supported Node.js runtime set in the runtime attribute (nodejs18.x in the current documentation). OneLogin documents two hook types:

• pre-authentication: runs after the user enters a username and before the password or MFA prompt. It can return a different policy_id for that login, or return success: false to stop it. Optional context includes a risk score from 0 to 100 with reasons, IP and country, device user agent and registered MFA devices.
• user-migration: runs during authentication to create a user in OneLogin from another source, returning a fully populated user object.

Because a hook can change the policy for a login, it is part of your authentication control plane. Secure it like code that runs in production:

• Secrets in environment variables: OneLogin advises against hard-coding secrets such as API keys and provides hook environment variables (/api/2/hooks/envs, read with process.env). Updating a variable updates every hook linked to it, so name and scope variables carefully.
• Pinned packages: npm packages need exact versions, and the customer is responsible for upgrading them. Track them in your dependency review process.
• Enable only the context you use: risk, location and MFA device context are opt-in. Turning on only what the hook reads keeps the hook simple and its inputs clear.
• Test in a sandbox and roll out by role: OneLogin recommends a developer or sandbox account for building hooks, and hook conditions can restrict a hook to a test role before it applies to everyone.
• Design the hook to raise, not lower, assurance: use it to apply stricter policies on high risk scores, new countries or unmanaged devices, rather than to skip MFA.

Logging and detection

OneLogin exposes tenant activity through the Events API. The v2 endpoint is GET https://<subdomain>.onelogin.com/api/2/events and accepts tokens from Read Users, Manage users, Read All or Manage All credentials. Useful details from the documentation:

• Pagination: limit defaults to 50 with a maximum of 100, and after_cursor walks pages newest first until has_more is false. OneLogin recommends v2 for new integrations.
• Incremental pulls: use since with the newest created_at you have stored, and de-duplicate by event id because since is inclusive. A single query window cannot exceed 365 days.
• Filters for detection: event_type_id, user_id, role_id, app_id, client_id (the API credential), actor_system (for example API or OneLogin), ip and risk_score_min and risk_score_max.
• Hook logs: each Smart Hook has a logs endpoint returning the last 7 days of execution history, including console.log() and console.error() output. Collect these too if hooks matter to your login flow.

Event type IDs come from OneLogin's Get Event Types endpoint; build your detection list from that endpoint in your own tenant rather than hard-coding IDs. Priority detections for a OneLogin tenant:

For building and tuning these detections in a SIEM, see the SIEM Guide and the Identity Threat Hunting Guide.

Metrics that show the baseline is working

• Number of people holding a wildcard (Super User) privilege, with a target of a small fixed number.
• Percentage of administrators covered by an MFA-at-every-login policy (target 100 per cent).
• Number of Manage All API credentials, and the share of credentials with a named owner and a review in the last 90 days.
• Event collection lag: time from event creation to arrival in the SIEM.
• Mean time to review an unapproved privilege or credential change.

Hardening baseline

Roll out in phases. Each phase can be piloted on a test group before it reaches everyone, and each has a simple rollback.

1. Inventory: export administrators, privileges, role assignments, API credential pairs and Smart Hooks. Record owner, scope and purpose for each. No change is made in this phase.
2. Protect administrators: create an admin user policy with MFA required at every login and assign it through an admin group. Pilot with the identity team first. Rollback: reassign the previous policy to the group, while keeping a break-glass account on a separately controlled policy.
3. Right-size privileges: replace broad privileges with persona-based privileges scoped by role or app, and reduce wildcard holders to the agreed few. Rollback: reassign the previous privilege while the narrower one is corrected.
4. Clean up API credentials: reduce each pair to the lowest working scope, move secrets into a vault, and disable (not delete) unknown pairs for a set observation period before deleting them.
5. Extend MFA to all users: assign MFA-enabled policies to user groups in rings, starting with pilot groups. OneLogin prompts users to register their device on first login, so communicate before each ring.
6. Add adaptive controls: deploy a pre-authentication Smart Hook restricted by role conditions to a test group, then widen it. Rollback: remove the condition target or disable the hook.
7. Monitor and review: schedule event collection, alerts and quarterly access reviews of privileges and credentials, using the Access Reviews Guide.

Decision guidance

• Small organisations: two named Super Users plus a break-glass account, one admin policy, MFA for everyone, and a Read All collector feeding a hosted log tool is a sound baseline.
• Large or regulated organisations: persona-based privileges scoped by role, a formal change process for privileges and hooks, separate credentials per integration, and quarterly certification of every privilege assignment.
• Policy versus hook: use user policies for stable, group-wide requirements. Use a pre-authentication hook when the decision depends on per-login context such as risk score, device or country.

Framework mapping

Common misconfigurations

These are customer-side settings that drift over time. Each has a straightforward fix.

• Too many wildcard administrators: a Super User style privilege handed out for convenience. Fix: move people to persona privileges and keep the wildcard for a named few.
• Helpdesk scope set to every user: a reset privilege scoped to * also covers administrators. Fix: scope helpdesk privileges to the roles they support.
• Manage All used for read-only jobs: collectors and reporting tools given full scope. Fix: issue Read All or Read Users pairs and delete the broad pair.
• Credentials owned by a person who leaves: integrations stop when the creating user is deleted. Fix: create integration credentials from a managed account and track ownership.
• Secrets inside hook code: API keys embedded in a Smart Hook function. Fix: move them to hook environment variables and rotate the keys.
• Events left in the tenant: no scheduled collection, so investigations start without history. Fix: run an incremental v2 Events API pull into the SIEM.

Practitioner checklist

• List every privilege, its statements and its assignments; reduce wildcard holders to an agreed small number.
• Assign an admin user policy that requires MFA at every login to all admin groups.
• Scope helpdesk and app-owner privileges with roles/{id} and apps/{id} rather than *.
• Inventory API credential pairs with owner, scope and consumer; move each to the lowest working scope.
• Store client secrets in a secrets manager and delete any pair whose secret may have been exposed.
• Create integration credentials from a managed account so they survive staff changes.
• Keep Smart Hook secrets in environment variables, pin and review npm packages, and test hooks on a role-restricted pilot.
• Collect v2 events and hook logs into the SIEM with alerts on privilege, credential, policy and hook changes.
• Review privileges and credentials quarterly and record the outcome.
• Apply OneLogin product updates and follow OneLogin's published guidance for any connectors and agents you run.

Standards and references

• OneLogin: Working with API Credentials
• OneLogin: Create a Privilege
• OneLogin: Smart Hooks Overview
• OneLogin: Pre-Authentication Smart Hook
• OneLogin: List Events (API v2)
• OneLogin: Generate Tokens
• OneLogin: Add MFA
• NIST: SP 800-53 Rev. 5 Security and Privacy Controls

Related NHI Mgmt Group resources: Identity Provider and SSO Security Guide · Phishing-Resistant MFA Guide · API Key Management Guide · Break-Glass Account Guide · Least Privilege Techniques Guide