SSO configuration

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

To configure SSO, complete the following 2 main steps:

1. Configure the Identity Provider (IdP) — set up an application on your IdP platform.
2. Update the CVAT configuration — provide the necessary identity provider settings in the CVAT configuration file.

If the application is already configured, refer to the Configuring SSO in CVAT section. Otherwise, you may follow one of the detailed platform-specific guides to set up such an application:

• Microsoft Azure
• Okta
• Auth0
• keycloak

Platform specific IdP configuration

Microsoft Azure

OpenID Connect

Follow these steps to configure an application on the Microsoft Azure platform and integrate it with CVAT:

Step 1: Register an OIDC-based application

To start, log into your Microsoft Azure Portal. Once you’re in:

1. Navigate to the Microsoft Entra ID service -> App registrations section in the menu on the left.

2. Click on the + New registration button.

3. Enter application name.

4. Select Supported account types based on your needs.

5. Add Redirect URI: choose Web platform and set <scheme:cvat_domain>/api/auth/oidc/<idp-id:azure-oidc>/login/callback/ to the value field.

   

6. Click on the Register button.

You’ve created an app, now you should configure the credentials for it.

Step 2: Configure credentials

1. Navigate to the Overview tab of your newly created application.
2. In the Client credentials section, click the Add a certificate or secret link. This will take you to the Certificates & secrets page.
3. Click + New client secret.
4. In the popup form, enter a description and select an expiration period, then click Add.

The newly created secret will appear in the list. Make sure to copy the value now — you won’t be able to see it again later.

Step 3: Configure CVAT

Utilize the example below as a template for your configuration:

sso:
  enabled: true
  selection_mode: email_address
  identity_providers:
    - id: <idp-id:azure-oidc>
      protocol: OIDC
      name: Azure OIDC-based IdP
      server_url: https://<Directory (tenant) ID>/v2.0/
      client_id: <Secret ID>
      client_secret: <Secret Value>
      email_domain: <company_email_domain>

You can now proceed to start CVAT. For additional CVAT configuration details, refer to Configuring SSO in CVAT.

SAML

Follow these steps to configure an application on the Microsoft Azure platform and integrate it with CVAT:

Step 1: Register an SAML-based application

To start, log into your Microsoft Azure Portal. Once you’re in:

1. Navigate to the Microsoft Entra ID service -> Enterprise applications section in the menu on the left.
2. Click + New application and enter a name for the application in the popup window, then click Create.

You’ve created an app, now you should finalize its configuration and assign users or groups.

Step 2: Configure a created application

1. Navigate to the Single sign-on section in the menu on the left.
2. Choose the SAML protocol as the single sign-on method.
3. Edit Basic SAML Configuration:
   • Identifier (Entity ID): <scheme:cvat_domain>/api/auth/saml/<idp-id:azure-saml>/metadata/
   • Reply URL (Assertion Consumer Service URL): <scheme:cvat_domain>/api/auth/saml/<idp-id:azure-saml>/acs/
   • Save changes
4. Edit Attributes & Claims by adding a new uid claim:
   • Name: uid
   • Namespace: http://schemas.xmlsoap.org/ws/2005/05/identity/claims
   • Source: attribute
   • Source attribute: user.objectid

Step 3: Assign users and groups

At this point, no users or groups have been assigned to the application. To grant access:

1. Navigate to the Users and groups section of the application.
2. Click the + Add user/group button.
3. Select the users or groups you want to assign.
4. Confirm selection.

The selected users or groups will now appear in the assignment list.

That’s it, now we can move on to the configuration in CVAT.

Step 4: Configure CVAT

Utilize the example below as a template for your configuration:

