> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OneLogin

*This article covers the OneLogin API integration (syncing and managing users, roles, and app assignments). A separate optional setup, putting Lumos itself behind OneLogin SAML SSO, is described at the end of the Instructions.*

## After this article

You will be able to connect OneLogin to Lumos to sync users, groups, roles, app assignments, and last-login activity. You can also suspend, delete, downgrade, and manage role-based app access during offboarding and Access Reviews.

## Capabilities

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users | Account | Yes | Yes | All user profiles and attributes. Create/update account and send invite link supported |
| Groups | Permission | Yes | No | Group membership metadata |
| Roles | Permission | Yes | Yes | Role definitions. Lumos can assign/remove role membership (single-app roles only) |
| Last Activity | Account | Yes | No | `last_login`, OneLogin's only available activity metric |

| Deprovisioning Action | Type | Description |
| - | - | - |
| Suspend (Deactivate) | User | Locks the account and logs the user out. Does **not** reclaim a license |
| Downgrade | User | Sets the user's state to Unlicensed. Reclaims a license |
| Delete | User | Permanently deletes the OneLogin user |
| Remove Role Access | Permission | Removes a role assignment, only if the user's app access came from that role |
| Remove Direct App Access | App Access | **Not supported**. OneLogin provides no API for removing direct app assignments |

**Create/update fields:** Email, Username, First Name, Last Name, Title, Department, Company, Phone, Comment, State, Status, SAM Account Name (linked directory), and Custom Attributes. A custom attribute configured in Lumos that does not exist in OneLogin causes the create/update action to fail.

**Status mapping (accounts):** Active/Password expired/Awaiting password reset with state Approved → Active. Suspended or Locked (any state) → Suspended. Those same statuses with any non-Approved state → Suspended. Unknown → Access created. Deleted (no longer returned) → Deprovisioned. When OneLogin is the User Source, employment status maps: Unactivated → Inactive. Active/Password expired/Awaiting password reset → Active. Suspended/Locked → Suspended. Password Pending/Security questions required → Staged. Deleted → Deprovisioned.

**Managed app assignments:** Lumos surfaces all applications managed in OneLogin and their assigned users. Per-app account status comes from the assignment's `provisioning_state` (Provisioned → Active, Provisioned Pending Approval → Staged, Deleted/Disabled → Deprovisioned, Unknown → Access Created). A blank group value on an app assignment means the user is directly assigned rather than via a role.

**Role-based assignment limits:** Lumos cannot assign a user directly to an application, only to a OneLogin Role that grants the app (OneLogin API limitation), and only when the role grants access to a **single** application. Multi-app roles are not attempted and the request is marked failed in the Activity Log. Role unassignment is not available in Inactivity Workflows.

## Required plan and roles

* **OneLogin role:** an **administrator** must create the API credential in OneLogin.
* **Credential scope:** `Manage All` (required). Lumos needs it to read users, groups, roles, and apps, and to perform write actions (suspend, delete, role assignment changes). There is no read-only variant of this connector.
* **Region:** know whether your OneLogin tenant is in the **US** or **EU** region.

## Read-only access vs provisioning

**Is read-only possible?** No. The credential scope is `Manage All`, and the article states plainly there is no read-only variant of this connector, since Lumos needs that scope both to read users, groups, roles, and apps and to perform write actions (suspend, delete, role assignment changes).

**What full provisioning requires.** An administrator-created API credential with the `Manage All` scope, plus your OneLogin region (US or EU), entered as the Client ID and Client Secret described below.

**Watch out for.** OneLogin has no API for removing direct app assignments, only role-based access, so some deprovisioning steps aren't available regardless of credential. Role assignment and removal only work when a role grants access to a single application. If you use Active Directory or LDAP mappings, upstream directory sync can silently revert role or attribute changes Lumos makes.

## Instructions

**Phase 1: Generate API credentials in OneLogin**

