Authentication

Authentication methods and configuration for self-hosted CVAT

CVAT supports multiple authentication methods for self-hosted deployments, providing flexibility for different organizational requirements.

Authentication Methods

CVAT implements the following authentication methods defined in cvat/settings/base.py:136-141:

1. Token Authentication: API token-based authentication
2. Access Token Authentication: Bearer token authentication
3. Session Authentication: Cookie-based session authentication
4. Basic Authentication: HTTP Basic authentication

Default Authentication Backends

Configured in cvat/settings/base.py:250-253:

AUTHENTICATION_BACKENDS = [
    "django.contrib.auth.backends.ModelBackend",
    "allauth.account.auth_backends.AuthenticationBackend",
]

Django Model Backend

The default Django authentication backend that authenticates against the PostgreSQL database using username/email and password.

Django-allauth Backend

Provides advanced authentication features including:

• Email verification
• Social authentication support
• Account management

See cvat/settings/base.py:255-263 for allauth configuration.

REST API Authentication

REST API authentication classes defined in cvat/settings/base.py:136-141:

"DEFAULT_AUTHENTICATION_CLASSES": [
    "rest_framework.authentication.TokenAuthentication",
    "cvat.apps.access_tokens.authentication.AccessTokenAuthentication",
    "rest_framework.authentication.SessionAuthentication",
    "cvat.apps.iam.authentication.BasicAuthenticationEx",
]

Token Authentication

Django REST Framework’s built-in token authentication. Users receive a token upon login that must be included in the Authorization header:

Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

Access Token Authentication

Custom bearer token authentication for API access tokens. Implemented in cvat/apps/access_tokens/authentication.py:11-27.

Tokens are passed in the Authorization header:

Authorization: Bearer <access_token>

Key features:

• Validates token against the database
• Checks user active status
• Updates last use timestamp
• Raises AuthenticationFailed for invalid or expired tokens

Session Authentication

Cookie-based authentication for web browsers. Sessions are stored in Redis and managed by Django.

Session configuration in cvat/settings/base.py:423:

CSRF_COOKIE_NAME = "csrftoken"

Basic Authentication Extended

Custom implementation in cvat/apps/iam/authentication.py:12-26 that extends Django REST Framework’s BasicAuthentication with email verification:

class BasicAuthenticationEx(BasicAuthentication):
    def authenticate(self, request):
        result = super().authenticate(request)
        
        if (
            allauth_settings.EMAIL_VERIFICATION
            == allauth_settings.EmailVerificationMethod.MANDATORY
            and result
        ):
            user = result[0]
            if not EmailAddress.objects.is_verified(user.email):
                raise exceptions.AuthenticationFailed("E-mail is not verified.")
        
        return result

Account Configuration

Account authentication settings in cvat/settings/base.py:256-263:

ACCOUNT_EMAIL_VERIFICATION = "none"  # Options: "none", "optional", "mandatory"
ACCOUNT_AUTHENTICATION_METHOD = "username_email"  # Users can login with username or email
ACCOUNT_EMAIL_CONFIRMATION_ANONYMOUS_REDIRECT_URL = "/auth/email-confirmation"
ACCOUNT_EMAIL_VERIFICATION_SENT_REDIRECT_URL = "/auth/email-verification-sent"
INCORRECT_EMAIL_CONFIRMATION_URL = "/auth/incorrect-email-confirmation"

Username Requirements

Defined in cvat/settings/base.py:693:

ACCOUNT_USERNAME_MIN_LENGTH = 5
ACCOUNT_LOGOUT_ON_PASSWORD_CHANGE = True

Email Verification

Email verification can be configured to:

• none: No email verification required (default)
• optional: Email verification is optional
• mandatory: Email must be verified before access is granted

To enable email verification, you need to configure email settings. See the Email Configuration section below.

Email Configuration Example

Create a custom settings file based on cvat/settings/email_settings.py:1-17:

from cvat.settings.production import *

# Enable email verification
ACCOUNT_AUTHENTICATION_METHOD = "username_email"
ACCOUNT_CONFIRM_EMAIL_ON_GET = True
ACCOUNT_EMAIL_REQUIRED = True
ACCOUNT_EMAIL_VERIFICATION = "mandatory"

