OpenXPKI::Server::Authentication::Command

This is the class which supports OpenXPKI with an authentication method via an external program. The input parameters are are passed as a hash reference.

When called with a non-empty username, the handler maps the incoming data into the environment based on the map given by env.

The given command is executed, if its return value is zero the login is assumed to be valid, otherwise LOGIN_FAILED is returned.

If a static role was set via role, the username provided as input and the static role are returned. If no role is set, the output of the command is considered to be the name of the role. It is possible to postprocess the output by setting output_template. The resulting string is checked to exist as role name at auth.roles. If the output does not qualify as valid role, a NOT_AUTHORIZED error is returned.

Any additional parameters set in the incoming hash will be set as userinfo except the keys username, password, token, secret which are always removed to avoid leakage of secrets.

The authinfo section can be set as parameter to the handler (HashRef) and is set as-is.

Login Parameters

Expects username to be set to a non-empty value, any other parameters can be set but are not used or validated by the handler itself.

Configuration Parameters

command

The command to execute. A single command can be given as string, if you need to pass a command with arguments you must pass them as an array.

The script must exit with a return value of 0 for a successful login.

If not role is set, the script must print the role name to assign on stdout.

For more details see See Proc::SafeExec.

env

Any incoming data is passed to the command by setting keys in the environment. env must be a HashRef where the keys are the names of the environment variables. The values can either be a static word or a template toolkit string. The incoming parameters are available with their names inside the template, e.g. [% username%] holds the value given as username.

role

The role to assign to a valid login, if not set the output of the command is used.

output_template

If no role is set, you can pass the commands output to template toolkit for postprocessing. The template can access the output of the command as [% out %].

The result must be the name of a valid role, leading and trailing whitespace is removed by the handler.

Configuration Examples

Static Role

In this mode, you need to specify the role for the user as a static value inside the configuration.

 MyHandler:
   type: Command
   role: 'RA Operator'
   command: /path/to/your/script
   env:
        PASSWD: "[% password %]"
        LOGIN: "[% username %]"

The login will succeed if the script has exitcode 0. Here is a stub that logs in user "john" with password "doe":

  #!/bin/bash

  if [ "$LOGIN" == "john" ] && [ "$PASSWD" == "doe" ]; then
    exit 0;
  fi;

  exit 1;

Output evaluation

If you do not set the role in the configuration, it is determined from the scripts output. Leading/Trailing spaces are always stripped by the handler internally. If your output needs more postprocessing (e.g. strip away a prefix), you can specify a template toolkit string.

 MyHandler:
   type: Command
   command: /path/to/your/script
   output_template: "[% out.replace('role_','') %]"
   env:
        PASSWD: "[% password %]"
        LOGIN: "[% username %]"