# Onelogin

Connecting OneLogin gives SureCloud read access to your OneLogin tenant's users, roles, applications, authentication policies, and event log. SureCloud monitors MFA factor enrolment at the per-user level, verifies that authentication policies enforce strong factors and are applied to all SSO-protected applications, audits role and group assignments for excessive privilege, and collects OneLogin event log data to provide an audit trail of authentication and administrative activity. This gives continuous evidence that your identity provider is enforcing access controls as required across all connected applications.

{% hint style="info" %}
SureCloud connects to OneLogin using OAuth 2.0 with the client credentials flow. You create an API credential set in the OneLogin developer console and provide the client ID and secret to SureCloud. No user interaction is required after initial setup.
{% endhint %}

## Authentication and setup

{% stepper %}
{% step %}

#### Create an API credential set in OneLogin

In the OneLogin Administration portal, navigate to **Developers → API Credentials → New Credential**.

* **Name**: `SureCloud CCM`
* **Permissions**: **Read All** — this provides read-only access to users, roles, apps, events, and policies without any write capability

Click **Save** and copy the **Client ID** and **Client Secret** immediately. The secret is only displayed once.
{% endstep %}

{% step %}

#### Identify your OneLogin subdomain

Your OneLogin API base URL uses your account subdomain:

`https://{subdomain}.onelogin.com/api/2`

Your subdomain is visible in the URL when you log in to the OneLogin portal (e.g. `https://yourcompany.onelogin.com` → subdomain is `yourcompany`).
{% endstep %}

{% step %}

#### Enter credentials in SureCloud

In SureCloud, navigate to **Integrations → OneLogin → Connect** and provide:

* **OneLogin subdomain**
* **Client ID**
* **Client Secret**

SureCloud exchanges the credentials for a bearer token using the OneLogin token endpoint and refreshes it automatically before expiry.

Click **Test Connection**, then **Save**.
{% endstep %}
{% endstepper %}

## Endpoints

| API Call                            | Use Case                                                                           |
| ----------------------------------- | ---------------------------------------------------------------------------------- |
| `GET /api/2/users`                  | Enumerate all users with their status, MFA enrolled state, and last login date     |
| `GET /api/2/users/{id}`             | Read full user record including role assignments, app access, and factor enrolment |
| `GET /api/2/users/{id}/otp_devices` | Read enrolled MFA devices per user; detect users with no enrolled factor           |
| `GET /api/2/roles`                  | List all roles and their assigned user counts                                      |
| `GET /api/2/roles/{id}/users`       | Enumerate users assigned to each role                                              |
| `GET /api/2/apps`                   | List all SSO applications configured in OneLogin                                   |
| `GET /api/2/apps/{id}/users`        | Read user assignments per application                                              |
| `GET /api/2/policies`               | Enumerate authentication policies and their MFA and session settings               |
| `GET /api/2/events`                 | Retrieve event log entries for authentication and administrative activity          |
| `GET /api/2/groups`                 | List directory groups and their membership                                         |

## Pagination

The OneLogin API uses cursor-based pagination via an `X-After-Cursor` response header. When a response contains more results, the `X-After-Cursor` header is present. SureCloud passes this value as the `after_cursor` query parameter in successive requests until no `X-After-Cursor` header is returned.

```
X-After-Cursor: a1b2c3d4e5f6g7h8i9j0
X-Total-Count: 3842
```

```http
GET /api/2/users?after_cursor=a1b2c3d4e5f6g7h8i9j0&limit=1000
```

SureCloud requests up to 1,000 records per page using the `limit=1000` parameter.

## Required permissions

The **Read All** permission on the API credential set is required for all SureCloud data collection. This grants read access to users, roles, apps, events, policies, and groups without any create, update, or delete capability.

## Polling frequency

| Data type                               | Collection interval |
| --------------------------------------- | ------------------- |
| User inventory and MFA enrolment status | 24 hours            |
| Role and group assignments              | 24 hours            |
| Application access assignments          | 24 hours            |
| Authentication policy configuration     | 24 hours            |
| Event log entries                       | 1 hour              |

## Troubleshooting

<details>

<summary>MFA enrolment status shows as not enrolled for users who have a factor registered</summary>

MFA device enrolment is read via the `/api/2/users/{id}/otp_devices` endpoint. If enrolment data is missing, confirm the API credential set has the **Read All** permission — narrower permission sets may not include OTP device access.

Additionally, confirm OneLogin MFA is enabled for your account in **Security → Authentication → Multi-factor Authentication**.

</details>

<details>

<summary>Event log entries are only returning the last 90 days</summary>

OneLogin retains event log data for 90 days via the Events API. Events older than 90 days are not accessible via the API. SureCloud collects events within a rolling window on each polling cycle — historical events prior to this window cannot be backfilled.

For longer retention, OneLogin supports event log export to a SIEM via the OneLogin SIEM integration or webhooks. Contact SureCloud support if extended log history is required for evidence purposes.

</details>

<details>

<summary>Some applications are not showing user assignments</summary>

Application user assignments are read per-app via `/api/2/apps/{id}/users`. If assignments are missing for specific apps, the app may use a role-based access model rather than direct user assignment — in this case users access the app by virtue of their role, not a direct assignment.

SureCloud collects both direct user assignments and role-based application access. If role-based app access is not appearing, confirm the **Read All** credential permission includes role and app data.

</details>

<details>

<summary>Test Connection fails with "Authentication failed" after a credential regeneration</summary>

When a OneLogin API credential secret is regenerated, the old secret is immediately invalidated. If SureCloud was not updated before the regeneration took effect, all subsequent API calls will return 401.

Update the new **Client Secret** in **SureCloud → Integrations → OneLogin → Edit Connection → Client Secret** immediately after regenerating the credential in OneLogin.

</details>

<a href="https://developers.onelogin.com/api-docs/2/getting-started/overview" class="button secondary">OneLogin API v2 reference</a>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/onelogin.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.