Duo Multi-Factor Authentication

From OSNEXUS Wiki
Jump to: navigation, search

Enabling Duo Multi-Factor Authentication Documentation v3

To enable multi-factor authentication using Duo, you must first create a Duo account. You can get a free trial for a Duo beyond account at Duo Security.

Once you have a Duo account set up, log in to the Duo admin dashboard. Click the ‘Applications’ tab and select ‘Protect an application’. In the search bar, search for Auth API and select the ‘Protect this Application' link. Now you will be shown your new API hostname, integration key, and secret key. These will be used to create your multi-factor authentication configuration.

Using the CLI tools:

To enable MFA for users, you must first create a multi-factor authentication configuration. You can use the following CLI tools:


qs multi-factor-auth-config-create --api-host=<API Hostname> --integration-key=<IntegrationKey> --secret-key=<Secret Key> --name=<Name>
            OR
qs mfa-config-create --api-host=<API Hostname> --integration-key=<Integration Key> --secret-key=<Secret Key> --name=<Name>


The API Hostname, Integration Key, and Secret Key are from your Duo Admin Dashboard. You must also supply a unique name for your configuration. Optionally, you may also supply a description. If you supply configuration keys which are not valid, the mfa config creation task will fail and an error will be thrown.


You can view your multi-factor authentication configurations using the following CLI tools:

qs multi-factor-auth-config-list
            OR
qs mfa-config-list
            OR
qs multi-factor-auth-config-get --mfa-config=<Name or ID>
            OR
qs mfa-config-get=<Name or ID>


With these last two, you may specify a specific multi-factor authentication configuration by supplying either its name or ID.


Assign/Unassign you multi-factor authentication configuration to specific users:

qs multi-factor-auth-set-user --mfa-config-user-mapping=<list of user:config mappings>
            OR
qs mfa-set-user --mfa-config-user-mapping=<list of use:config mappings>


The mfa-config mappings which are supplied as a comma delimited list should have the form “user1:config1,user2:config2,~user3,...” where a tilde (~) before the username signals the removal of a multi-factor authentication configuration from the specified user. In this case, the users mfa configuration will be set to an empty string and mfa will be disabled on the user account. Otherwise, the given mfa configuration will be assigned to the specified user and mfa will be enabled on the user account. If a user from the list already has the specified configuration, the user will not be modified.


You can change any multi-factor authentication configuration using the following commands:

qs multi-factor-auth-config-modify --mfa-config=<Name or ID> --secret-key=<New Secret Key> --name=<New Name> --description=<New Description>
            OR
qs mfa-config-modify --mfa-config=<Name or ID> --secret-key=<New Secret Key> --name=<New Name> --description=<New Description>


Specify the mfa config you would like to change by supplying either its name or ID. You can also supply either a new secret key, new name, new description, or any combination of the three. You cannot change the API Host or the Integration Key, as that would essentially be making a completely new mfa config. Delete a multi-factor authentication configuration with these commands:

qs multi-factor-auth-config-delete --mfa-config=<Name or ID>
            OR
qs mfa-config-delete --mfa-config=<Name or ID>


Specify which mfa config you would like to be deleted by supplying either its name or ID. This operation cannot be undone. When a mfa config is deleted, all user who have an association with this config will have their mfa config id field set to an empty string and their mfa mode set to NONE.

Using Multi-Factor Authentication for login:

Now that you understand how to create mfa configs and assign/unassign them to users, you can enable mfa on you chosen user(s).

qs user-modify --user=<Name or ID> --enable-mfa=<true or false> --mfa-config=<Name or ID>


To enable mfa on your chosen user(s), you must set the enable mfa flag to true.

Next you need to supply a mfa config to the user. You can do this in a couple different ways. One way is using the mfa-config-set-user CLI mentioned earlier. Another is to specify the name or id of the config while modifying the user. If the supplied name or ID does not relate to an existing mfa config, an error will be thrown.

If a enable-mfa is set to false and a mfa config is given, the mfa config will be ignored and mfa will be disabled for the given user.

Now that you have a user (or users) with mfa enabled and have a mfa config associated with their account, next time that user logs in, it will be prompted to enroll with DUO. The user will follow the given URL to enroll. This is the last step in the mfa set up process. Now every time the user logs in, he/she will be given the choice between authenticating via push notification, sms, phone call, or passcode.

Disable Admin Multi-Factor Authentication:

If the admin account gets locked out duo to multi-factor authentication failure, there is a way to disable mfa for only the admin account. This may occur when the admin has mfa enabled and the secret key is reset from the duo admin panel. This creates a scenario where the mfa config which is saved in quantastor is out of date, but the admin can't login to change it because logging in is attempting to use the now invalid mfa config.

To disable mfa from the admin account, one must stop the quantastor service and run ‘./qs_service --disable-mfa’. After this has been run, the quantastor service may be restarted and the admin can log in, bypassing the mfa process.

Using the Web UI:

All that can be accomplished using the CLI tools can also be accomplished using the Web UI. The tools to Create, Modify, Delete, and Assign/Unassign mfa configs are under the User & Groups tab on the right most section of the ribbon bar. They can also be accessed via the Multi-Factor Authentication Manager, which can be found under the Users section of the ribbon bar.

To enable mfa for users, you can use the User Modify dialogs. You can also create a new user and set these fields during creation.

(See Appendix A below for screenshots of various MFA components in Web UI)

