Net::Duo(3pm)

💖 Net::Duo 💖

okay bestie, welcome to Net::Duo — it's the API for the Duo multifactor authentication service, and yes it's a Perl module, and yes it ate. 🦋

---

✨ SYNOPSIS ✨

my $duo = Net::Duo->new({ key_file => '/path/to/keys.json' });
my $reply = $duo->call_json('GET', '/auth/v2/check');

literally two lines and you're in. 💅

---

🌸 REQUIREMENTS 🌸

you need Perl 5.14 or later, no negotiating, and also these modules:

• HTTP::Request and HTTP::Response (they live inside HTTP::Message)
• JSON
• LWP (aka libwww-perl)
• Perl6::Slurp
• URI::Escape (part of URI)

all of them are on CPAN, so like, go get them, it's fine. 🎀

---

🌈 DESCRIPTION 🌈

Net::Duo gives you an object-oriented Perl interface for generic calls to one of the the Duo Security REST APIs. It's primarily meant to be a base class for more specialized Perl modules that implement the specific Duo APIs — but lowkey you can also just use it directly to make generic API calls. main character energy either way. 👑

🚨 and listen, on failure, all methods throw a Net::Duo::Exception object. You can interpolate it into a string for a simple error message, or poke at it with method calls for more details. Same deal for every single method in every single object in the Net::Duo namespace. no cap.

---

🧚 CLASS METHODS 🧚

new(ARGS)

Create a new Net::Duo object. Use this for all your subsequent API calls, bestie, don't skip it.

ARGS should be a hash reference with one or more of these keys:

• api_hostname — the API hostname that Duo handed you when the API integration was created. Required if key_file is not set.
• integration_key — the integration key that Duo handed you when the API integration was created. This is basically the public "username" for this integration. Required if key_file is not set.
• key_file — the path to a file in JSON format holding the key and hostname data for a Duo integration. That file should contain one JSON object with the keys integration_key, secret_key, and api_hostname — these are the three data values you get back when you create a new Duo API integration.

⚠️ be aware that the secret_key value in this file is security-sensitive information equivalent to a password. Anyone in possession of that key has complete control of all data and actions to which the integration has access. 💀

Either this key or all of integration_key, secret_key, and api_hostname must be provided. And if you give both this key and some of those keys, their values will override the values retrieved from the key_file file. override era. ✨

• secret_key — the secret key that Duo handed you when the API integration was created. This is security-sensitive information equivalent to a password. Anyone in possession of that key has complete control of all data and actions to which the integration has access. Do not hard-code this into programs — instead, read it from a file with appropriate permissions or retrieve it via some other secure mechanism. i'm begging. 🙈

Required if key_file is not set.

• user_agent — the user agent to use for all requests. It should be a Perl object that supports the same API as LWP::UserAgent.

Normally you won't provide this key at all, and then Net::Duo will create an LWP::UserAgent object internally to make Duo API calls with. This argument exists primarily so the user agent can be overridden for unit testing. 🧪

---

💜 INSTANCE METHODS 💜

call(METHOD, PATH[, ARGS])

Make a generic Duo API call, with no assumptions about the response.

This is the low-level escape hatch for making any Duo API call this module doesn't know about, regardless of what format it returns its results in. You (the caller) have to provide all of the details: HTTP method, URL path, and all arguments as a reference to a hash of key/value pairs. And the URL path must start with a slash.

The return value is the resulting HTTP::Response object from the web API call. No error checking will be performed. You are responsible for examining the HTTP::Response object for any problems, including internal or HTTP errors. it's giving "you're on your own, babe." 😭

Most Duo API calls return structured JSON and follow a standard pattern for indicating errors. For those calls, use call_json() instead of this method. You only need call() for the small handful of API calls that do not return JSON in that format — like the Auth API /logo endpoint. 🖼️

call_json(METHOD, PATH[, ARGS])

Make a generic Duo API call that returns a JSON response.

This is the escape hatch to use for any Duo API call this module doesn't know about. Same deal as before — you provide all of the details (HTTP method, URL path, and all arguments as a reference to a hash of key/value pairs), and the URL path must start with a slash.

The return value will be only the value of the response key from the returned JSON. This method still handles checking the stat value from Duo and throws a Net::Duo::Exception object if the call fails. slay. 🫶

This method cannot be used with the small handful of API calls that do not return JSON, such as the Auth API /logo endpoint.

call_json_paged(METHOD, PATH[, ARGS])

The same as call_json(), except for endpoints that require pagination. 📄📄📄

This makes repeated calls to call_json() with increasing offsets until it has retrieved all of the objects, and then returns them all as a single response. It always uses a limit setting of 500. iconic behaviour honestly.

---

👑 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>
• Duo Admin API <https://www.duo.com/docs/adminapi>

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/>. 🌐

---

and that's the whole page, bestie!! this doc was brought to you by perl v5.36.0, dated 2022-12-18, and the manual name is Net::Duo(3pm) in case you forgot already. go make some API calls, you're gonna devour. 💖✨🎀