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

# SSO and LDAP

> Single Sign-On and LDAP integration for self-hosted CVAT

CVAT Enterprise supports Single Sign-On (SSO) and LDAP integration for centralized authentication. These features are available in the Enterprise edition.

## Single Sign-On (SSO)

CVAT supports SSO using both OpenID Connect (OIDC) and Security Assertion Markup Language (SAML) protocols.

### Supported Identity Providers

* Microsoft Azure (OIDC and SAML)
* Okta (OIDC and SAML)
* Auth0 (OIDC and SAML)
* Keycloak (OIDC and SAML)
* Any OIDC or SAML compliant provider

### Configuration Overview

To configure SSO:

1. Configure your Identity Provider (IdP) application
2. Create an SSO configuration file (`auth_config.yml`)
3. Set environment variables
4. Start or restart CVAT

### SSO Configuration File

Create an `auth_config.yml` file with your SSO settings:

#### OpenID Connect Example

```yaml theme={null}
sso:
  enabled: true
  selection_mode: email_address
  enable_pkce: false
  identity_providers:
    - id: company-oidc
      protocol: OIDC
      name: Company SSO
      server_url: https://login.company.com/
      client_id: cvat-client-id
      client_secret: your-client-secret
      email_domain: company.com
      token_auth_method: client_secret_post  # Optional
```

#### SAML Example

```yaml theme={null}
sso:
  enabled: true
  selection_mode: email_address
  identity_providers:
    - id: company-saml
      protocol: SAML
      name: Company SAML
      entity_id: https://sso.company.com
      metadata_url: https://sso.company.com/saml/metadata
      
      attribute_mapping:
        uid: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
        username: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
        email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
        first_name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
        last_name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
        email_verified: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailverified
      
      email_domain: company.com
      weight: 1
```

### SSO Settings Reference

| Setting          | Description                                                                               |
| ---------------- | ----------------------------------------------------------------------------------------- |
| `enabled`        | Enable or disable SSO functionality                                                       |
| `selection_mode` | How to select IdP: `email_address` (by email domain) or `lowest_weight` (by weight value) |
| `enable_pkce`    | Enable Proof Key for Code Exchange for OIDC (default: false)                              |

### Identity Provider Configuration

#### Required Fields

| Field      | Description                                                    |
| ---------- | -------------------------------------------------------------- |
| `id`       | Unique URL-safe identifier for the IdP (used in callback URLs) |
| `name`     | Human-readable name displayed to users                         |
| `protocol` | Authentication protocol: `OIDC` or `SAML`                      |

#### Optional Fields

| Field          | Description                                                      |
| -------------- | ---------------------------------------------------------------- |
| `email_domain` | Company email domain (for `email_address` selection mode)        |
| `weight`       | Priority value (for `lowest_weight` selection mode, default: 10) |

#### OIDC-Specific Fields

| Field               | Required | Description                                                                   |
| ------------------- | -------- | ----------------------------------------------------------------------------- |
| `client_id`         | Yes      | OAuth client ID from IdP                                                      |
| `client_secret`     | Yes      | OAuth client secret from IdP                                                  |
| `server_url`        | Yes      | OIDC discovery URL (should have `/.well-known/openid-configuration` endpoint) |
| `token_auth_method` | No       | Token authentication method: `client_secret_basic` or `client_secret_post`    |

#### SAML-Specific Fields

| Field               | Required | Description                     |
| ------------------- | -------- | ------------------------------- |
| `entity_id`         | Yes      | IdP entity ID                   |
| `metadata_url`      | No\*     | SAML metadata URL               |
| `x509_cert`         | No\*     | SAML X.509 certificate          |
| `sso_url`           | No\*     | SAML Single Sign-On service URL |
| `attribute_mapping` | Yes      | Mapping of user attributes      |

\*Either `metadata_url` OR both `x509_cert` and `sso_url` are required.

### Callback URLs

When configuring your IdP, use these callback URL patterns:

**OIDC Redirect URI:**

```
https://your-cvat-domain.com/api/auth/oidc/<idp-id>/login/callback/
```

**SAML Assertion Consumer Service (ACS) URL:**

```
https://your-cvat-domain.com/api/auth/saml/<idp-id>/acs/
```

**SAML Entity ID/Metadata URL:**

