Skip navigation
Documentation

Duo Administration - Import Users from CSV

Last Updated: June 21st, 2024

Contents

The Import Users feature is used both to import batches of new users, and to update or delete existing users.

Overview

Duo's Import Users tool imports user information from a properly formatted comma-separated values (CSV) file. This streamlined process makes it easy to create, update, or delete many users at the same time.

CSV import values can include username aliases, email addresses, full names, groups, notes, and multiple phones or mobile devices. Manage users created via import from the Duo Admin Panel immediately after being created. This differs from the Bulk Enroll Users tool, in that those entries are initially limited to username and email address, and those users cannot be managed in Duo until they've completed self-enrollment.

Role required: Owner, Administrator, or User Manager.

Creating the CSV File

The CSV file can include multiple data fields for each Duo user.

Allowed Fields

The fields allowed in this CSV file are:

  • username
  • realname
  • alias[1…8]
  • email
  • phone[1…n]
  • platform[1…n]
  • group[1…n]
  • status
  • notes
  • token[1…n]
  • type[1…n]

Only the username field is mandatory; all other fields are optional, and can be arranged in any order (as shown in the CSV File Format section below). Duo usernames and username aliases should have unique values for each user.

username

Required. The Duo username. May include spaces, numbers, and punctuation.

If the provided username specified already exists in Duo as the username or username alias for another user, then the import updates that user. Note that this update operation may also affect the updated user's username aliases. If the provided username does not exist as a username or username alias, then the import creates a new user.

realname

The user's full name. May include spaces, numbers, and punctuation.

alias[1..8]

Specify up to eight additional usernames for each Duo user as alias1 to alias8. The Duo user may log in with either the user name or alias value while consuming a single Duo user license. May include spaces, numbers, and punctuation.

The username alias values must be unique. If the alias already exists for a different user as either the username or alias, the import fails to update the user.

email

The user's email address, as a correctly formatted SMTP address (user@example.com).

phone

The phone number may include spaces, dashes, or parentheses; all non-numeric characters are deleted during import. If the phone number includes an extension, the extension can be preceded by either a # or an x. A country code can be prepended to the phone number using a +.

Multiple phones can be attached to a user by including columns for phone1, phone2, etc.

platform

One of mobile, smartphone, landline, blackberry10, iphone, android, or windows phone. If a platform value is not defined for a phone, the default value is smartphone.

If you include a platform field, you must include a matching phone field; e.g., if you specify platform1, you must also specify phone1 (but you can specify a phone without specifying a platform for it).

Note: smartphone should only be chosen if you know that the user has a smartphone, but don't know which kind it is. If the user has a basic mobile phone or "feature phone," then chose mobile. Having an accurate value for this field will make it easier for your users to install and activate Duo Mobile.

group

Add the user to the specified Duo group upon import. The import process automatically creates the group if it doesn't exist (with "Active" status), with the user as a member.

A single user can be added to multiple groups by including columns for group1, group2, etc.

status

One of active, disabled, bypass, or delete. If the user's status is not specified, it defaults to active, requiring the user to use two-factor authentication.

Importing with status bypass allows that user to login without using two-factor authentication. A disabled user is not able to log in at all. Disabling a user invalidates existing remembered device sessions. The delete status removes the user from Duo on import. Learn more about Duo user status.

Note that the effective status for an imported user may be affected by the user's group memberships and the status assigned to those group(s). If, for example, a user was imported with bypass status and also as a member of a group with "Disabled" status, the user could not log in.

notes

Free-text information about the user, with a maximum length of 512 characters. May include spaces, numbers, and punctuation.

token1

The serial number of an OTP-generating hardware token to attach to the user. The token must already exist in Duo, that is, you must have already purchased and received Duo hardware tokens or have imported any third-party OTP token you want to assign to a user.

Requires a corresponding type1 value for the hardware token attached to the user by the import.

Multiple OTP hardware tokens can be attached to a user by including columns for token2 and type2, token3 and type3, etc.

type1

One of h6 for HOTP 6-digit, h8 for HOTP 8-digit, t6 for TOTP 6-digit, t8 for TOTP 8-digit, yk for YubiKey OTP, or d1 for Duo D-100 tokens.

Requires a corresponding token1 serial number value for the hardware token attached to the user by the import. The hardware token must already exist in Duo.

Multiple OTP hardware tokens can be attached to a user by including columns for token2 and type2, token3 and type3, etc.

CSV File Format

The first line of the CSV file (the header) specifies the fields to import. For example:

username,realname,alias1,email,status,phone1,platform1,phone2,group1,group2

Here are some examples of possible user entries in a CSV file using the example header. Notice that when there is no value for a field, the field is left blank.