sso:
  enabled: true
  selection_mode: email_address
  identity_providers:
    - id: <idp-id:azure-saml>
      protocol: SAML
      name: Azure SAML-based IdP
      entity_id: <Microsoft Entra Identifier> (https://sts.windows.net/<tenantId>/)
      metadata_url: <App Federation Metadata Url>

      attribute_mapping:
        uid: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/uid
        username: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
        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: it is not possible to configure SAML-based application to send this claim to the SP

      email_domain: <company_email_domain>

You can now proceed to start CVAT. For additional CVAT configuration details, refer to Configuring SSO in CVAT.

Okta

OpenID Connect

Follow these steps to configure an application on the Okta platform and integrate it with CVAT:

Step 1: Register an OIDC-based application

To start, log into your Okta admin dashboard. Once you’re in:

1. Navigate to the Applications section in the menu on the left.

2. Click on the Create App integration button.

3. Select OIDC - OpenID Connect as a sign-in method and Web Application type.

4. Fill the form with the following content:

   • App integration name: enter a name for the application
   • Sign-in redirect URIs: <scheme:cvat_domain>/api/auth/oidc/<idp-id:okta-oidc>/login/callback/
   • Select option in the Controlled access to match your requirements. In this example, we’ll use Skip group assignment for now.

   

You’ve created and configured the app, now you should assign users or groups to the application.

Step 2: Assign users or groups

At this point, no users or groups have been assigned to the application. To grant access:

1. Navigate to the Assignments tab of the application.
2. Click the Assign button and select Assign to People or Assign to Groups based on your needs.
3. Identify the users or groups you want to assign, then click assign.

The selected users or groups will now appear in the assignment list.

Step 3: Configure CVAT

Utilize the example below as a template for your configuration:

sso:
  enabled: true
  selection_mode: email_address
  identity_providers:
    - id: <idp-id:okta-oidc>
      protocol: OIDC
      name: Okta OIDC-based IdP
      server_url: https://<okta_domain>/
      client_id: <client_id>
      client_secret: <client_secret>
      email_domain: <company_email_domain>

Tip

Actual Client ID and Client secret key values may be found on the General tab of the created application

You can now proceed to start CVAT. For additional CVAT configuration details, refer to Configuring SSO in CVAT.

SAML

Follow these steps to configure an application on the Okta platform and integrate it with CVAT:

Step 1: Register an SAML-based application

To start, log into your Okta admin dashboard. Once you’re in:

1. Navigate to the Applications section in the menu on the left.

2. Click on the Create App integration button.

3. Select SAML 2.0 as a sign-in method, then click Next.

4. Fill the form with the general settings and go to the next configuration step.

5. On the Configure SAML form set the following fields:

   • Single sign-on URL: <scheme:cvat_domain>/api/auth/saml/<idp-id:okta-saml>/acs/
   • Audience URI (SP Entity ID: <scheme:cvat_domain>/api/auth/saml/<idp-id:okta-saml>/metadata/

6. Define attribute statements that will be shared with CVAT. In our example we will use the Basic attribute name format and set the mapping as shown below:

   • firstName: user.firstName
   • lastName: user.lastName
   • username: user.login
   • email: user.email
   • uid: user.getInternalProperty("id")

   

   Tip

   If attribute mapping needs to be adapted, follow the official documentation on how to configure Attribute Statements

7. Navigate to the next configuration step and fill the Feedback form.

You’ve created and configured the app. You can now either complete an optional step to simplify the login process in CVAT or proceed directly to the CVAT configuration step.

Step 2: Simplify login process

If CVAT is configured to require email verification, it expects the Identity Provider to include the email_verified claim. However, Okta does not send this claim by default. As a result, users will receive a confirmation email with a verification link.

There is an option to include email verification claim on the sign-in step:

1. Add one more mapping emailVerified -> user.emailVerified on SAML-based application configuration step:
   1. Navigate to the SAML Settings on the General tab and click Edit.
   2. Add one more attribute mapping as it was described in the app configuration step.
2. Add custom user attribute emailVerified:
   • Navigate to the Directory section in the menu on the left -> Profile Editor item
   • Select the default user profile from the list (User (default))
   • Click + Add Attribute
   • Fill out the form with your desired values, making sure to select the boolean data type
   • Click Save
3. Update user profiles:
   • Navigate to the People section in the menu on the left
   • Set the value for the recently created attribute for each person

Step 3: Configure CVAT

Utilize the example below as a template for your configuration:

sso:
  enabled: true
  selection_mode: email_address
  identity_providers:
    - id: <idp-id:okta-saml>
      protocol: SAML
      name: Okta SAML-based Identity Provider
      entity_id: <Issuer>
      metadata_url: <Metadata URL>

      attribute_mapping:
        uid: uid
        username: username
        email: email
        first_name: firstName
        last_name: lastName
        email_verified: emailVerified # if configured

      email_domain: <company_email_domain>

Tip

Metadata URL and Issuer values may be found on the Sign On tab of the application setting

You can now proceed to start CVAT. For additional CVAT configuration details, refer to Configuring SSO in CVAT.

Auth0

OpenID Connect

Follow these steps to configure an application in the Auth0 platform and integrate it with CVAT:

Step 1: Register an OIDC-based application

To start, log into your Auth0 dashboard. Once you’re in:

1. Navigate to the Applications section in the menu on the left, click + Create Application.
2. Enter a name for the application and choose the Regular Web Applications type, then click Create.

You’ve created an app, now you should finalize its configuration.

Step 2: Configure a created application

1. In the Settings tab of your new application, scroll down to the Application URIs section.
2. Add <scheme:cvat_domain>/api/auth/oidc/<idp-id:auth0-oidc>/login/callback/ to the Allowed Callback URLs.
3. Save changes.

That’s it, now we can move on to the configuration in CVAT.

Step 3: Configure CVAT

Utilize the example below as a template for your configuration:

sso:
  enabled: true
  selection_mode: email_address
  identity_providers:
    - id: <idp-id:auth0-oidc>
      protocol: OIDC
      name: Auth0 OIDC-based IdP
      server_url: https://<auth0_domain>/
      client_id: <client_id>
      client_secret: <client_secret>
      email_domain: <company_email_domain>

Tip

Client ID, Client Secret and Domain can be found in the Basic Information section of application settings

You can now proceed to start CVAT. For additional CVAT configuration details, refer to Configuring SSO in CVAT.

SAML

Follow these steps to configure an application in the Auth0 platform and integrate it with CVAT:

Step 1: Register an SAML-based application

To start, log into your Auth0 dashboard. Once you’re in:

1. Navigate to the Applications section in the menu on the left, click + Create Application.
2. Enter a name for the application and choose the Regular Web Applications type, then click Create.

You’ve created an app, now you should finalize its configuration.

Step 2: Configure a created application

1. Navigate to the Addons tab of the created application and click on the SAML2 WEB APP button.

2. Open the Settings tab in the popup window and set the following configuration:

   • Application Callback URL: <scheme:cvat_domain>/api/auth/saml/<idp-id:auth0-saml>/acs/
   • Settings: enter a JSON object like the following:

   {
     "audience": "<scheme:cvat_domain>/api/auth/saml/<idp-id:auth0-saml>/metadata/",
     "recipient": "<scheme:cvat_domain>/api/auth/saml/<idp-id:auth0-saml>/acs/",
     "destination": "<scheme:cvat_domain>/api/auth/saml/<idp-id:auth0-saml>/acs/",
     "mappings": {
       "user_id": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
       "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
       "nickname": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/username",
       "given_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
       "family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
       "email_verified": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailverified"
     },
     "createUpnClaim": false,
     "passthroughClaimsWithNoMapping": false,
     "mapIdentities": false
   }
   

3. Scroll down and click Enable.

That’s it, now we can move on to the configuration in CVAT.

Step 3: Configure CVAT

Utilize the example below as a template for your configuration:

sso:
  enabled: true
  selection_mode: email_address
  identity_providers:
    - id: <idp-id:auth0-saml>
      protocol: SAML
      name: Auth0 SAML-based IdP
      entity_id: <Issuer>
      metadata_url: <Metadata URL>

      attribute_mapping:
        uid: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
        username: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/username
        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_email_domain>

Tip

Actual Metadata URL and Issuer values may be found on the Usage tab of the SAML2 Web App plugin

You can now proceed to start CVAT. For additional CVAT configuration details, refer to Configuring SSO in CVAT.

Keycloak

To configure SSO in terms of Keycloak we need to create a client.

OpenID Connect

Follow these steps to do that:

Step 1: Register an OIDC-based client

To start, go to the Keycloak service (by default it is listening for HTTP and HTTPS requests using the ports 8080 and 8443, respectively) and log into your admin account. Once you’re in:

1. Under the desired realm navigate to the Clients section and click create client.
2. Fill out the general client settings:
   • Client type: OpenID Connect
   • Client ID: enter client identifier
   • Enter a name for the client, e.g. OIDC-based client
3. In the next step, enable the Client authentication toggle.
4. In the Login settings section, provide the following values:
   • Home URL: <scheme:cvat_domain>
   • Valid redirect URIs: <scheme:cvat_domain>/api/auth/oidc/<idp-id:keycloak-oidc>/login/callback/
   • Web origins: <scheme:cvat_domain>

That’s it, now we can move on to the configuration in CVAT.

Step 2: Configure CVAT

Utilize the example below as a template for your configuration:

sso:
  enabled: true
  selection_mode: email_address
  identity_providers:
    - id: <idp-id:keycloak-oidc>
      protocol: OIDC
      name: Keycloak OIDC-based Identity Provider
      server_url: <scheme:keycloak_domain>/realms/<custom_realm>/.well-known/openid-configuration
      client_id: <Client ID>
      client_secret: <Client Secret>
      email_domain: <company_email_domain>

Tip

Actual Client Secret value can be found on the Credentials tab of the created OIDC client

You can now proceed to start CVAT. For additional CVAT configuration details, refer to Configuring SSO in CVAT.

SAML

Follow these steps to configure a client:

Step 1: Register a SAML-based client

To start, go to the Keycloak service (by default it is listening for HTTP and HTTPS requests using the ports 8080 and 8443, respectively) and log into your admin account. Once you’re in:

1. Under the desired realm navigate to the Clients section and click create client.
2. Fill out the general client settings:
   • Client type: SAML
   • Set the Clint ID the URL: <scheme:cvat_domain>/api/auth/saml/<idp-id:keycloak-saml>/metadata/
   • Enter a name for the client, e.g. SAML client
3. In the Login settings section, provide the following values:
   • Home URL: <scheme:cvat_domain>
   • Valid redirect URIs: <scheme:cvat_domain>/api/auth/saml/<idp-id:keycloak-saml>/acs/

You’ve created a client, now you should finalize its configuration.

Step 2: Configure a created client

1. Navigate to the general settings of the created client, scroll down to the SAML capabilities section.
2. Update the following parameters:
   • Name ID format: email
   • Force name ID format: On
3. Navigate to the Keys tab and enable the Client signature required toggle.
4. Configure attributes & claims:

   1. Navigate to the Client scopes tab on the created client -> dedicated scopes for the client. You will see that there is no configured mappers.

   2. Set up mappers for the following attributes:

      • uid
      • first_name
      • last_name
      • username
      • email

      For attributes like email, first name, and last name, you can either

      • Use the predefined mappers
      • Or follow the manual configuration steps to create them yourself.

      To configure other mappers click Configure a new mapper if it is a first mapper or Add mapper -> By configuration and then select User Property.

      For instance, to configure a mapper for the username attribute, fill in the form as it is done below:

      • Name: username
      • Property: username
      • SAML Attribute Name: usernameAttribute

That’s it, now we can move on to the configuration in CVAT.

Step 3: Configure CVAT

Utilize the example below as a template for your configuration:

sso:
  enabled: true
  selection_mode: email_address
  identity_providers:
    - id: <idp-id:keycloak-saml>
      protocol: SAML
      name: Keycloak SAML-based Identity Provider
      entity_id: <scheme:keycloak_domain>/realms/<custom_realm>
      metadata_url: <scheme:keycloak_domain>/realms/<custom_realm>/protocol/saml/descriptor

      attribute_mapping:
        uid: uidAttribute
        email_verified: emailVerifiedAttribute
        email: emailAttribute
        last_name: lastNameAttribute
        first_name: firstNameAttribute
        username: usernameAttribute

      email_domain: <company_email_domain>

Tip

Actual Metadata URL may be found in the Realm settings on the General tab

You can now proceed to start CVAT. For additional CVAT configuration details, refer to Configuring SSO in CVAT.

Configuring SSO in CVAT

CVAT provides a dedicated configuration file to customize the login and registration flow. The sso section of this file specifies which external Identity Provider (IdP) integrations are enabled. To set up SSO, you typically create a custom YAML configuration file (e.g., auth_config.yml) and supply its path when starting CVAT.

SSO settings

---
sso:
  enabled: true|false
  selection_mode: email_address|lowest_weight
  enable_pkce: true|false
  ...

IdP Configuration Structure

To integrate an Identity Provider, you must define its configuration block under the identity_providers section in the CVAT config file. Each provider’s configuration includes both general and protocol-specific settings.

Additionally, each IdP configuration must include several protocol-specific parameters:

• OpenID Connect
• SAML

Below are examples of SSO configuration file for both protocols:

• Integrate OIDC-based IdP
• Integrate SAML-based IdP

---
sso:
  enabled: true
  selection_mode: email_address
  identity_providers:
    - id: oidc-idp
      protocol: OIDC
      name: OIDC-based IdP
      server_url: https://example.com
      client_id: xxx
      client_secret: xxx
      email_domain: example.com

 ---
 sso:
   enabled: true
   selection_mode: lowest_weight
   identity_providers:
     - id: saml-idp
       protocol: SAML
       name: SAML-based IdP
       entity_id: <idp-entity-id>
       weight: 1
       # specify only metadata_url or sso_url and x509_cert
       metadata_url: http://example.com/path/to/saml/metadata/
       sso_url: <Login URL>
       x509_cert: |
         -----BEGIN CERTIFICATE-----
         certificate content
         -----END CERTIFICATE-----         

       attribute_mapping:
         uid: uidAttribute
         email_verified: emailVerifiedAttribute
         email: emailAttribute
         last_name: lastNameAttribute
         first_name: firstNameAttribute
         username: usernameAttribute

More information about OIDC-based and SAML-based IdP configuration expected by Django Allauth can be found here and here respectively.

Start CVAT

Once the configuration file is created, several environment variables must be exported before running CVAT:

export AUTH_CONFIG_PATH="<path_to_auth_config>"
export CVAT_HOST="<cvat_host>"
# cvat_port is optional
export CVAT_BASE_URL="<http|https>://${CVAT_HOST}:<cvat_port>"

Start the CVAT Enterprise instance as usual.

That’s it! The CVAT login page now should have the Continue with SSO option, allowing users to authenticate using the configured Identity Provider.