oracular (3) Wallet::Object::Duo.3pm.gz

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.

SEE ALSO

       Net::Duo(3), Wallet::Config(3), Wallet::Object::Base(3), wallet-backend(8)

       This module is part of the wallet system.  The current version is available from
       <https://www.eyrie.org/~eagle/software/wallet/>.

AUTHOR

       Russ Allbery <eagle@eyrie.org>