File Coverage

blib/lib/Net/Duo/Admin.pm

Criterion	Covered	Total	%
statement	57	58	98.2
branch	8	10	80.0
condition			n/a
subroutine	12	12	100.0
pod	6	6	100.0
total	83	86	96.5

# Perl interface for the Duo Admin API.
#
# This Perl module collection provides a Perl interface to the Admin API
# integration for the Duo multifactor authentication service
# (https://www.duosecurity.com/).  It differs from the Perl API sample code in
# that it wraps all the returned data structures in objects with method calls,
# abstracts some of the API details, and throws rich exceptions rather than
# requiring the caller deal with JSON data structures directly.

package Net::Duo::Admin 1.01;

use 5.014;
use strict;
use warnings;

use parent qw(Net::Duo);

use Net::Duo::Admin::Integration;
use Net::Duo::Admin::User;

##############################################################################
# Admin API methods
##############################################################################

# Retrieve all integrations associated with a Duo account.
#
# $self - The Net::Duo::Admin object
#
# Returns: List of Net::Duo::Admin::Integration objects
#  Throws: Net::Duo::Exception on failure
sub integrations {
    my ($self) = @_;

    # Make the Duo call and get the decoded result.
    my $result = $self->call_json('GET', '/admin/v1/integrations');

    # Convert the returned integrations into Net::Duo::Admin::Integration
    # objects.
    my @integrations;
    for my $integration (@{$result}) {
        my $object = Net::Duo::Admin::Integration->new($self, $integration);
        push(@integrations, $object);
    }
    return @integrations;
}

# Retrieve logs of administrative actions.  At most 1000 entries are returned,
# so the caller may need to call this repeatedly with different mintime
# parameters to retrieve all of the logs.
#
# $self    - The Net::Duo::Admin object
# $mintime - Only return records with a timestamp after this (optional)
#
# Returns: A list of log entries, each of which is a hash reference with keys:
#            timestamp   - Time of event in seconds since epoch
#            username    - Admin username or API for changes via API
#            action      - The action taken
#            object      - The object on which the action was performed
#            description - The details of what was changed
#  Throws: Net::Duo::Exception on failure
sub logs_administrator {
    my ($self, $mintime) = @_;

    # Make the Duo call and get the decoded result.
    my $args   = defined($mintime) ? { mintime => $mintime } : {};
    my $uri    = '/admin/v1/logs/administrator';
    my $result = $self->call_json('GET', $uri, $args);

    # Return the result as a list.
    return @{$result};
}

# Retrieve authentication logs.  At most 1000 entries are returned, so the
# caller may need to call this repeatedly with different mintime parameters to
# retrieve all of the logs.
#
# $self    - The Net::Duo::Admin object
# $mintime - Only return records with a timestamp after this (optional)
#
# Returns: A list of log entries, each of which is a hash reference with keys:
#            timestamp   - Time of event in seconds since epoch
#            username    - The authenticating username
#            factor      - The authentication factor
#            result      - The result of the authentication
#            ip          - IP address from which the request originated
#            integration - Integration name attempting the authentication
#  Throws: Net::Duo::Exception on failure
sub logs_authentication {
    my ($self, $mintime) = @_;

    # Make the Duo call and get the decoded result.
    my $args   = defined($mintime) ? { mintime => $mintime } : {};
    my $uri    = '/admin/v1/logs/authentication';
    my $result = $self->call_json('GET', $uri, $args);

    # Return the result as a list.
    return @{$result};
}

# Retrieve telephony logs.  At most 1000 entries are returned, so the caller
# may need to call this repeatedly with different mintime parameters to
# retrieve all of the logs.
#
# $self    - The Net::Duo::Admin object
# $mintime - Only return records with a timestamp after this (optional)
#
# Returns: A list of log entries, each of which is a hash reference with keys:
#            timestamp - Time of event in seconds since epoch
#            context   - How this telephony event was initiated
#            type      - The event type
#            phone     - The phone number for this event
#            credits   - How many telephony credits this event cost
#  Throws: Net::Duo::Exception on failure
sub logs_telephony {
    my ($self, $mintime) = @_;

    # Make the Duo call and get the decoded result.
    my $args   = defined($mintime) ? { mintime => $mintime } : {};
    my $uri    = '/admin/v1/logs/telephony';
    my $result = $self->call_json('GET', $uri, $args);

    # Return the result as a list.
    return @{$result};
}

# Retrieve a single user by username.  An empty reply indicates that no user
# by that username exists.
#
# $self     - The Net::Duo::Admin object
# $username - Username whose record to retrieve
#
# Returns: A single Net::Duo::User object or undef
#  Throws: Net::Duo::Exception on failure
sub user {
    my ($self, $username) = @_;

    # Make the Duo call and get the decoded result.
    my $args = { username => $username };
    my $result = $self->call_json('GET', '/admin/v1/users', $args);

    # Convert the returned user into a Net::Duo::Admin::User object.
    if (@{$result}) {
        return Net::Duo::Admin::User->new($self, $result->[0]);
    } else {
        return;
    }
}

# Retrieve all users associated with a Duo account.
#
# $self     - The Net::Duo::Admin object
# $username - Retrieve the record for only this user (optional)
#
# Returns: List of Net::Duo::User objects if no parameter is given
#          A single Net::Duo::User object if $username is given and found
#          undef if $username is given and not found
#  Throws: Net::Duo::Exception on failure
sub users {
    my ($self, $username) = @_;

    # Make the Duo call and get the decoded result.
    my $args = $username ? { username => $username } : undef;
    my $result = $self->call_json('GET', '/admin/v1/users', $args);

    # Convert the returned users into Net::Duo::Admin::User objects.
    my @users;
    for my $user (@{$result}) {
        push(@users, Net::Duo::Admin::User->new($self, $user));
    }
    return @users;
}

1;
__END__