File Coverage

blib/lib/Net/Duo/Auth.pm

Criterion	Covered	Total	%
statement	62	75	82.6
branch	13	20	65.0
condition	10	13	76.9
subroutine	12	12	100.0
pod	4	4	100.0
total	101	124	81.4

# Perl interface for the Duo Auth API.
#
# This Perl module collection provides a Perl interface to the Auth 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::Auth 1.01;

use 5.014;
use strict;
use warnings;

use parent qw(Net::Duo);

use Carp qw(croak);
use Net::Duo::Auth::Async;
use URI::Escape qw(uri_escape_utf8);

# All dies are of constructed objects, which perlcritic misdiagnoses.
## no critic (ErrorHandling::RequireCarping)

##############################################################################
# Auth API methods
##############################################################################

# Helper function to validate and canonicalize arguments to the auth and
# auth_async functions.  Ensures that the arguments meet the calling contract
# for the auth method (see below) and returns a reference to a new hash with
# the canonicalized copy of data.
#
# $self     - The Net::Duo::Auth object
# $args_ref - Reference to hash of arguments to an auth function
#
# Returns: Reference to hash of canonicalized arguments
#  Throws: Text exception on internal call method error
sub _canonicalize_auth_args {
    my ($self, $args_ref) = @_;
    my %args = %{$args_ref};

    # Ensure we have either username or user_id, but not neither or both.
    my $user_count = grep { defined($args{$_}) } qw(username user_id);
    if ($user_count < 1) {
        croak('no username or user_id specified');
    } elsif ($user_count > 1) {
        croak('username and user_id both given');
    }

    # Ensure factor is set.
    if (!defined($args{factor})) {
        croak('no factor specified');
    }

    # Set some defaults that we provide in our API guarantee.
    my $factor = $args{factor};
    if ($factor eq 'push' || $factor eq 'phone' || $factor eq 'auto') {
        $args{device} //= 'auto';
    }

    # Convert pushinfo to a URL-encoded string if it is present.  We use this
    # logic rather than _canonicalize_args so that we can preserve order.
    if ($args{pushinfo}) {
        my @pushinfo = @{ $args{pushinfo} };
        my @pairs;
        while (@pushinfo) {
            my $encoded_key   = uri_escape_utf8(shift(@pushinfo));
            my $encoded_value = uri_escape_utf8(shift(@pushinfo));
            my $pair          = $encoded_key . q{=} . $encoded_value;
            push(@pairs, $pair);
        }
        $args{pushinfo} = join(q{&}, @pairs);
    }

    # Return the results.  Currently, we don't validate any of the other
    # arguments and just pass them straight to Duo.  We could do better about
    # this.
    return \%args;
}

# Perform a synchronous user authentication.  The user will be authenticated
# given the factor and additional information provided in the $args argument.
# The call will not return until the user has authenticated or the call has
# failed for some reason.  To do long-polling instead, see the auth_async
# method.
#
# $self     - The Net::Duo::Auth object
# $args_ref - Reference to hash of arguments, chosen from:
#   user_id  - ID of user (either this or username is required)
#   username - Username of user (either this or user_id is required)
#   factor   - One of auto, push, passcode, or phone
#   ipaddr   - IP address of user (optional)
# For factor == push:
#   device           - ID of the device (optional, default is "auto")
#   type             - String to display before prompt (optional)
#   display_username - String instead of username (optional)
#   pushinfo         - Reference to array of pairs to show user (optional)
# For factor == passcode:
#   passcode - The passcode to validate
# For factor == phone:
#   device - The ID of the device to call (optional, default is "auto")
#
# Returns: Scalar context: true if user was authenticated, false otherwise
#          List context: true/false for success, then hash of additional data
#            status               - Status of authentication
#            status_msg           - Detailed status message
#            trusted_device_token - Token to use later for /preauth
#  Throws: Net::Duo::Exception on failure
sub auth {
    my ($self, $args_ref) = @_;
    my $args = $self->_canonicalize_auth_args($args_ref);

    # Make the call to Duo.
    my $result = $self->call_json('POST', '/auth/v2/auth', $args);

    # Ensure we got a valid result.
    if (!defined($result->{result})) {
        my $error = 'no authentication result from Duo';
        die Net::Duo::Exception->protocol($error, $result);
    } elsif ($result->{result} ne 'allow' && $result->{result} ne 'deny') {
        my $error = "invalid authentication result $result->{result}";
        die Net::Duo::Exception->protocol($error, $result);
    }

    # Determine whether the authentication succeeded, and return the correct
    # results.
    my $success = $result->{result} eq 'allow';
    delete $result->{result};
    return wantarray ? ($success, $result) : $success;
}

# Perform an asynchronous authentication.
#
# Takes the same arguments as the auth method, but starts an asynchronous
# authentication.  Returns a transaction ID, which can be passed to
# auth_status() to long-poll the result of the authentication.
#
# $self     - The Net::Duo::Auth object
# $args_ref - Reference to hash of arguments, chosen from:
#
# Returns: The transaction ID to poll with auth_status()
#  Throws: Net::Duo::Exception on failure
sub auth_async {
    my ($self, $args_ref) = @_;
    my $args = $self->_canonicalize_auth_args($args_ref);
    $args->{async} = 1;

    # Make the call to Duo.
    my $result = $self->call_json('POST', '/auth/v2/auth', $args);

    # Return the transaction ID.
    if (!defined($result->{txid})) {
        my $error = 'no transaction ID in response to async auth call';
        die Net::Duo::Exception->protocol($error, $result);
    }
    return Net::Duo::Auth::Async->new($self, $result->{txid});
}

# Confirm that authentication works properly.
#
# $self - The Net::Duo::Auth object
#
# Returns: Server time in seconds since UNIX epoch
#  Throws: Net::Duo::Exception on failure
sub check {
    my ($self) = @_;
    my $result = $self->call_json('GET', '/auth/v2/check');
    return $result->{time};
}

# Send one or more passcodes (depending on Duo configuration) to a user via
# SMS.  This should always succeed, so any error results in an exception.
#
# $self     - The Net::Duo::Auth object
# $username - The username to send SMS passcodes to
# $device   - ID of the device to which to send passcodes (optional)
#
# Returns: undef
#  Throws: Net::Duo::Exception on failure
sub send_sms_passcodes {
    my ($self, $username, $device) = @_;
    my $data = {
        username => $username,
        factor   => 'sms',
        device   => $device // 'auto',
    };
    my $result = $self->call_json('POST', '/auth/v2/auth', $data);
    if ($result->{status} ne 'sent') {
        my $status  = $result->{status};
        my $message = $result->{status_msg};
        my $error   = "sending SMS passcodes returned $status: $message";
        die Net::Duo::Exception->protocol($error, $result);
    }
    return;
}

1;
__END__