As a Duo specialist, I often talk with customers that would like to add Yubikey hardware tokens at scale before assigning them to users that will then use their assigned token for multi-factor authentication. Duo currently has a few ways in which administrators can add hardware tokens:

• .CSV upload within the Duo Admin Panel
• User self-enrolment with a Yubikey
• Using the Admin API

Now, while many Duo administrators are happy to put together a .csv file containing all the required information to bulk add tokens to Duo, the challenge often comes when administrators need to assign hundreds of tokens to their users. Unfortunately, at the time of writing this, Duo doesn’t have many options within the Duo Admin Panel to assign tokens to multiple users at once. In fact, the only methods available are to use a .csv file providing the tokens have already been added or manually assign tokens to users one-by-one. These methods can be laborious and as a result, this could make customers think twice about using hardware tokens as an authentication method.

The good news, however, is that we can utilise the Admin API to bulk assign tokens to users, saving Duo admins a lot of time and making their experience with Duo that little bit better. The bad news for some admins is that they might not be proficient with programming and therefore choose to avoid API-related tasks. If you fall into that bucket of people, fear not because in this article I will provide you with all the information you need to utilise the Admin API to bulk assign tokens.

to users in Cisco Duo. Although, the focus of this article will highlight the assignment of Yubikeys to users within Duo, the code is not restricted to just Yubikeys and therefore other hardware tokens should also work.

Install Duo_Client_Python

Install Duo_Client_Python onto your client using the following commands and instructions here.

Configure the Duo Admin API

To get started, access the Duo Admin panel and navigate to Applications > Protect an application and search for and select Admin API

Grant read and write to resources, check that you’re happy with the rest of the settings and complete the configuration by saving changes.

The Integration Key, Secret Key and API Hostname will be required in the next step. Please keep these details to yourself as sharing them could compromise your deployment.

Create a Python File (.py) for the IKEY, SKEY and API Hostname

On the client that you will use to execute the following Python scripts, create a separate Python file for your integration key (IKEY), secret key (SKEY) and API hostname. The following syntax has been used as an example from a Debian-based machine. Assuming that you’re using a Linux client, ensure that you’re in a suitable directory before running the following commands.

nano my_duo_keys.py

Add the following text, replacing the <REPLACE_ME> with the relevant information.

DUO_IKEY = "<REPLACE_ME>"
DUO_SKEY = "<REPLACE_ME>"
DUO_APIHOSTNAME = "<REPLACE_ME>"

Save the file.

Create a .csv File Mapping Users to Tokens

Create a .csv file to map Duo users to tokens that have already been added to the Duo deployment. The three fields required are:

• The tokens serial number
• The username of each user
• The token type

Below is an exam of the .csv file format.

tokenserial,username,tokentype
12345678,networkwizkid,yk

Once all users have been mapped to hardware tokens, save the .csv file in the same file location so that it will be easy to reference in the python script.

Create the Python Script

The following python script will be used to bulk assign hardware tokens to users in Duo. Note that you will need to change the fields <CHANGE_ME> to match the file names of your .csv files.

# This script can be used to bulk assign tokens to users based on the data contained within a .CSV file. Both the tokens and users need to be already in Duo.

import duo_client
from datetime import datetime
import csv
from my_duo_keys import DUO_IKEY, DUO_SKEY, DUO_APIHOSTNAME

# Initialize Duo Admin API
admin_api = duo_client.Admin(
    ikey=DUO_IKEY,
    skey=DUO_SKEY,
    host=DUO_APIHOSTNAME
)

def get_current_time():
    now = datetime.now()
    return now.strftime('%d-%m-%Y %H:%M:%S')

def assign_tokens(csv_filename):
    print("\n-------------------------------------------------------------------")
    print("************ ASSIGNING HARDWARE TOKENS ************")
    print(f"Time Started: {get_current_time()}")
    print("-------------------------------------------------------------------")

    success = 0
    failed = 0

    with open(csv_filename, newline='') as csvfile:
        reader = csv.reader(csvfile)
        next(reader, None)

        for count, row in enumerate(reader, start=1):
            tokenserial, username, tokentype = row[:3]

            try:

                user_id = admin_api.get_users_by_name(username=username)[0]['user_id']
                token_id = admin_api.get_tokens_by_serial(type=tokentype, serial=tokenserial)[0]['token_id']
                admin_api.add_user_token(user_id=user_id, token_id=token_id)

                print(f"({count}) SN: {tokenserial} | User: {username} ...SUCCESS!")
                success += 1
            except Exception as e:
                print(f"({count}) SN: {tokenserial} | User: {username} ...FAILED!")
                failed += 1

    print("\n-------------------------------------------------------------------")
    print(f"Tokens Successfully Assigned: {success}")
    if failed > 0:
        print(f"Tokens Failed to be Assigned: {failed}")
        print("** Please check username or SN for errors.")
    print(f"Time Finished: {get_current_time()}")
    print("-------------------------------------------------------------------")

if __name__ == "__main__":
    csv_filename = '<CHANGE_ME>'
    assign_tokens(csv_filename)

Run the Script

Once you’re satisfied with the above python script, you should be ready to run it. Once the script has been run, you will be notified of the results as shown below.

-------------------------------------------------------------------
************ ASSIGNING HARDWARE TOKENS ************
Time Started: 07-09-2023 00:13:25
-------------------------------------------------------------------
(1) SN: 12345678 | User: networkwizkid ...SUCCESS!
(2) SN: 91011121 | User: granite ...SUCCESS!

-------------------------------------------------------------------
Tokens Successfully Assigned: 2
Time Finished: 07-09-2023 00:13:26
-------------------------------------------------------------------

You can now access the Duo Admin Panel and verify the changes have been successful. Firstly, navigate to the Administrator Actions. Reports > Administrator Actions. You will be able to see that the Admin API has made some changes.

Next, you can take a look at all your hardware tokens and see whether they are assigned. Navigate to 2FA Devices > Hardware Tokens.

Thats it! You’ve successfully bulk assigned multiple hardware tokens to your Duo users and saved a lot of time.

To support this article, please like and share, it helps creators like me a lot!

Useful Links

Duo Admin API | Duo Security

wiizkiid/Network-Wizkid-Scripts (github.com)