Provided by: libnet-duo-perl_1.02-3_all bug

NAME

       Net::Duo::Admin - Perl interface for the Duo Admin API

SYNOPSIS

           my $duo = Net::Duo::Admin->new({ key_file => '/path/to/keys.json' });
           my @users = $duo->users;

REQUIREMENTS

       Perl 5.14 or later and the modules HTTP::Request and HTTP::Response (part of
       HTTP::Message), JSON, LWP (also known as libwww-perl), Perl6::Slurp, Sub::Install, and
       URI::Escape (part of URI), all of which are available from CPAN.

DESCRIPTION

       Net::Duo::Admin is an implementation of the Duo Admin REST API for Perl.  Method calls
       correspond to endpoints in the REST API.  Its goal is to provide a native, natural
       interface for all Duo operations in the API from inside Perl, while abstracting away as
       many details of the API as can be reasonably handled automatically.

       Currently, only a tiny number of available methods are implemented.

       For calls that return complex data structures, the return from the call will generally be
       an object in the Net::Duo::Admin namespace.  These objects all have methods matching the
       name of the field in the Duo API documentation that returns that field value.  Where it
       makes sense, there will also be a method with the same name but with "set_" prepended that
       changes that value.  No changes are made to the Duo record itself until the commit()
       method is called on the object, which will make the underlying Duo API call to update the
       data.

       Some objects have associated lists of other objects.  For example, a user has a list of
       phones and a list of tokens.  Wherever this pattern occurs, new objects can be added to
       that list with a method starting with "add_" and removed with a method starting with
       "remove_".  These changes are pushed to Duo immediately and do not wait for the next
       commit().

       On failure, all methods throw a Net::Duo::Exception object.  This can be interpolated into
       a string for a simple error message, or inspected with method calls for more details.
       This is also true of all methods in all objects in the Net::Duo namespace.

CLASS METHODS

       new(ARGS)
           Create a new Net::Duo::Admin object, which is used for all subsequent calls.  This
           constructor is inherited from Net::Duo.  See Net::Duo for documentation of the
           possible arguments.

INSTANCE METHODS

       integrations()
           Retrieves all the integrations currently present in this Duo account and returns them
           as a list of Net::Duo::Admin::Integration objects.  Be aware that this list may be
           quite long if the Duo account supports many integrations, and the entire list is read
           into memory.

       logs_administrator([MINTIME])
           Returns a list of administrative actions.  Each member of this list will be a
           reference to a hash with the following keys:

           timestamp
               The time of the event in seconds since UNIX epoch.

           username
               The username of the administrator, or "API" if the action was performed via the
               Admin API.

           action
               The administrator action.  See the Duo Admin API documentation for a full list of
               valid values.

           object
               An identifier for the object that was acted on.  What fields are used as an
               identifier will vary by type of object.

           description
               The details of what was changed.

           At most 1,000 log entries will be returned.  If MINTIME is provided, only records with
           a time stamp after MINTIME will be returned.  All records can therefore be retrieved
           by calling this method repeatedly, first with no MINTIME and then with MINTIME
           matching the timestamp of the last returned record from the previous call.

       logs_authentication([MINTIME])
           Returns a list of authentication attempts.  Each member of the list will be a
           reference to a hash with the following keys:

           timestamp
               The time of the event in seconds since UNIX epoch.

           username
               The authenticating user's username.

           factor
               The authentication factor, chosen from "phone call", "passcode", "bypass code",
               "sms passcode", "sms refresh", or "duo push".

           result
               The result of the authentication, chosen from "success", "failure", "error", or
               "fraud".

           ip  The IP address from which the authentication attempt originated.

           integration
               The name of the integration from which the authentication attempt originated.

           At most 1,000 authentication log entries will be returned.  If MINTIME is provided,
           only records with a time stamp after MINTIME will be returned.  All records can
           therefore be retrieved by calling this method repeatedly, first with no MINTIME and
           then with MINTIME matching the timestamp of the last returned record from the previous
           call.

       logs_telephony([MINTIME])
           Returns a list of telephony events.  Each member of this list will be a reference to a
           hash with the following keys:

           timestamp
               The time of the event in seconds since UNIX epoch.

           context
               How this telephony event was initiated.  This will be one of "administrator
               login", "authentication", "enrollment", or "verify".

           type
               The event type.  One of "sms" or "phone".

           phone
               The phone number that initiated this event.

           credits
               How many telephony credits this event cost.

           At most 1,000 log entries will be returned.  If MINTIME is provided, only records with
           a time stamp after MINTIME will be returned.  All records can therefore be retrieved
           by calling this method repeatedly, first with no MINTIME and then with MINTIME
           matching the timestamp of the last returned record from the previous call.

       user(USERNAME)
           Retrieves a single user by username and returns it as a Net::Duo::Admin::User object
           if found.  If no user with that username exists, returns undef, and does not throw an
           exception.

       users()
           Retrieves all the users currently present in this Duo account and returns them as a
           list of Net::Duo::Admin::User objects.  Be aware that this list may be quite long and
           consume a lot of resources for accounts with many users.

AUTHOR

       Russ Allbery <rra@cpan.org>

COPYRIGHT AND LICENSE

       Copyright 2014 The Board of Trustees of the Leland Stanford Junior University

       Copyright 2019 Russ Allbery <rra@cpan.org>

       Permission is hereby granted, free of charge, to any person obtaining a copy of this
       software and associated documentation files (the "Software"), to deal in the Software
       without restriction, including without limitation the rights to use, copy, modify, merge,
       publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
       to whom the Software is furnished to do so, subject to the following conditions:

       The above copyright notice and this permission notice shall be included in all copies or
       substantial portions of the Software.

       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
       INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
       PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
       FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
       OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
       DEALINGS IN THE SOFTWARE.

SEE ALSO

       Duo Auth API <https://www.duo.com/docs/authapi>

       This module is part of the Net::Duo distribution.  The current version of Net::Duo is
       available from CPAN, or directly from its web site at
       <https://www.eyrie.org/~eagle/software/net-duo/>.