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

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

​

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.