This page is relevant to some institutions depending on their Identity Provider configuration and specific claims used in the authentication process. Please refer to EchoVideo: Configuring Auth0 Authentication for more information.

EchoVideo depends on 'email' as the unique identifier for user logins, however for Single Sign-On (SSO) institutions may be dependent on a User Principal Name (UPN) or another claim to map user accounts in their Identity Provider (IdP) with EchoVideo.

The primary lookup for SSO with EchoVideo is based on matching the attributed passed with the echo_identity claim and the ssoId values.

Configuring echo_identity

echo_identity is a custom claim configured as part of the Auth0 setup and can pass a string value that might take the form of an email or a username. If present, this value will override the value being passed in the 'email' claim.

Populating ssoId

ssoId is a field associated with a user's account in EchoVideo that can be optionally added as an override to the EchoVideo user's email value for SSO authentication. This value must match the value being passed to Auth0 in the echo_identity claim and can be populated in one of the following ways:

Manually, using the Users page

The 'SSO ID' field on the Edit User modal can be used. You can navigate to this under the Users page accessible by administrators EchoVideo: Editing Users.

1. Go to Admin Dashboard > Users and search for a specific user.
2. Click on Edit under the three-vertical-dots on the right of the specific user in the Users table: 
   
3. The main User Information tab will have an optional field called 'SSO ID'. 
   
4. Populate the 'SSO ID' field and click Update to save the change.

Bulk Import

For large user bases, the Bulk CSV Import and Export tool is useful as new users can be created or existing users updated with an SSO ID.

New Users

1. Go to Admin Dashboard > Imports/Exports > Imports and click on Imports
2. Select Version 1, User, and Create to display the see the fields required and optional for creating new users in bulk. 
   
3. Use the 'Download a sample CSV file' to retrieve a template CSV containing the relevant fields.
4. For SSO ID, the field in the CSV labeled 'SSO Id' will need to be populated for relevant users.
5. Once the CSV is completed, use the UPLOAD CSV button on the 'Import CSV' modal to upload and initiate the bulk user creation.

Existing Users

1. To retrieve existing users table for populating the 'SSO ID' field, go to Admin Dashboard > Imports/Exports > Exports
2. Select Version 1 and User and click on START EXPORT JOB. 
   
3. Once the job is completed, download the CSV containing existing users and the columns contained will be those required to construct the CSV required for importing to update existing users.
4. The CSV will include the column 'SSO Id', that can be populated. 
   
5. Once the 'SSO Id' column has been populated for the require users, go to Admin Dashboard > Imports/Exports > Imports and click on IMPORT CSV.
6. Select Version 1, User, and Update in the modal.
   
7. Click UPLOAD CSV to upload the configured file from step 4.
8. Once the CSV is uploaded, this will trigger those existing user accounts to be updated with the specified 'SSO Id'.
9. Validate these changes using the Admin Dashboard > Users to search for an updated user and validate the 'SSO ID' under the 'User Information' has changed.

Programmatically via API

REST API endpoints can be used to create and update users and the 'ssoId' field programmatically.

Swagger documentation for each region can be found: EchoVideo: Using Swagger Docs UI for API Calls

• Creating users is a POST request to the users endpoint with the requisite request body show below that includes the ssoId field.

  {
    "email": "Foo.Bar@echo360.com",
    "timeZone": "US/Eastern",
    "firstName": "Foo",
    "lastName": "Bar",
    "phoneNumber": {
      "region": "United Kingdom",
      "number": "999-999-9999, 123456789012345"
    },
    "profileImageUrl": "string",
    "roles": [
      "string"
    ],
    "ssoId": "fbar+internet2.edu@subdomain.incommon.org",
    "externalId": "Foo.Bar@echo360.com"
  }

• Updating a user's account is a PUT request to the users endpoint and specifying the ssoId field in the request body.

  {
    ...
    "ssoId": "fbar+internet2.edu@subdomain.incommon.org",
    ...
  }