Duo Multi-Factor Authentication Login Process:

Once you have created at least one mfa config, assigned it to a user, and enabled mfa for that user, you are ready to login using the new mfa login process. To do so, proceed with logging in as normal by entering a username and password and clicking the ‘Login’ button. If this is your first time logging in with this specific mfa config, you will be prompted at login that enrollment with Duo is required. Follow the given url to enroll.

After enrollment, you may attempt another login. You will need to click the ‘Cancel’ button in order to restart the login process. After entering username and password and clicking the ‘Login’ button, a new dialog will appear. After the users registered authentication devices are gathered, the user may choose to use any of the available devices for authentication. If the user would not like to use a device or if the user is using a passcode not associated with a device, the ‘N/A’ option may be chosen.

Once a device has been chosen, the user must choose a mode of authentication. The mode options which are appropriate for the chosen device will be listed in the dropdown. After making a selection, the user can click ‘Send Authentication Request’ to proceed.

If SMS is the chosen authentication mode, the user will be sent a passcode via SMS to the chosen device. Once the user has received the passcode, they may enter it into the ‘Passcode’ field in the web UI and click ‘Enter Passcode’. If they did not receive the passcodes or if they would like new passcodes, they may click the ‘Resend Passcodes’ button to receive a new passcode.

If Phone Call is the chosen authentication mode, the user will receive a phone call on the chosen device. Once the user has received the phone call, they can follow the given instructions to either authenticate, which will log them into their quantastor account, or deny authentication.

If Push is the chosen authentication mode, the user will receive a push notification on the chosen device. Once the user has received the push notification, they may choose to authenticate, which will log them into their quantastor account, or deny authentication.

Finally, if Passcode is the chosen authentication mode, the user can enter their code into the ‘Passcode’ field in the Web UI before clicking the ‘Send Authentication Request’ button.

(See Appendix B below for screenshots of the new MFA login process)

Appendix A

1. Multi-Factor Authentication Configuration Manipulation Icons in Ribbon Bar

Ribbon Bar.png
Icons for multi-factor authentication configuration manipulation can be found on the far right of the ribbon bar under the Users & Groups tab. Multi-factor authentication configuration manipulation can also be done from the Multi-Factor Auth Manager, which can be launched from the ribbon bar, under the Users section on the left.


2. Multi-Factor Authentication Configuration Manager

MFA Manager.png
All multi-factor authentication configuration manipulation can be handled from the Multi-Factor Auth Config Manager. To delete multiple configurations at once, check the check boxes next to the configurations you would like to delete, then hit the delete button.


3. Multi-Factor Authentication Configuration Create

Create Auth Cnfg.png
Clicking the ‘Create’ icon in the ribbon bar in the multi-factor authentication configuration panel will open the multi-factor auth config create dialog.


4. Multi-Factor Authentication Configuration Modify

Modify Auth Cnfg.png
Clicking the ‘Modify’ icon in the ribbon bar in the multi-factor authentication configuration panel will open the multi-factor auth config modify dialog. You can choose to modify any of the existing mfa configs from the drop down menu. You may only modify the name, description, or secret key.


5. Multi-Factor Authentication Configuration Delete

MFA Config Delete.jpg
Clicking the ‘Delete’ icon in the ribbon bar in the multi-factor authentication configuration panel will open the multi-factor auth config delete dialog. You can choose to delete any of the existing mfa configs from the drop down menu.


6. Multi-Factor Authentication Configuration Assign/Unassign

Assignunassigndialog.png
Clicking the ‘Assign/Unassign’ icon from the ribbon bar in the multi-factor authentication configuration panel or from the Multi-Factor Auth Manager dialog will open the multi-factor auth config assign/unassign dialog. Here you can choose a configuration for each of the users in the system. To change a configuration for a given user, select the desired config from the drop down under the Multi-Factor Auth Config column in the specific users row. If you would like to disable mfa for a given user, select the ‘Disabled’ option from the drop down.


7. User Create

User add enable mfa checkbox.png
User add enable mfa tooltip.png
User add select config.png
When creating a new user, the ‘Enable Multi-Factor Auth’ checkbox will be left unchecked by default. To enable mfa for this new user, check the checkbox next to ‘Enable Multi-Factor Auth’. After checking the checkbox, select the mfa config you would like to assign to this user from the list of existing mfa configs in the mfa config drop down.


8. User Modify

User modify enable mfa checkbox.png
User modify enable mfa tooltip.png
User modify select config.png
When modifying an existing user, the mfa mode drop down will auto select which mode the user is currently set to. To change this, select the desired mode form the MFA Mode drop down. If a mode other than Disabled is selected, you will need to select the mfa config which you would like to assign to this user as well. You may select any of the existing mfa configs from the mfa config drop down.

Appendix B

1. Duo Enrollment

Getting devices.png


2. Duo Push

Getting devices.pngCats phone choose auth mode.png
Selecting push auth mode.pngSelect push auth mode.png

IMG 1540.PNG


3. Duo Call

Getting devices.pngCats phone choose auth mode.png
Select phone auth mode.pngAuth via phonecall.png


4. Duo SMS

Getting devices.pngCats phone choose auth mode.png
Select sms auth mode.pngNew sms passcodes sent.png
IMG 1538.PNGProcessing auth request via sms.png


5. Duo Passcode

Getting devices.pngCats phone choose auth mode.png
IMG 1539.pngAuth processing via passcode.png