Support Desk

Mi-Token has developed a command line to create and assign soft-tokens to users in the domain. This tool can do so for a single user or in batches using a text file as input.

The tool requires the Mi-token API service to work, therefore, the program will need an API client key.

Please download and unzip the archive from this article. Unzip it anywhere you see fit as long as it allows the user running it to read and write data in the same directory as the binaries.

Configuration

Locate the MiToken-ST-CommandLine-Utilities.exe.config file and open it with any text editor, for instance, Notepad or Notepad++.

Under the <appSettings> tag, there are two configuration groups: API and EMAIL.

API settings

In these tags, set the IP address or server's name where the Mi-Token API is installed. Set the API key and the domain name of your organization. Use the short version of the domain name, i.e., if your domain is contoso.com, just type contoso.

For instance:

    <add key="APIServer" value="192.168.0.1" />
    <add key="APIKey" value="C48AE2BB099D751E18B4B8D6FB60D78CF3C755A85CD91CE1CEE5147A95DF31BB" />
    <add key="domain" value="contoso" />

Create an API Key

The API Key is retrieved from the Mi-Token-enabled server. Open the Users and Computers Window, right-click the tokens node, and select properties.

In the auxiliary dialog, click the API Clients tab:

Click "Add..."

In the appearing window, Give the key a name in the Certificate name input field, for instance: Bulk tokens creator.

Check the Allow management checkbox and the Isolate to a partition (required for management) checkbox. Leave the rest of the fields untouched.

Once the settings have been established, click New Key. You will see the Certificate text area populate. Select and copy the string shown:

Select and copy the string, Click save. Next, paste the string in the APIKey entry in the configuration file for the command line tools.

    <add key="APIServer" value="192.168.0.1" />
    <add key="APIKey" value="PASTE_THE_KEY_HERE" />
    <add key="domain" value="contoso" />

Email settings

For each softoken created, a provisioning URL is provided, the same way it occurs when creating the token manually from the management console or the Self-service provisioning portal.

The command line tool will automatically send an email with the provisioning URL for the defined username and email address. The configuration entries are as follows:

    <add key="mail_subject" value="A new soft-token has been created for you" />
    <add key="mail_hostname" value="mail_server" />
    <add key="mail_user" value="user_account" />
    <add key="mail_passwd" value="user_password" />
    <add key="mail_port" value="587" />
    <add key="mail_enableSSL" value="false" />
    <add key="sendEmail" value="true" />

mail_subject is a fixed text that will be used as the message subject.

mail_hostname corresponds to the hostname of your SMTP server.

mail_user is the user account that will send the email.

mail_password is the password for the email account. Please treat this carefully, as the password is stored as plain text.

mail_port is the port defined for the SMTP service.

mail_enableSSL is a boolean value that, as its name implies, enables or disables a connection to the mail server using SSL.

sendEmail is a boolean that enables or disables sending an email message after the token is created and assigned. Leave this value as true.

Running the program

Once you have configured the tool, open a command line and navigate to the installation directory.

New soft-token for a user

Use the following command:

MiToken-ST-CommandLine-Utilities.exe --user=<username> --email=<email>

<username> corresponds to the username as defined in the domain.

<email> is the user's email address recipient to whom the message will be sent.

For example

MiToken-ST-CommandLine-Utilities.exe --user=ivanvega --email=ivanv@mi-token.io

The following is a sample output of the program:

The output shows the serial number of the soft-token that you later can see in the Users and Computers window in the Token management server:

Create soft-tokens for multiple users in batch

The tool can process a text file that contains a list of usernames and email addresses, with the following format:

username,email address
username,email address
...
username,email address

For example:

Use the following command:

MiToken-ST-CommandLine-Utilities.exe --file=<path>

<path> corresponds to the full path of the file containing the list of pairs username-email address to be processed.

For example

MiToken-ST-CommandLine-Utilities.exe --file=z:\bulktoken.txt

The following is a sample output of the command using a text file as input:

As shown, the program will process each line in the file, create and assign a token for the intended username, and send an email message with the URL for provisioning the token.

Email message

The current version of this tool sends a fixed message. If you need a particular version, please contact our support team or your designated sales associate.

The following is a sample message:

Considerations

The program does not validate if the given username or email address exists. It will try to create a soft-token and send the email message every time.

The program does not validate if the given username already has one token assigned.

Bulk token assignment via CSV file

The command line tools can assign tokens to users getting the data from a CSV file with the format:

username,tokenserial

The command line arguments are as follows:

MiToken-ST-CommandLine-Utilities.exe --csv-token-assign --csv-token-file=z:\assign_tokens.csv

The program will read each line and try to assign the tokens to the given user. It is important to note that the tool will not validate if the given user name or token serial exists. If they don't, the tool will report unable to assign the token. Similarly, suppose the token has already been assigned, particularly with hardware tokens. In that case, the tool will report an error trying to assign it and not finding it, as the tool looks for unassigned hardware tokens.

For software tokens, put in the file the token serial corresponding to the UID of a given unit, for instance, the token shown in the AD Users and Computer window as:

It should be referenced in the CSV file as:

ivanvega,dec5d529-7666-4f2a-93f3-fed1876b6b38

In the case of Yubico YubiKeys and LCD tokens, put the entire name of the token in the file, for instance:

Should appear in the file as:

ivanvega,YubiKey 13668065

The following is a sample output ot the bulk token assignment functionality:

Final notes

We love feedback!

Please let us know how we can improve our tools.