/ 
Airlock-0.001
/ Airlock::Upstream::Keycloak

NAME

Airlock::Upstream::Keycloak - Use a Keycloak login as the subject of an Airlock approval

VERSION

version 0.001

SYNOPSIS

my $keycloak = Airlock::Upstream::Keycloak->new;

my $airlock = Airlock->new(
  policy  => { always => ['upstream'] },
  factors => [ $keycloak->factor( max_age => 300 ) ],
  ...
);

# in the approval action, with the claims of the person's ID token
my $result = $airlock->approve( $code, subject => $keycloak->subject($claims) );

DESCRIPTION

When the host application logs people in through Keycloak, this class turns the token claims into the subject Airlock wants, and builds the Airlock::Factor::Upstream that recognises a Keycloak login with a second factor.

A Keycloak realm in its default configuration does not report a second factor in the token: with Keycloak 26.8.0 a password login and a login with TOTP both carry acr=1 and no amr. Two settings change that:

  • the client, or a client scope it uses, has the protocol mapper Authentication Method Reference (AMR) (oidc-amr-mapper);

  • the steps of the authentication flow carry a reference value (default.reference.value, with default.reference.maxAge), for example pwd on the password form and otp on the OTP form.

A login with TOTP then carries amr => [ 'pwd', 'otp' ], which the default "mfa_amr" recognises. t/keycloak/setup.pl in the distribution does the second part through the Admin REST API, and t/90-live-keycloak.t checks the whole chain against a running Keycloak.

mfa_amr

amr values that mean a second factor was used.

mfa_acr

acr values that mean a second factor was used.

subject

my $subject = $keycloak->subject($claims);

The Airlock subject for a set of token claims: id from sub, and amr, acr and auth_time as Keycloak sent them. Croaks without sub.

factor

my $factor = $keycloak->factor( max_age => 300 );

An Airlock::Factor::Upstream that holds for a Keycloak login with a second factor. Takes its options.

SUPPORT

Issues

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