/ 
WWW-Keycloak-0.001
/ WWW::Keycloak

NAME

WWW::Keycloak - Perl client for Keycloak identity management (OIDC + Admin REST API)

VERSION

version 0.001

SYNOPSIS

use WWW::Keycloak;

my $kc = WWW::Keycloak->new(
  base_url => 'https://id.example.org',
  realm    => 'main',
  username => 'admin',            # or client_id + client_secret, or token
  password => $ENV{KEYCLOAK_ADMIN_PASSWORD},
);

# OpenID Connect
my $claims = $kc->oidc->verify_token( $jwt, audience => 'my-api' );

# Admin REST API, repeatable
$kc->admin->ensure_client( clientId => 'my-cli', publicClient => \1 );
$kc->admin->ensure_user( username => 'alice', enabled => \1 );

# another realm, same login
my $dev = $kc->for_realm('dev');

DESCRIPTION

A client for Keycloak in two parts: WWW::Keycloak::OIDC for what an application does with a realm, and WWW::Keycloak::Admin for bringing a realm into a wanted state from Perl, repeatably.

The realm is part of every address in Keycloak, so it is a required attribute here and not an argument of each method. "for_realm" gives the same client for another realm.

The admin login is managed for you: WWW::Keycloak::Auth fetches a token, renews it before it runs out and once more when Keycloak refuses it.

base_url

Required. Where Keycloak is, without /realms/.... A trailing slash is removed.

realm

Required. The realm to work with.

username

password

Admin login with a password, through the admin-cli client of "auth_realm".

client_id

client_secret

Admin login as a service-account client.

token

A ready admin token, used as it is.

auth_realm

The realm the admin logs in to. Default master for a password login, the own realm for a service account.

ua

The LWP::UserAgent every part shares. The default follows no redirects.

auth

The WWW::Keycloak::Auth, or undef when no admin login was given.

oidc

The WWW::Keycloak::OIDC of this realm.

admin

The WWW::Keycloak::Admin of this realm.

issuer

print $kc->issuer;   # https://id.example.org/realms/main

for_realm

my $dev = $kc->for_realm('dev');

The same client for another realm, sharing the user agent and the admin login.

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-www-keycloak/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.