Net::Duo::Admin(3pm)

📦
version 1.02 · 2 versions
  • 1.02 · debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
  • 1.02 · ubuntu jammy
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Net::Duo::Admin 💖

okay so bestie, welcome to Net::Duo::Admin — it's the Perl interface for the Duo Admin API. yes THE Duo. the auth one. she's a Perl module, she's a whole manual page (3pm, in case you were wondering), and she's here to let you talk to Duo from inside your Perl like it's nothing. 🦋

✨ SYNOPSIS ✨

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

like. that's it. that's the whole vibe. 💅

🌸 REQUIREMENTS 🌸

you're gonna need Perl 5.14 or later, plus these modules, and no you cannot skip them:

  • HTTP::Request and HTTP::Response — these two live inside HTTP::Message, they're a package deal 🫶
  • JSON
  • LWP (also known as libwww-perl, same girl different name)
  • Perl6::Slurp
  • Sub::Install
  • URI::Escape — part of URI

all of them are available from CPAN, so like, go get them. ✨

👑 DESCRIPTION 👑

Net::Duo::Admin is an implementation of the Duo Admin REST API for Perl. method calls correspond to endpoints in the REST API — so like, every method is basically a lil doorway into an endpoint. her goal is to give you a native, natural interface for all the Duo operations in the API from inside Perl, while abstracting away as many details of the API as can be reasonably handled automatically. she's doing the emotional labor so you don't have to. 😭💖

currently, only a tiny number of available methods are implemented. she's growing. be patient with her.

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. and where it makes sense, there's also 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 is the moment that makes the underlying Duo API call to actually update the data. so like, you can be feral with your set_ calls and nothing happens to Duo until you commit. periodt. 💅

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_. heads up though — these changes are pushed to Duo immediately and do not wait for the next commit(). so add_ and remove_ are the impulsive ones. no vibe check, straight to Duo. 🏃♀️💨

on failure, all methods throw a Net::Duo::Exception object. you can interpolate it into a string for a simple error message, or inspect it with method calls for more details. and this is also true of all methods in all objects in the Net::Duo namespace. consistent queen. 👑

⭐ 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, so see Net::Duo for documentation of the possible arguments. she's not reinventing the wheel, she's borrowing it. 🎀

🌈 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. so like, all of it. at once. in your RAM. 🙈
  • 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. so you can retrieve all the records 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. it's a lil loop, bestie. you got this. 🔁

  • 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. same lil loop, different log. 💫

  • 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. she's chill about it. no drama. just undef. 🫶
  • 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. she said what she said. 💀

🎀 AUTHOR 🎀

Russ Allbery <rra@cpan.org>

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.

so like, yeah, all caps legal text, but the whole point is: it's free, use it, just keep the notice, and don't come for the authors if it breaks. 🧚

🦋 SEE ALSO 🦋

and that's the whole page, bestie! this one shipped as perl v5.36.0, dated 2022-12-18 — iconic, timeless, no notes. go call an endpoint. mwah. 💖✨🌸🎀🫶

📦 where this page comes from