```
https://your-cvat-domain.com/api/auth/saml/<idp-id>/metadata/
```

Replace `<idp-id>` with your identity provider's `id` from the configuration file.

### Environment Variables

Set these environment variables before starting CVAT:

```bash theme={null}
export AUTH_CONFIG_PATH="/path/to/auth_config.yml"
export CVAT_HOST="cvat.company.com"
export CVAT_BASE_URL="https://cvat.company.com"
```

Update your `docker-compose.override.yml`:

```yaml theme={null}
services:
  cvat_server:
    environment:
      AUTH_CONFIG_PATH: /auth_config.yml
      CVAT_BASE_URL: https://cvat.company.com
    volumes:
      - ./auth_config.yml:/auth_config.yml:ro
```

### Starting CVAT with SSO

```bash theme={null}
docker compose up -d
```

The login page will now display a "Continue with SSO" button.

## LDAP Authentication

LDAP integration allows users to authenticate against Active Directory, FreeIPA, or other LDAP servers.

Source: `site/content/en/docs/administration/community/advanced/ldap.md`

### Prerequisites

Install the Python LDAP library in your CVAT container:

```dockerfile theme={null}
RUN pip install django-auth-ldap
```

Or build a custom Docker image with this dependency.

### Configuration

Create a custom Django settings file (`settings.py`) that imports production settings and adds LDAP configuration.

#### Active Directory Example

```python theme={null}
# Overlay production settings
from cvat.settings.production import *

# Import LDAP modules
import ldap
from django_auth_ldap.config import LDAPSearch, NestedActiveDirectoryGroupType

# Set IAM type to LDAP
IAM_TYPE = 'LDAP'

# LDAP server configuration
AUTH_LDAP_SERVER_URI = "ldap://ad.example.com"
ldap.set_option(ldap.OPT_REFERRALS, 0)

_BASE_DN = "CN=Users,DC=ad,DC=example,DC=com"

# Bind credentials
AUTH_LDAP_BIND_DN = "CN=cvat_bind,%s" % _BASE_DN
# Alternative format: "cvat_bind@ad.example.com"
AUTH_LDAP_BIND_PASSWORD = "SuperSecurePassword^21"

# User search configuration
AUTH_LDAP_USER_SEARCH = LDAPSearch(
    _BASE_DN,
    ldap.SCOPE_SUBTREE,
    "(sAMAccountName=%(user)s)"
)

# Group search configuration
AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
    _BASE_DN,
    ldap.SCOPE_SUBTREE,
    "(objectClass=group)"
)

# Map LDAP attributes to Django fields
AUTH_LDAP_USER_ATTR_MAP = {
    "user_name": "sAMAccountName",
    "first_name": "givenName",
    "last_name": "sn",
    "email": "mail",
}

# Group type
AUTH_LDAP_GROUP_TYPE = NestedActiveDirectoryGroupType()

# Register LDAP authentication backend
AUTHENTICATION_BACKENDS += ['django_auth_ldap.backend.LDAPBackend']

# Map AD groups to CVAT roles
AUTH_LDAP_ADMIN_GROUPS = ['CN=CVAT Admins,%s' % _BASE_DN]
AUTH_LDAP_WORKER_GROUPS = ['CN=CVAT Workers,%s' % _BASE_DN]
AUTH_LDAP_USER_GROUPS = ['CN=CVAT Users,%s' % _BASE_DN]

DJANGO_AUTH_LDAP_GROUPS = {
    "admin": AUTH_LDAP_ADMIN_GROUPS,
    "user": AUTH_LDAP_USER_GROUPS,
    "worker": AUTH_LDAP_WORKER_GROUPS,
}
```

#### FreeIPA Example

