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 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 ( |
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 Multiple phones can be attached to a user by including columns for |
platform
|
One of If you include a Note: |
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 |
status
|
One of Importing with 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 |
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 Multiple OTP hardware tokens can be attached to a user by including columns for |
type1
|
One of Requires a corresponding Multiple OTP hardware tokens can be attached to a user by including columns for |
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
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.
-
Log in to the Duo Admin Panel and navigate to Users → Import Users in the left sidebar, or click the Import Users link near the top of the "Users" page.
-
Click the Choose File button, browse to your CSV file, and select it. Click Upload to start the import process.
-
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.
-
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.
-
After the CSV import is finished, a success message at the top of the Duo Admin Panel reports the results:
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,AndroidThe 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,TestGroup1Note that you can't remove username aliases, group memberships, hardware tokens, or attached phones for a user via import. CSV import can only add additional aliases, group memberships, hardware tokens, and phones to users.
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,deleteActivating 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.
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.