NAME

Net::Async::Authentik - Async Perl client for the authentik identity provider (IO::Async + Future)

VERSION

version 0.001

SYNOPSIS

use Future::AsyncAwait;
use IO::Async::Loop;
use Net::Async::Authentik;

my $loop = IO::Async::Loop->new;
my $ak   = Net::Async::Authentik->new(
  base_url    => 'https://id.example.org',
  application => 'my-app',                   # the application slug, for OIDC
  client_id   => $client_id,                 # its provider's client id, checked as the audience
  token       => $ENV{AUTHENTIK_TOKEN},      # an API token, for the REST API
);
$loop->add($ak);

my $claims = await $ak->oidc->verify_token_f( $jwt, type => 'access' );
my $r      = await $ak->api->ensure_user_f( username => 'alice', name => 'Alice' );

DESCRIPTION

The asynchronous twin of WWW::Authentik, on IO::Async and Future: the same facade, the same parts, every method with _f returning a future. Requests are built and responses read by the same code as in the synchronous client, and the ensure_*_f methods compare with the same WWW::Authentik::Diff and resolve names from the same table, so both clients do the same thing to an authentik.

Add the object to a loop before the first request. The Net::Async::HTTP it sends through is its child notifier; without a loop every call fails with a Net::Async::Authentik::Error::Network saying so.

Nothing here throws. A wrong argument fails the future the caller is already holding, so one else catches a validation error and a refused request alike.

Hold the future you get back. Dropping it does not undo anything: the async sub has already begun, the request it waits on is held by the HTTP client, and the work runs to the end — authentik is written to and the answer goes nowhere, with a "lost its returning future" warning as the only sign. To start something and not wait for it, say so with ->retain.

And let every future finish before the process ends. A future of this distribution that is still pending at exit can take the interpreter down with double free or corruption or a segmentation fault — in global destruction, after the program's own work is done, so the damage is an exit status rather than lost data. This is a defect in Future::AsyncAwait 0.71, the newest release at the time of writing: an async sub suspended at exit whose saved frame holds a reference argument corrupts the heap. Eight lines reproduce it with none of this distribution involved; docs/future-asyncawait-0.71-crash.pl has them, together with what does and does not change it. Holding the future does not help and neither does ->retain; running the loop until the future is ready does.

Coming from WWW::Authentik

Two return values differ from what a Keycloak user would expect, and deliberately: create_*_f and update_*_f give back the representation, because authentik answers a create with the whole object and no Location header, and ensure_*_f gives back { object => \%rep, changed => ... }, because authentik has no single kind of identifier. Both are as in the synchronous client.

Developed and tested against authentik 2026.8.3.

base_url

Required. Where authentik is, without /api/v3 and without /application/o/. Trailing slashes are removed.

application

The slug of the application "oidc" talks to. Without it every method of "oidc" fails.

client_id

The client id of "application"'s provider. "verify_token_f" in Net::Async::Authentik::OIDC checks it as the audience, which is what keeps a token of another application of the same authentik from passing. Worth setting.

token

An authentik API token, sent as a bearer token with every call of "api". Without it every method of "api" fails. It is used as it is and never renewed.

http

The Net::Async::HTTP every part shares, built as a child of this notifier. Pass one in to share it with something else; it is then not added as a child, and whoever owns it is responsible for its loop.

Unlike the synchronous client, nothing has to be done about the TE connection token: Net::Async::HTTP does not announce it, and authentik answers every request. See the plan in docs/superpowers/plans/ for what was measured.

oidc

The Net::Async::Authentik::OIDC of "application". Without an application slug the object still exists, and every one of its methods fails with a validation error — an attribute does not throw.

api

The Net::Async::Authentik::API of this instance. Without a token every one of its methods fails with a validation error.

api_url

print $ak->api_url;   # https://id.example.org/api/v3

application_url

print $ak->application_url;   # https://id.example.org/application/o/my-app

Where this application's OpenID Connect endpoints live, without the trailing slash. The slug is URI encoded.

issuer

print $ak->issuer;   # https://id.example.org/application/o/my-app/

The issuer in its address form, which is what authentik puts into a token while the provider is set to issuer_mode: per_provider (its default). The authoritative value is "issuer_f" in Net::Async::Authentik::OIDC, read out of the discovery document.

for_application

my $other = $ak->for_application('second-app');

The same client for another application, sharing the Net::Async::HTTP and the API token. The new object is not a notifier in any loop of its own; it sends through the shared http.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-net-async-authentik/issues.

IRC

Join #kubernetes on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.