> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/get-started/onboarding-to-ox/source-control/gitlab-1/gitlab-identity-provider.md).

# GitLab Identity Provider

Use this connection method to connect GitLab to OX using OAuth authentication. During the connection process, you authenticate to GitLab and grant OX access to the GitLab resources that you want to scan.

### Before you begin

Verify that:

* You have permission to configure connectors in OX.
* You have access to the GitLab projects and groups that you want OX to scan.

### Connect GitLab to OX

1. In OX, go to **Settings > Connections**.
2. Select **GitLab** **>** **Identity Provider**.

<figure><img src="/files/szKzWyCcosIF8fhjVbvP" alt="" width="511"><figcaption></figcaption></figure>

3. In **Connection Name**, enter a name for the connection.
4. Select **Connect**.

> **Note**
>
> When you select **Connect**, GitLab prompts you to authorize OX to access your organization's resources. You must explicitly approve this access to complete the connection.

## GitLab SSO session requirements

When you connect GitLab to OX using the **Identity Provider** authentication method, OX accesses GitLab on behalf of the user who created the connection.

If your organization requires users to authenticate to GitLab through Single Sign-On (SSO), the GitLab session for the connected user must remain valid for OX to access repositories.

### How it works

If GitLab is configured to require SSO through an Identity Provider (IdP):

1. A user connects GitLab to OX using the **Identity Provider** authentication method.
2. OX uses that user's GitLab authorization when accessing repositories.
3. OX can clone repositories only while the user's GitLab SSO session remains valid.

If the GitLab SSO session expires, OX can no longer authenticate to GitLab and repository scans fail until the user signs in to GitLab again.

For example, if your organization configures GitLab SSO sessions to expire every 24 hours, the user who connected GitLab to OX must sign in to GitLab again at least every 24 hours to keep repository scanning working.

> **Important:**
>
> If repository scans unexpectedly stop working after an SSO session expires, have the user who connected the GitLab integration sign in to GitLab again to refresh the SSO session.

### Recommended approach for organizations with short SSO sessions

If your organization enforces short-lived GitLab SSO sessions or frequent reauthentication, OX recommends connecting GitLab using a **Token** created for a dedicated service account instead of using the **Identity Provider** authentication method.

Using a service account token provides more reliable access for automated repository scanning because it does not depend on an individual user's active GitLab SSO session.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.ox.security/get-started/onboarding-to-ox/source-control/gitlab-1/gitlab-identity-provider.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.