NAME

Wallet::Object::Duo - Duo integration object implementation for wallet

SYNOPSIS

    my @name = qw(duo host.example.com);
    my @trace = ($user, $host, time);
    my $object = Wallet::Object::Duo->create (@name, $schema, @trace);
    my $config = $object->get (@trace);
    $object->destroy (@trace);

DESCRIPTION

Wallet::Object::Duo is a representation of Duo integrations the wallet. It implements the wallet object API and provides the necessary glue to create a Duo integration, return a configuration file containing the key and API information for that integration, and delete the integration from Duo when the wallet object is destroyed.

Usually you will want to use one of the subclasses of this module, which override the output to give you a configuration fragment suited for a specific application type. However, you can always use this module for generic integrations where you don't mind massaging the output into the configuration for the application using Duo.

This object can be retrieved repeatedly without changing the secret key, matching Duo's native behavior with integrations. To change the keys of the integration, delete it and recreate it.

To use this object, at least one configuration parameter must be set. See Wallet::Config for details on supported configuration parameters and information about how to set wallet configuration.

METHODS

This object mostly inherits from Wallet::Object::Base. See the documentation for that class for all generic methods. Below are only those methods that are overridden or behave specially for this implementation.

create(TYPE, NAME, DBH, PRINCIPAL, HOSTNAME [, DATETIME, INTEGRATION_TYPE])

This is a class method and should be called on the Wallet::Object::Duo class. It creates a new object with the given TYPE and NAME (TYPE is normally "duo" and must be for the rest of the wallet system to use the right class, but this module doesn't check for ease of subclassing), using DBH as the handle to the wallet metadata database. PRINCIPAL, HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is creating the object. If DATETIME isn't given, the current time is used.

When a new Duo integration object is created, a new integration will be created in the configured Duo account and the integration key will be stored in the wallet object. If the integration already exists, create() will fail. If an integration type isn't given, the new integration's type is controlled by the DUO_TYPE configuration variable, which defaults to "unix". See Wallet::Config for more information.

If create() fails, it throws an exception.

destroy(PRINCIPAL, HOSTNAME [, DATETIME])

Destroys a Duo integration object by removing it from the database and deleting the integration from Duo. If deleting the Duo integration fails, destroy() fails. Returns true on success and false on failure. The caller should call error() to get the error message after a failure. PRINCIPAL, HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is destroying the object. If DATETIME isn't given, the current time is used.

get(PRINCIPAL, HOSTNAME [, DATETIME])

Retrieves the configuration information for the Duo integration and returns that information in the format expected by the configuration file for the Duo UNIX integration. Returns undef on failure. The caller should call error() to get the error message if get() returns undef.

The returned configuration look look like:

    [duo]
    ikey = <integration-key>
    skey = <secret-key>
    host = <api-hostname>

The "host" parameter will be taken from the configuration file pointed to by the DUO_KEY_FILE configuration variable.

PRINCIPAL, HOSTNAME, and DATETIME are stored as history information. PRINCIPAL should be the user who is downloading the keytab. If DATETIME isn't given, the current time is used.

LIMITATIONS

Only one Duo account is supported for a given wallet implementation.

AUTHOR

Russ Allbery <eagle@eyrie.org>

2024-11-12

perl v5.40.0