CSV Import

How to Import Data from CSV Files into Veza

Overview

You can use a CSV file to upload identity and permissions metadata for applications that do not have a built-in Veza integration. Importing from CSV is especially useful when the target application supports exporting user metadata from a management console or API.

Uploading CSV data creates a custom application provider and data source. It also populates Authorization Graph entities with the specified attributes. The template currently supports Users, Groups, and Roles.

CSV format

CSV stands for "Comma-Separated Values." This widely used file format stores tabular data (numbers and text) in plain text format. A CSV file contains a set of records, where each row corresponds to a single record, and columns indicate the attributes for each row.

When importing from CSV, Veza uses the following column headers. All columns are optional except for "user id".

• "user id" (required): a unique identifier for the user, typically from the provider such as an email or GUID. Used to match additional columns with group/role assignments.

• "name": Full name for display purposes.

• "email": user email address.

• "active": whether the user is disabled.

• "groups" (group names separated by commas).

• "roles" (role names separated by commas).

• "created at": timestamp when the user was created.

• "deactivated at": timestamp when the user was disabled.

• "last login at": timestamp of last login.

• "password last changed at": timestamp of last password change.

Alternative column headers:

• "first name": First name. Replaces "name" column, when "last name" is present the two columns are joined to create the user's name.

• "last name": Last name. See above.

• "email address": Can be used in place of "email"

Here's an example:

user_id,name,active,email,created_at,deactivated_at,last_login_at,password_last_changed_at,groups,roles
bhaig0,John Smith,false,[e-mail],2021-02-05,,2024-04-02T09:37:54Z,,Sales,Senior Developer
bhaig0,,,[e-mail],,,,,Marketing,Lead Developer
mmourant1,Emily Johnson,true,[e-mail],2024-01-16,,2024-01-11T07:36:33Z,2023-07-25T05:30:31Z,Sales,Quality Engineer
pbolger2,Michael Brown,false,[e-mail],2023-11-04,2023-09-22 13:31:11,2024-03-25T02:16:34Z,2023-07-06T10:59:17Z,Sales,General Manager
pbolger2,,,[e-mail],,,,,Support,Team Lead

Notes

• Role and Group Assignment: The template supports multiple rows per user to express multiple group or role assignments. If a user row is repeated, the assigned groups/roles are added to the original user. Properties are based on the first row for that Unique ID. For subsequent rows for a unique user ID, only the groups and roles columns are processed.

• Active status: users are considered active if the field case-insensitively matches: active, enabled, true, t, yes, y, 1. Any other value will be treated as in-active. If the column is omitted or the value is an empty string, "Is Active" will be unset.

• The Name column can contain a full user name including spaces. For compatibility, Veza supports individual columns for Last Name and First Name. If present, display names will be the combination of "{First Name} {Last Name}".

• Email Address is used as an external identity for the user if supplied. It is stored as an Email property on the custom user.

• Rows without a User ID are skipped. If no user name is specified, Veza will show "{User ID}" as the display name.

• Timestamps: Veza supports full and partial timestamp formats:

  • 2023-04-12T15:34:56.123456789Z (RFC3339 with nanoseconds)

  • 2006-01-02T15:04:05Z07:00 (RFC3339)

  • 20060102150405 (Active Directory)

  • 2006-01-30 15:04:05Z07:00

  • 2006-01-30 15:04:05

  • 2006-01-30

  • 2006-01-30T

  • 2006-01-30T15:04:05

  • 2006-01-30T15:04:05Z

  • Timestamps are considered unset when the value is never, null, none, false, or 0. Invalid timestamps will result in a processing error.

• Column headers can substitute underscores for spaces, such as "unique id" = "unique_id." Column headers are case-insensitive.

• Field violations will indicate if a value is missing or has an incorrect format.

Preparing data for CSV import

The exact steps to create a CSV with the required data will vary based on the application. However, the general flow should look like:

1. Export Data: Export user data from the application's API or front end. This typically yields data in a format such as JSON, XML, or directly in CSV.

2. Transform Data:

   • Ensure the data is in CSV.

   • Ensure roles, groups, or similar fields are comma-separated in the CSV.

3. Map Fields: Align fields from the exported data to those expected by Veza. Rename or adjust fields as necessary.

4. Clean Data:

   • Remove inconsistencies and ensure fields have valid values.

5. Save as CSV: If using software like Excel or Google Sheets, export the data as a .csv file.

6. Review & Test:

   • Check a few rows for accuracy.

   • Test import a subset of data, if possible, before the full upload.

Adding a CSV integration

To create a custom CSV provider and data source, upload the initial data:

1. Go to Integrations > Create Integration.

2. Choose Upload CSV from the options.

3. Upload a logo for the provider (optional).

4. Provide a name for the provider and click Next. The application name and type will use this provider name.

5. Specify a name for the data source and proceed by clicking Next.

6. Upload your desired CSV file and finalize by clicking Create Integration.

Download the sample CSV template here:

Updating a CSV integration

Incremental updates are not supported; submit the full data set for each update.

To update an existing data source with fresh data:

1. Navigate to Integrations > Integrations.

2. Search for the relevant integration using its name and select Edit.

3. Upload the CSV file that contains the new set of data.