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

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

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:

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:

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

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:

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

# 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: "[e-mail]"
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

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:

services:
  cvat_server:
    environment:
      DJANGO_SETTINGS_MODULE: settings
    volumes:
      - ./settings.py:/home/django/settings.py:ro

Restart CVAT:

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

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:

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:

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
• Django-allauth OIDC Documentation
• Django-allauth SAML Documentation
• Source: site/content/en/docs/account_management/sso.md

LDAP Resources

• Django LDAP Reference Manual
• Django LDAP with Active Directory Guide
• 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
• Email: [e-mail]

Enterprise features include:

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