# Configure email backend (example for SMTP)
EMAIL_BACKEND = "django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST = "smtp.gmail.com"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_HOST_USER = "[e-mail]"
EMAIL_HOST_PASSWORD = "your-app-password"
DEFAULT_FROM_EMAIL = "[e-mail]"

Note: By default, EMAIL_BACKEND is set to None in cvat/settings/base.py:754, which will raise an error if email functionality is needed without proper configuration.

Identity and Access Management (IAM)

IAM settings in cvat/settings/base.py:223-233:

IAM_TYPE = "BASIC"  # Options: "BASIC", "LDAP"
IAM_DEFAULT_ROLE = "user"
IAM_ADMIN_ROLE = "admin"
IAM_ROLES = ["admin", "user", "worker"]  # Ordered by priority
IAM_OPA_HOST = "http://opa:8181"
IAM_OPA_DATA_URL = f"{IAM_OPA_HOST}/v1/data"
LOGIN_URL = "rest_login"
LOGIN_REDIRECT_URL = "/"

User Roles

Three built-in roles with descending priority:

1. admin: Full system access
2. user: Standard user access
3. worker: Limited access for annotation workers

Password Validation

Password validators defined in cvat/settings/base.py:397-410:

AUTH_PASSWORD_VALIDATORS = [
    {"NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator"},
    {"NAME": "django.contrib.auth.password_validation.MinimumLengthValidator"},
    {"NAME": "django.contrib.auth.password_validation.CommonPasswordValidator"},
    {"NAME": "django.contrib.auth.password_validation.NumericPasswordValidator"},
]

Login URLs and Redirects

Defined in cvat/settings/base.py:233-234:

LOGIN_URL = "rest_login"
LOGIN_REDIRECT_URL = "/"

Open Policy Agent (OPA)

CVAT uses OPA for authorization decisions. Configuration in docker-compose.yml:313-330:

cvat_opa:
  container_name: cvat_opa
  image: openpolicyagent/opa:1.12.2
  command:
    - run
    - --server
    - --addr=:8181
    - --set=services.cvat.url=http://cvat-server:8080
    - --set=bundles.cvat.service=cvat
    - --set=bundles.cvat.resource=/api/auth/rules

The OPA server fetches authorization rules from the CVAT server at /api/auth/rules.

API Rate Limiting

Throttle configuration in cvat/settings/base.py:158-163:

"DEFAULT_THROTTLE_CLASSES": [
    "rest_framework.throttling.AnonRateThrottle",
],
"DEFAULT_THROTTLE_RATES": {
    "anon": "100/minute",
}

Anonymous users are limited to 100 requests per minute. Authenticated users have no throttle limit by default.

Custom Authentication Adapter

Custom account adapter in cvat/settings/base.py:696:

ACCOUNT_ADAPTER = "cvat.apps.iam.adapters.DefaultAccountAdapterEx"

Security Settings

HTTPS Configuration

Configured in cvat/settings/base.py:601-609:

# Trust X-Forwarded-Proto header from proxy
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
SECURE_REFERRER_POLICY = "strict-origin-when-cross-origin"
USE_X_FORWARDED_HOST = True

CORS Configuration

CORS headers defined in cvat/settings/base.py:585-596:

CORS_ALLOW_HEADERS = list(default_headers) + [
    "upload-offset",
    "upload-length",
    "tus-version",
    "tus-resumable",
    "upload-start",
    "upload-finish",
    "upload-multiple",
    "x-organization",
]

API Documentation

CVAT provides interactive API documentation with authentication support. Configuration in cvat/settings/base.py:617-689:

SPECTACULAR_SETTINGS = {
    "SERVE_PERMISSIONS": ["rest_framework.permissions.IsAuthenticated"],
    # ...
}

Access the API documentation at:

• Swagger UI: http://your-host:8080/api/docs
• ReDoc: http://your-host:8080/api/redoc
• OpenAPI Schema: http://your-host:8080/api/schema

Next Steps

• SSO and LDAP Configuration - Enterprise SSO integration
• Configuration - General configuration options

Additional Resources

• Source: cvat/apps/iam/authentication.py
• Source: cvat/apps/access_tokens/authentication.py
• Source: cvat/settings/base.py:223-263
• Django Authentication Documentation
• Django REST Framework Authentication
• Django-allauth Documentation