```python theme={null}
from cvat.settings.production import *

import ldap
from django_auth_ldap.config import LDAPSearch, GroupOfNamesType

IAM_TYPE = 'LDAP'

_BASE_DN = "CN=Accounts,DC=ipa,DC=example,DC=com"

AUTH_LDAP_SERVER_URI = "ldap://ipa.example.com"
ldap.set_option(ldap.OPT_REFERRALS, 0)

AUTH_LDAP_BIND_DN = "UID=cvat_bind,CN=Users,%s" % _BASE_DN
AUTH_LDAP_BIND_PASSWORD = "SuperSecurePassword^21"

AUTH_LDAP_USER_SEARCH = LDAPSearch(
    "CN=Users,%s" % _BASE_DN,
    ldap.SCOPE_SUBTREE,
    "(uid=%(user)s)"
)

AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
    "CN=Groups,%s" % _BASE_DN,
    ldap.SCOPE_SUBTREE,
    "(objectClass=groupOfNames)"
)

AUTH_LDAP_USER_ATTR_MAP = {
    "user_name": "uid",
    "first_name": "givenName",
    "last_name": "sn",
    "email": "mail",
}

AUTH_LDAP_GROUP_TYPE = GroupOfNamesType()

AUTHENTICATION_BACKENDS += ['django_auth_ldap.backend.LDAPBackend']

AUTH_LDAP_ADMIN_GROUPS = ['CN=cvat_admins,CN=Groups,%s' % _BASE_DN]
AUTH_LDAP_WORKER_GROUPS = ['CN=cvat_workers,CN=Groups,%s' % _BASE_DN]
AUTH_LDAP_USER_GROUPS = ['CN=cvat_users,CN=Groups,%s' % _BASE_DN]

DJANGO_AUTH_LDAP_GROUPS = {
    "admin": AUTH_LDAP_ADMIN_GROUPS,
    "user": AUTH_LDAP_USER_GROUPS,
    "worker": AUTH_LDAP_WORKER_GROUPS,
}
```

### Deploying LDAP Configuration

Update your `docker-compose.override.yml`:

```yaml theme={null}
services:
  cvat_server:
    environment:
      DJANGO_SETTINGS_MODULE: settings
    volumes:
      - ./settings.py:/home/django/settings.py:ro
```

Restart CVAT:

```bash theme={null}
docker compose down
docker compose up -d
```

### LDAP Group Mapping

CVAT roles are mapped to LDAP groups:

* **admin**: Full administrative access
* **user**: Standard annotation user
* **worker**: Limited worker access

Users are assigned the highest priority role from their LDAP group memberships.

### Troubleshooting LDAP

#### Test LDAP Connection

```bash theme={null}
docker exec -it cvat_server bash
ldapsearch -x -H ldap://your-ldap-server -D "CN=cvat_bind,CN=Users,DC=ad,DC=example,DC=com" -W -b "CN=Users,DC=ad,DC=example,DC=com"
```

#### Enable LDAP Debug Logging

Add to your `settings.py`:

```python theme={null}
LOGGING['loggers']['django_auth_ldap'] = {
    'level': 'DEBUG',
    'handlers': ['console'],
}
```

#### Common Issues

* **Connection refused**: Check firewall rules and LDAP server accessibility
* **Bind failed**: Verify bind DN and password
* **User not found**: Check user search base DN and filter
* **No groups assigned**: Verify group search configuration and group DNs

## IAM Type Configuration

Set the IAM type in your Django settings:

```python theme={null}
IAM_TYPE = 'BASIC'   # Default username/password authentication
IAM_TYPE = 'LDAP'    # LDAP authentication
```

See `cvat/settings/base.py:224` for the IAM\_TYPE setting.

## Additional Resources

### SSO Resources

* [Microsoft LDAP Distinguished Names](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/ldap/distinguished-names)
* [Django-allauth OIDC Documentation](https://docs.allauth.org/en/latest/socialaccount/providers/openid_connect.html)
* [Django-allauth SAML Documentation](https://docs.allauth.org/en/latest/socialaccount/providers/saml.html)
* Source: `site/content/en/docs/account_management/sso.md`

### LDAP Resources

* [Django LDAP Reference Manual](https://django-auth-ldap.readthedocs.io/en/latest/reference.html)
* [Django LDAP with Active Directory Guide](https://techexpert.tips/django/django-ldap-authentication-active-directory)
* Source: `site/content/en/docs/administration/community/advanced/ldap.md`

## Enterprise Support

For enterprise deployments requiring SSO or LDAP integration, contact CVAT.ai:

* Website: [cvat.ai/pricing/on-prem](https://www.cvat.ai/pricing/on-prem)
* Email: [support@cvat.ai](mailto:support@cvat.ai)

Enterprise features include:

* SSO with OIDC and SAML
* LDAP/Active Directory integration
* Advanced analytics
* Priority support with 24-hour SLA
* Training and onboarding