username,realname,alias1,alias2,email,status,phone1,platform1,phone2,platform2,group1,group2,notes,token1,type1
jason,Jason Liu,jason@example.com,smithj3,jason@example.com,active,734-555-1234,iphone,734-555-3232,mobile,StdUsers,,,,
sally,Sally Jones,sally@example.com,joness5,sally@example.com,disabled,(734)-555-1235,android,(734)-555-4343,landline,StdUsers,,activate account after Dec 4,,
jack,Jack Cruz,jack@example.com,,jack@example.com,bypass,+17345554322,smartphone,,,StdUsers,NetAdmins,,101222,h6
sarah,Sarah James,sarah@example.com,,sarah@example.com,active,(734) 555-2235,iphone,(734) 555-3302 x3243,landline,StdUsers,,,,
bob,Bob Rogers,bob@example.com,rogersb,bob@example.com,active,734 555 3444,landline,734 223 9836,smartphone,StdUsers,,,,
mary,,,,,delete,,,,,,,,,

Here is a sample CSV file that you can use as a template for creating your own.

The CSV file size should not exceed 1 MB. If you need to import many users, split the information up into multiple CSV files of 1 MB or less and import each one separately.

Importing Users

Imported values overwrite existing values!

When you import a user with the same username as an existing Duo user who is not already managed by directory sync, the imported values for user details (like realname or email) always overwrite the existing values.

CSV import does not modify or update user attributes values imported by directory sync. CSV import can update attributes that aren't configured for import by directory sync, and can also update a user's status to "Active" or "Bypass" when the user's status is not "Disabled" before the import.

Once you've created your CSV file, you're ready to import your users.

  1. Log in to the Duo Admin Panel and click Users in the left sidebar. Click the Import Users navigation item under "Users" or from the "Users" page click the Import Users link near the top of the page.

  2. Click the Choose File button, browse to your CSV file, and select it. Click Upload to start the import process.

  3. If the CSV file contains any errors, the import attempt fails and you are shown a red error message like the one below. If you see an error message, then the attempt has failed and none of your users were imported. Correct the indicated errors and try the import again.

    CSV Import File Error
  4. Wait for the import to complete. Importing users via CSV can take some time, particularly if there are a large number of entries. You can leave the Import Users page running in the background. Periodically check back or refresh the page for progress updates, which will appear in a bar near the top of the Import Users page.

    Note: Only one CSV import can be running at any given time.

  5. After the CSV import is finished, a success message at the top of the Duo Admin Panel reports the results:

    Import Status

There are few circumstances under which an import can succeed even though updates to one or more accounts failed. An example of this is attempting to delete an account that does not exist. These will be noted in the success message.

Updating Users

Remember: When you import a user with the same username as an existing Duo user, values for user details specified in the CSV file (like realname or email) always overwrite the existing values.

For example, suppose you have a Duo user with the username TestUser1 who has no other information associated with the account. If you were to import a CSV containing a row with the same username (TestUser1), but this time also including a real name, username alias, email address, phone number, etc., this information would replace the existing (blank) details for that user, create a new phone with the imported number and platform, and associate that new phone with the existing user.

username,realname,alias1,email,status,phone1,platform1
TestUser1,Test User 1,tuser1,testuser1@example.com,,734-555-1234,Android

The situation is the same if the Duo user has existing information. Suppose some properties for TestUser1 are already populated, like username alias, real name, email address, phone numbers, groups, etc. Now you want to add this user to a new group, TestGroup1. If you modify your CSV to include this new group value for TestUser1 (but leave all other values as they were), the user is added to the new group while keeping all other information intact. This can be done for any number of users in a CSV file, and for any of the fields.

username,realname,alias1,email,status,phone1,platform1,group1
TestUser1,Test User 1,tuser1,testuser1@example.com,,734-555-1234,Android,TestGroup1

Note that you can't remove username aliases, group memberships, or attached phones for a user via import. CSV import can only add additional aliases, group memberships, and phones.

Deleting Users

If you want to delete an existing Duo user, you can do so by setting the user's status to delete in the CSV file. If that user is the only user attached to a specific phone, then the phone will also be deleted from Duo when the CSV file is imported.

username,status
jason,delete
sally,delete
jack,delete
mary,delete

Activating Devices for Newly Imported Users

After importing new users, the next step is to activate their devices for use with Duo. If you defined the users' device platforms as part of the import, then the Users page displays a bar indicating that some users have not yet activated Duo Mobile. Clicking the link in this bar starts the process of sending activation links. You can choose which users you want to receive links, and whether to send the activation via email or text.

Activation Links

For more information on user activation for imported users, see Activating Duo Mobile After Enrollment.

Troubleshooting

Need some help? Try searching our Knowledge Base articles or Community discussions. For further assistance, contact Support.