OneLogin Enterprise Implementation Guide: SSO, MFA, and Directory Integration

Overview

OneLogin is an Identity and Access Management platform used to provide single sign-on (SSO), multi-factor authentication (MFA), directory integration, and user lifecycle automation across SaaS, on-premises, and custom applications. Enterprises adopt OneLogin to reduce password sprawl, enforce consistent authentication policies, and integrate identity controls with HR, Active Directory, LDAP, and cloud services.

Its core value is centralized policy enforcement. Administrators can connect authoritative identity sources, map users into roles, publish applications with SAML or OIDC, and apply adaptive MFA based on user, device, network, or risk context. In mature environments, OneLogin becomes a control plane for identity-driven access governance.

Architecture

Core components

• OneLogin cloud tenant: hosts directories, apps, policies, MFA settings, and audit logs.
• Directory connectors: synchronize identities from Active Directory or LDAP.
• Applications: SAML 2.0, OpenID Connect, WS-Federation, or password vault integrations.
• Authentication policies: define password, MFA, trusted networks, and risk-based controls.
• Provisioning engine: supports SCIM and app-specific provisioning for create, update, suspend, and deprovision workflows.
• API access: administrative automation via OAuth 2.0 client credentials.

Deployment models

• Cloud-first: OneLogin as primary IdP for SaaS and federated apps.
• Hybrid enterprise: OneLogin integrated with on-prem AD through OneLogin Desktop or directory connectors.
• Multi-directory: multiple AD forests or LDAP domains mapped to business units.

Data flow

1. A user authenticates to OneLogin using AD-backed credentials, cloud directory credentials, or delegated auth.
2. OneLogin evaluates policy, device posture, IP restrictions, and MFA requirements.
3. After successful authentication, OneLogin issues a SAML assertion or OIDC token to the target application.
4. Provisioning events are triggered through SCIM or app connectors based on role membership.
5. Audit events are written to tenant logs and can be exported to SIEM.

Implementation Guide

1. Create API credentials

In OneLogin, create an API credential with permissions for users, roles, apps, and events. Export values securely.

export ONELOGIN_CLIENT_ID="ol_client_id"
export ONELOGIN_CLIENT_SECRET="ol_client_secret"
export ONELOGIN_REGION="us"
TOKEN=$(curl -s -X POST "https://api.${ONELOGIN_REGION}.onelogin.com/auth/oauth2/v2/token" -H "Content-Type: application/json" -d '{"grant_type":"client_credentials"}' -u "$ONELOGIN_CLIENT_ID:$ONELOGIN_CLIENT_SECRET" | jq -r '.access_token')
echo $TOKEN

2. Configure directory integration

Install the OneLogin AD Connector on a domain-joined Windows Server and restrict outbound access to OneLogin endpoints over TCP 443. Scope synchronization to required OUs only and map immutable identifiers such as objectGUID.

3. Create a SAML application

Define ACS URL, audience, NameID, and attribute mappings. Example attributes typically include email, firstname, lastname, groups, and department.

4. Assign roles and policies

Create roles such as Finance-SSO, Engineering-Admins, and Contractors-MFA. Bind apps to roles and attach MFA policies requiring WebAuthn or OneLogin Protect for privileged users.

5. Test authentication and provisioning

Validate SP-initiated and IdP-initiated login, then test JIT or SCIM provisioning. Confirm deprovisioning on user disablement.

6. Export logs to SIEM

Use the Events API or supported log streaming integration to forward authentication, admin, and provisioning events.

Code Examples

Example 1: Get OneLogin OAuth token

curl -s -X POST "https://api.us.onelogin.com/auth/oauth2/v2/token" -H "Content-Type: application/json" -u "${ONELOGIN_CLIENT_ID}:${ONELOGIN_CLIENT_SECRET}" -d '{"grant_type":"client_credentials"}'

Example 2: SCIM provisioning mapping

scim:
  base_url: "https://scim.example.com/v2"
  auth:
    type: bearer
    token: "${SCIM_BEARER_TOKEN}"
  mappings:
    userName: email
    active: status
    name.givenName: firstname
    name.familyName: lastname
    externalId: samaccountname
    emails:
      - primary: true
        value: email

Example 3: List recent OneLogin events with Python

import os
import requests
headers = {"Authorization": f"bearer:{os.environ['TOKEN']}", "Content-Type": "application/json"}
resp = requests.get("https://api.us.onelogin.com/api/2/events?limit=5", headers=headers, timeout=30)
resp.raise_for_status()
for event in resp.json().get("data", []):
    print(event.get("created_at"), event.get("event_type_id"), event.get("actor_system"))

Security Hardening

• Enforce phishing-resistant MFA for admins and high-risk groups using WebAuthn/FIDO2 where supported.
• Disable legacy protocols and avoid password vault mode when federation is available.
• Restrict admin access by trusted networks, device trust, and step-up authentication.
• Rotate API credentials regularly and store them in a vault such as HashiCorp Vault or AWS Secrets Manager.
• Minimize directory sync scope to required OUs and attributes.
• Validate SAML signing certificates and monitor expiration dates.
• Export audit logs to SIEM and alert on admin role changes, MFA bypass, and repeated failed logins.
• Use least privilege for app admins; separate directory administration from app assignment administration.

Comparison

Troubleshooting

Error 1: Invalid SAML audience

Log sample:

[2026-04-11 09:14:22,881] ERROR saml.validation AudienceRestriction validation failed. expected="https://app.example.com/saml/metadata" received="https://app.example.com/sso"

Fix: Ensure the OneLogin Audience exactly matches the SP entity ID configured in the application.

Error 2: OAuth token authentication failure

Log sample:

{"status":{"type":"Unauthorized","code":401,"message":"Invalid client credentials"}}

Fix: Recreate the API credential, verify region-specific API endpoint, and confirm the client secret is not truncated by shell quoting.

Error 3: AD connector sync failure

Log sample:

2026-04-11 10:02:47 ERROR DirectorySync LdapException: The server is not operational
2026-04-11 10:02:47 WARN DirectorySync Retry scheduled in 300 seconds

Fix: Validate DNS resolution, LDAPS connectivity, service account permissions, and firewall egress to both domain controllers and OneLogin.

Best Practices

Do

• Use role-based app assignment tied to HR or AD groups.
• Standardize on SAML or OIDC instead of stored passwords.
• Pilot MFA policies with IT and privileged users before broad rollout.
• Send OneLogin events to SIEM and correlate with endpoint and VPN telemetry.

Don't

• Do not assign apps directly to individual users unless there is a documented exception.
• Do not sync entire directories when only a subset of users needs access.
• Do not leave break-glass accounts without compensating controls such as vaulting and monitoring.
• Do not allow long-lived API credentials without rotation and usage review.

A practical enterprise pattern is to source identities from AD, map departments to OneLogin roles, federate to SaaS with SAML, provision with SCIM, and require phishing-resistant MFA for all administrative paths.