Duo Security Python Client

The Admin module in duo_client_python is designed to automate the management of account-level elements within a Duo customer configuration. It provides programmatic access to manage the following resources:

• Users: Manage user accounts and attributes.
• Groups: Manage user groups.
• Phones/Tablets: Manage registered devices.
• Tokens: Manage authentication tokens.
• Application integrations: Manage Duo application settings.
• Policies: Manage security policies.
• Logs: Access and manage audit logs.

Python Versions

Supported versions: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12.

TLS Support

The client uses Python's ssl module and OpenSSL. Python 3.7 and higher provide support for both TLS 1.2 and TLS 1.3.

API Documentation Links

• Auth API: https://www.duosecurity.com/docs/authapi
• Admin API: https://www.duosecurity.com/docs/adminapi
• Subaccount access: https://duo.com/docs/adminapi#subaccounts

The Duo Auth API is intended for application developers who want to integrate Duo Multi-Factor Authentication (MFA) functionality directly into their own applications. It provides access to:

• User enrollment services
• Authentication services

Subaccount management (intended for Managed Service Partners to automate child account management) should be performed using the Admin module.

Important Deprecation Notice: While the Accounts client provides subaccount methods like get_child_accounts, create_account, and delete_account, these are deprecated and will be removed in a future release. Their functionality is frozen. For all new code, use the Admin module instead.

# Use Admin for subaccount management
# Avoid the deprecated Accounts client for these methods
# Methods include: get_child_accounts, create_account, delete_account

The Duo Auth API is designed for integrating user enrollment and authentication into custom third-party applications.

Key Integration Pattern:

1. The third-party application provides the user interface.
2. The application performs primary authentication for the user.
3. The application calls the Duo Auth API to initiate secure second-factor authentication (MFA).

Note that the examples provided in this repository use console/tty-based interactions to simulate the data collection required for functional interactions with the Duo Auth API.

The Duo Admin API is used for operational tasks related to Duo account management. Use these examples if you need to automate tasks such as:

• User management: Creating, updating, or deleting users.
• MFA device management: Managing user authentication devices.
• Integration management: Managing Duo integrations.
• Policy management: Configuring Duo security policies.
• Log extractions: Retrieving logs from Duo.
• Subaccount management: Managing subaccounts (primarily for Duo Managed Service Provider (MSP) partners). For subaccount examples, refer to the Accounts folder.

If you are contributing to the repository, clone the repo, set up a virtual environment, and install the requirements for both the library and development tools.

$ git clone https://github.com/duosecurity/duo_client_python.git
$ cd duo_client_python
$ virtualenv .env
$ source .env/bin/activate
$ pip install --requirement requirements.txt
$ pip install --requirement requirements-dev.txt
$ python setup.py install

To run the provided subaccount management examples, execute the Python scripts from the repository root or from within the specific example directory.

# From the repo root
python3 examples/Accounts/get_billing_and_telephony_credits.py

# Or from within the examples/Accounts/ folder
python3 get_billing_and_telephony_credits.py

To execute the provided Duo Auth API examples, you can run them from the repository root or from within the examples/Auth/ directory using a Python 3 interpreter.

# From the repository root
python3 examples/Auth/basic_user_mfa.py

# From within the examples/Auth/ folder
python3 basic_user_mfa.py

To install the Duo Python client for use in your system or environment, use pip to install the package from PyPI.

$ pip install duo-client

To run the provided Admin API examples, execute the Python scripts from either the repository root or from within the examples/Admin/ directory. For example, to run the report_users_and_phones.py script:

# From the repo root
python3 examples/Admin/report_users_and_phones.py

# Or, from within the examples/Admin/ folder
python3 report_users_and_phones.py