Authentication Hooks

login_key_(create|modify)_post.sh

This hook will be triggered when a Login Key is either being created or modified, or if a One-Time Login Hash URL is being created (as it essentially creates a special login key to do this).

Environment variables

  • keyname:name of the login key
  • is_login_url (0|1): if 1, we're creating the one-time login hash url. 0 means a normal login key.
  • modifying (0|1): whether this is a new login key or modifications to an existing login key
  • key: secret key. only applies to creations, it's the plaintext/raw password for the key to work with.
  • expiry_timestamp: unix timestamp for the current expiry of the key. 0 means never.
  • max_uses: how many times the key could be used. 0 means unlimited.
  • allow: list of CMDs allowed, separated by | character
  • deny: list of CMDs denied, separated by | character
  • ips: list of IPs allowed, separated by | character.
  • login_keys_notify_on_creation (0|1|2): based on the directadmin.conf setting, altered by DA at run-time, determines whether a notice should be sent for this call.

login_pre.sh

The hook login_pre.sh is an extra layer of security, should you wish to use it. A strong password is good, but a strong password from an approved IP is better.

Integrated right into the user/pass authentication code, this script allows the server admin to check the remote ip, user, password, and referer of the connection.

If the script exists, it will be called for all requests, since authentication is done for each request (even with sessions).

The script enables the server admin to allow or deny a request based on any criteria they wish.

Any non-zero exit code here will count against the brute-force check, even if the correct password is passed.

A non-zero exit code will add an entry into your error.log with any text you echo.

This is run before any passwords and demo accounts are even checked, so if you use a demo, ensure to allow demo_user, demo_admin, and demo_reseller before you do your normal checks.

Environment variables

  • username : username
  • password : password
  • session_id : session ID generated
  • ip : ip of the user
  • referer : Referer header passed to DA in the request
  • user_agent : User-Agent header passed to DA in the request

lost_password_pre.sh

The hook script, /usr/local/directadmin/scripts/custom/lost_password_pre.sh, will run before all calls of the CMD_LOST_PASSWORD command. If you exit with a non-zero value, the script will abort the process.

Environment variables

  • username : username
  • password : password
  • session_id : session ID generated
  • ip : ip of the user
  • referer : Referer header passed to DA in the request
  • user_agent : User-Agent header passed to DA in the request

one_click_pma_login_post.sh

New optional hook to use with the phpMyAdmin one-click login feature:

one_click_pma_login=1
1

The exit code should be 0 for success and 1 for error, however error or not, the behavior will not be altered and the output will not be modified.

The only variance is a debug output at level 100 will provide info from your script.

This is basically just a silent script to take action as needed.

Environment variables

  • token: token name
  • username: pma login name (will be formatted similar to 'da_sso_XXXXXXXXX')
  • passwd: secret pass, known to no-one, except internally in DA, set in DB User account.
  • name: Database User name.

Note: name may be set to username_%% in the event that all User databases are to be accessible for this token.


session_create_pre.sh

This hook is very similar to the login_pre.sh hook script. However, the login_pre.sh is called for every request and checks the password for each one.

The session_create_pre.sh only applies to DA just before it creates the session file but after the password has been validated.

Note that API calls DO NOT use session files, so this should not be a login filter.

This script can be handy if you'd like to notify yourself of a session-based login, but you won't be notified for any API based actions for the same account (this won't be called for API calls).

Be sure to exit with a zero-status. If you exit with a non-zero status, the write of the session file will be aborted, and the login won't work.

All non-zero exit statuses will be logged to the /var/log/directadmin/error.log, but the login page will just refresh with no errors.

Environment variables

  • username: username
  • password : password
  • session_id : generated session ID
  • ip : ip of the user
  • referer : Referer header passed to DA in the request
  • user_agent : User-Agent header passed to DA in the request

session_destroy_pre.sh

If a session is to be destroyed due to old age, or due to logout, session_destroy_pre.sh will be called just before the session file at /usr/local/directadmin/data/sessions/sess_XXX is removed.

Environment variables for a standard login

  • username: username
  • passwd: base64 encrypted password
  • key: secret key used for session
  • host: host
  • ip: ip of the user
  • file: path to the session file to be removed
  • home_memory:

Environmental values passed will be the entire contents of the session file, plus:

file=/usr/local/directadmin/data/sessions/sess_XXX  #path to the current session file.
1

Contents of a session file might look like this, but can vary:

home_memory=3
host=2.3.4.5
ip=1.2.3.4
key=SEbYTmsYQ7kccy0OhWenhidoEs6POWfqiEO2yHgPMQzyOxM3TAp9rfv5V2UtW7hE
login_key=keyname
passwd=base64encodedpasswd
selected_domain=domain.com
username=admin
1
2
3
4
5
6
7
8

If a Login Key is used to login to DA, the login_key=keyname is added to the session file. You can then get info on that login key with this path:

/usr/local/directadmin/data/users/$username/login_keys/${login_key}/*
1

Note that this does not account for the "login-as" method, which might set the username to be:

username=admin|fred
1

So be sure to check for that in the $username variable before using it, e.g.,

REALUSER=`echo "$username" | cut -d\| -f1
1

In the above example, the login_key and key pass would be from User "admin" and not "fred". Use $REALUSER throughout your script instead of $username if the "login-as" method is used.

Unlike other pre.sh scripts, the exit code of your script will not abort the deletion process, as we should never block the removal of a session. It is highly recommended that you use exit 0; at the end of your script, in case this policy does change later on.


Examples

login_pre.sh - Filter users according to their IP(s)

If you know that admin should only be logging in from a specific range of IPs, you can write code to check the IP, compare it to the list, and approve/deny the request.

The benefit of this method of filtering is that if you deny the request (exit with a non-zero result), the standard login errors will appear. The person attempting to login will assume they've got an invalid password, and not realize they may be filtered based on their IP.

Add the following code to /usr/local/directadmin/scripts/custom/login_pre.sh:

#!/usr/local/bin/php
<?php

$user = getenv('username');
$ip = getenv('ip');

$my_ip = "1.2.3.4";

if ($user == 'demo_user' || $user == 'demo_reseller' || $user == 'demo_admin')
{
       //not worried about demos
        exit(0);
}

if ($ip != "1.2.3.4")
{
        echo "Invalid IP";
        exit(1);
}
exit(0);

?>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Lastly, correct the permissions and ownership:

chown diradmin. /usr/local/directadmin/scripts/custom/login_pre.sh
chmod 700 /usr/local/directadmin/scripts/custom/login_pre.sh
1
2
Last Updated: 6/23/2021, 9:36:08 PM