.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Net::Duo::Admin 3pm" .TH Net::Duo::Admin 3pm "2019-03-09" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::Duo::Admin \- Perl interface for the Duo Admin API .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& my $duo = Net::Duo::Admin\->new({ key_file => \*(Aq/path/to/keys.json\*(Aq }); \& my @users = $duo\->users; .Ve .SH "REQUIREMENTS" .IX Header "REQUIREMENTS" Perl 5.14 or later and the modules HTTP::Request and HTTP::Response (part of HTTP::Message), \s-1JSON, LWP\s0 (also known as libwww-perl), Perl6::Slurp, Sub::Install, and URI::Escape (part of \s-1URI\s0), all of which are available from \s-1CPAN.\s0 .SH "DESCRIPTION" .IX Header "DESCRIPTION" Net::Duo::Admin is an implementation of the Duo Admin \s-1REST API\s0 for Perl. Method calls correspond to endpoints in the \s-1REST API.\s0 Its goal is to provide a native, natural interface for all Duo operations in the \s-1API\s0 from inside Perl, while abstracting away as many details of the \s-1API\s0 as can be reasonably handled automatically. .PP Currently, only a tiny number of available methods are implemented. .PP 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 \s-1API\s0 documentation that returns that field value. Where it makes sense, there will also be a method with the same name but with \f(CW\*(C`set_\*(C'\fR prepended that changes that value. No changes are made to the Duo record itself until the \fBcommit()\fR method is called on the object, which will make the underlying Duo \s-1API\s0 call to update the data. .PP 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 \f(CW\*(C`add_\*(C'\fR and removed with a method starting with \f(CW\*(C`remove_\*(C'\fR. These changes are pushed to Duo immediately and do not wait for the next \fBcommit()\fR. .PP 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. .SH "CLASS METHODS" .IX Header "CLASS METHODS" .IP "new(\s-1ARGS\s0)" 4 .IX Item "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. .SH "INSTANCE METHODS" .IX Header "INSTANCE METHODS" .IP "\fBintegrations()\fR" 4 .IX Item "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. .IP "logs_administrator([\s-1MINTIME\s0])" 4 .IX Item "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: .RS 4 .IP "timestamp" 4 .IX Item "timestamp" The time of the event in seconds since \s-1UNIX\s0 epoch. .IP "username" 4 .IX Item "username" The username of the administrator, or \f(CW\*(C`API\*(C'\fR if the action was performed via the Admin \s-1API.\s0 .IP "action" 4 .IX Item "action" The administrator action. See the Duo Admin \s-1API\s0 documentation for a full list of valid values. .IP "object" 4 .IX Item "object" An identifier for the object that was acted on. What fields are used as an identifier will vary by type of object. .IP "description" 4 .IX Item "description" The details of what was changed. .RE .RS 4 .Sp At most 1,000 log entries will be returned. If \s-1MINTIME\s0 is provided, only records with a time stamp after \s-1MINTIME\s0 will be returned. All records can therefore be retrieved by calling this method repeatedly, first with no \&\s-1MINTIME\s0 and then with \s-1MINTIME\s0 matching the timestamp of the last returned record from the previous call. .RE .IP "logs_authentication([\s-1MINTIME\s0])" 4 .IX Item "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: .RS 4 .IP "timestamp" 4 .IX Item "timestamp" The time of the event in seconds since \s-1UNIX\s0 epoch. .IP "username" 4 .IX Item "username" The authenticating user's username. .IP "factor" 4 .IX Item "factor" The authentication factor, chosen from \f(CW\*(C`phone call\*(C'\fR, \f(CW\*(C`passcode\*(C'\fR, \&\f(CW\*(C`bypass code\*(C'\fR, \f(CW\*(C`sms passcode\*(C'\fR, \f(CW\*(C`sms refresh\*(C'\fR, or \f(CW\*(C`duo push\*(C'\fR. .IP "result" 4 .IX Item "result" The result of the authentication, chosen from \f(CW\*(C`success\*(C'\fR, \f(CW\*(C`failure\*(C'\fR, \&\f(CW\*(C`error\*(C'\fR, or \f(CW\*(C`fraud\*(C'\fR. .IP "ip" 4 .IX Item "ip" The \s-1IP\s0 address from which the authentication attempt originated. .IP "integration" 4 .IX Item "integration" The name of the integration from which the authentication attempt originated. .RE .RS 4 .Sp At most 1,000 authentication log entries will be returned. If \s-1MINTIME\s0 is provided, only records with a time stamp after \s-1MINTIME\s0 will be returned. All records can therefore be retrieved by calling this method repeatedly, first with no \s-1MINTIME\s0 and then with \s-1MINTIME\s0 matching the timestamp of the last returned record from the previous call. .RE .IP "logs_telephony([\s-1MINTIME\s0])" 4 .IX Item "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: .RS 4 .IP "timestamp" 4 .IX Item "timestamp" The time of the event in seconds since \s-1UNIX\s0 epoch. .IP "context" 4 .IX Item "context" How this telephony event was initiated. This will be one of \&\f(CW\*(C`administrator login\*(C'\fR, \f(CW\*(C`authentication\*(C'\fR, \f(CW\*(C`enrollment\*(C'\fR, or \f(CW\*(C`verify\*(C'\fR. .IP "type" 4 .IX Item "type" The event type. One of \f(CW\*(C`sms\*(C'\fR or \f(CW\*(C`phone\*(C'\fR. .IP "phone" 4 .IX Item "phone" The phone number that initiated this event. .IP "credits" 4 .IX Item "credits" How many telephony credits this event cost. .RE .RS 4 .Sp At most 1,000 log entries will be returned. If \s-1MINTIME\s0 is provided, only records with a time stamp after \s-1MINTIME\s0 will be returned. All records can therefore be retrieved by calling this method repeatedly, first with no \&\s-1MINTIME\s0 and then with \s-1MINTIME\s0 matching the timestamp of the last returned record from the previous call. .RE .IP "user(\s-1USERNAME\s0)" 4 .IX Item "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. .IP "\fBusers()\fR" 4 .IX Item "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. .SH "AUTHOR" .IX Header "AUTHOR" Russ Allbery .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2014 The Board of Trustees of the Leland Stanford Junior University .PP Copyright 2019 Russ Allbery .PP Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \*(L"Software\*(R"), 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: .PP The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. .PP \&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\s0 \s-1IN 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.\s0 .SH "SEE ALSO" .IX Header "SEE ALSO" Duo Auth \s-1API\s0 .PP This module is part of the Net::Duo distribution. The current version of Net::Duo is available from \s-1CPAN,\s0 or directly from its web site at .