1. Log in at [app.onelogin.com/login](https://app.onelogin.com/login) as an administrator.
2. Go to **Developers → API Credentials**.
3. Click **New Credential**, name it (e.g. `Lumos`), and select the **Manage All** scope.
4. Click **Save**, then copy the **Client ID** and **Client Secret**.

**Phase 2: Connect in Lumos**

1. In Lumos, go to **Settings → Integrations → OneLogin** (reconnect an existing card or add a new one).
2. Choose a unique **App Instance Identifier** (e.g. `onelogin-1`, `lumos-onelogin-prod`). This lets you connect multiple OneLogin tenants.
3. Enter the **Client ID** and **Client Secret**.
4. Select your **Region** (US or EU).
5. Click **Connect**.

**Optional: Put Lumos behind OneLogin SAML SSO**

This separate setup restricts who can log in to Lumos itself via OneLogin SAML.

1. Contact Lumos support (Slack or [support@lumos.com](mailto:support@lumos.com)) to obtain the ACS URL for your OneLogin custom SAML app.
2. In the OneLogin admin dashboard, select **Applications** and create a custom SAML application for Lumos.
3. Configure the SAML app fields:
   * **ACS URL Validator:** build a regex from the ACS URL Lumos provided, in the format `^https:\/\/auth\.workos\.com\/sso\/saml\/acs\/<alphanumeric-string>$`, keeping the trailing `$`.
   * **ACS URL:** the URL provided by Lumos in step 1.
   * **Login URL:** `https://app.lumosidentity.com/login`
   * **SAML Initiator:** Service Provider.
   * **SAML Signature Element:** Assertion.
4. Configure attribute mappings, checking **Include in SAML assertion** for each: `email` → Email, `firstName` → First Name, `id` → UUID (Name Format UUID), `lastName` → Last Name.
5. From the app's **SSO** tab, open the **More Actions** dropdown, click **SAML Metadata** to download the XML metadata file, and send it to Lumos support.
6. Assign users to the application in OneLogin.
7. After Lumos support confirms the setup, verify you can log in from the OneLogin tile or the Lumos login page.

## API Endpoints Used

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## Troubleshooting

**Role or user updates keep reverting.** If you use Active Directory or LDAP mappings, upstream directory sync processes can overwrite changes Lumos makes to roles or user attributes.

**Create/update account fails.** Check for a custom attribute configured in Lumos that does not exist in OneLogin. Every custom attribute mapped in Lumos must already be defined in OneLogin.

**Role assignment or removal marked failed in the Activity Log.** The target role grants access to multiple applications. Lumos can only assign/unassign roles that grant a single application. Split the role in OneLogin or manage that access natively.

**Can't remove a user's app access.** If the user is directly assigned to the app (blank group value), removal is not possible: OneLogin has no API for removing direct app assignments. Only role-based access can be removed via Lumos.

**License not reclaimed after deactivation.** Suspend/Deactivate locks the account but does not reclaim a license. Use the **Downgrade** action (state → Unlicensed) to reclaim it.

**Authentication errors after connecting.** Confirm the credential was created with the **Manage All** scope, the Client ID/Secret were copied fully, and the **Region** in Lumos matches your OneLogin tenant (US vs EU).

**No OneLogin removal step is offered when building an offboarding workflow for a custom or manually managed app.** When you add a step to a deprovisioning workflow for one of those apps, the OneLogin actions listed are provisioning actions only (Activate Account, Create Account, Send Invite Link, Update Account). There is currently no selectable OneLogin deprovision or unassign action, so nothing is hidden from you. To automate access removal on offboarding for these apps, add a **Manual Deprovisioning** task routed to the app admin, a **Deprovisioning Webhook**, or a **Remove From Group** step, depending on how access to the app is granted. If access is governed by a OneLogin group or role, removing the group membership is usually the cleanest interim path. Note that an app with no deprovisioning steps configured is excluded from offboarding altogether.

**An Access Review still reflects an old manual CSV upload after the app was switched to OneLogin.** A manual or CSV data source cannot be detached or deleted from an app once it has been added. To clear the stale accounts, first download the current account table as a backup. Then upload a CSV that contains only the header row (Email, or First Name plus Last Name) with no data rows. This marks the previously uploaded manual accounts as Deprovisioned and leaves the OneLogin-synced accounts untouched, and it refreshes the upload timestamp so the **Outdated Data** warning clears. Finally, open the Access Review and click **Sync Data** so the snapshot pulls the current OneLogin accounts and group membership. The record that a manual source was once added to the app remains, which is expected.