The Import Users feature is used both to import batches of new users, and to update or delete existing users.
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.
Users created with the Import Users feature can include username aliases, email addresses, full names, groups, notes, and multiple phones or mobile devices. These users can be managed 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.
The CSV file can include many data fields for each Duo user.
The fields allowed in this CSV file are:
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.
notes values may include spaces, numbers, and punctuation.
Import up to four username aliases per user with
alias2, etc. columns. Username aliases provide additional login usernames for each user, using the same authentication factors and without consuming multiple Duo licenses per username. Be sure your username aliases represent user attributes with unique values, like email addresses or UPN usernames.
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
platform must be a value from the following list:
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.)
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. It will also be easier to administer your system.
Users can be organized into Duo groups by specifying a
group. A single user can be added to multiple groups by including columns for
group2, etc. If the CSV file lists groups that don't already exist in Duo, they are created automatically.
status must be (
delete). If the user's status is not specified, it defaults to
active, requiring the user to use two-factor authentication. If the status is set to
bypass, that user is able to login without using two-factor authentication. A
disabled user is not able to log in at all. (Learn more about Duo user statuses.) The
delete status removes the user from Duo on import.
notes field has a maximum length of 512 characters.
The first line of the CSV file (the header) specifies the fields to import. For example:
Here are some examples of possible user entries in this 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,alias3,alias4,email,status,phone1,platform1,phone2,group1,group2 jason,Jason Smith,firstname.lastname@example.org,email@example.com,jason.smith,smithj,firstname.lastname@example.org,,734-555-1234,Android,734-555-4343x222,Stdusers, sally,Sally Jones,email@example.com,,,,firstname.lastname@example.org,Bypass,734-555-1235,,,StdUsers, jack,Jack Johnson,email@example.com,,,,firstname.lastname@example.org,,734-555-4322,Mobile,440-555-1234,Stdusers,NetAdmins 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.
When you import a user with the same username as an existing Duo user, the imported values always overwrite the existing values.
Once you've created your CSV file, you're ready to import your users.
Log in to the Duo Admin Panel and click Users in the left sidebar.
Click the Import Users button near the top of the page. Now 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.
Remember: When you import a user with the same username as an existing Duo user, values specified in the CSV file 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) information for that user.
username,realname,alias1,email,status,phone1,platform1 TestUser1,Test User 1,tuser1,email@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. Note that you can't remove group memberships via CSV import.
username,realname,alias1,email,status,phone1,platform1,group1 TestUser1,Test User 1,tuser1,firstname.lastname@example.org,,734-555-1234,Android,TestGroup1
If you want to delete an existing Duo user, you can do so by setting the user's
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
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 Users After Enrollment.