User/Device Authorization

1 post / 0 new
Michael
User/Device Authorization

This functionality is available when the VirtualHere server has been purchased

Scripting is now also supported on the VirtualHere Windows Server using batch files instead of bash scripts, the return codes are identical to the linux/osx values as described below

The ClientAuthorization script

VirtualHere supports user authorization whereby specific users can be granted/denied access to specific devices. This is useful for example to protect remote access to security dongles by certain users, or limit the number of shared devices per user.

Make sure the VirtualHere Server is not running, then add the clientAuthorization setting to the server configuration file. This setting specifies the bash script to run to perform authorization and passes it specific parameters replaced at runtime with actual values for the current user and the device they are attempting to use. The CLIENT_ID is passed in by the VirtualHere client to the server. It is automatically set to the same username used to login to the current operating system session under Windows / OSX / Linux.

Once the config.ini file is changed and the server started, you can modify the authorization script at any time without restarting the server

  • $VENDOR_ID$ - The USB Device vendor id, in hex e.g "05ac"
  • $PRODUCT_ID$ - The USB Device product id in hex hex e.g "12a4"
  • $CLIENT_ID$ - The format is <full name><space><open bracket><username><close bracket> .eg "John Smith (jsmith)"
  • $CLIENT_IP$ - e.g "192.168.2.60"
  • $PRODUCT_SERIAL$ - This is the USB Device serial number e.g "2c89237021"
  • $PASSWORD$ - This setting is optional and is the password entered by the user when attempting to use the device. The password is encoded as an MD5 hash value
  • $DEVPATH$ - The device path on the server e.g /sys/bus/usb/devices/1-1
  • $NICKNAME$ - The nickname of the device (if set)
  • $NUM_BINDINGS$ - the number of devices this user is currently using.

Example 1

For example, the following setting specifies the bash script auth.sh to perform authorization and passes it 9 runtime parameters (all on one line)

clientAuthorization=/home/root/auth.sh "$VENDOR_ID$" "$PRODUCT_ID$" "$CLIENT_ID$" "$CLIENT_IP$" "$PRODUCT_SERIAL$" "$PASSWORD$" "$DEVPATH$" "$NICKNAME$" "$NUM_BINDINGS$"

Create a new file called auth.sh in the directory specified in the line above (e.g /home/root) and add the following example code (This code will deny access to everyone except the username "michael" with a password "mypassword"). Change it to suit your needs.

#!/bin/bash
# Example script for performing basic user authorization for virtualhere
# Also includes a simple password protection mechanism for accessing a device
# Return 2 if the user needs to provide a password (or the password is incorrect) to use the device
# Return 1 if the user is allowed to access this device
# Return 0 if the user is not allowed to access this device
# Parameters are passed in as:
# $1 = VENDOR_ID
# $2 = PRODUCT_ID
# $3 = CLIENT_ID
# $4 = CLIENT_IP
# $5 = PRODUCT_SERIAL
# $6 = PASSWORD
# $7 = DEVPATH
# $8 = NICKNAME
# $9 = NUM_BINDINGS
logger "Authorizing -> '$1' '$2' '$3' '$4' '$5' '$6' '$7' '$8' '$9'"
# "mypassword" = "34819d7beeabb9260a5c854bc85b3e44" as an MD5 hash
if [ "$6" == "34819d7beeabb9260a5c854bc85b3e44" ]; then
echo "Password ok"
else
exit 2
fi
if [[ "$3" == *"(michael)"* ]]; then
logger "Authorized!"
exit 1
else
logger "NOT authorized"
exit 0
fi

Save the file and give it execute permissions chmod +x /home/root/auth.sh

Now when you start the server it will call this script every time a client attempts to Use a device. You can use the other parameters passed in to perform more specific authorization, for example using the device product ID or client IP or password based on the type of device and so forth.

Example 2

Thanks to user ben at wildblue de, here is an advanced configuration script with logging and detailed authentication

The ClientDeauthorization script

The ClientDeauthorization setting is identical to the ClientAuthorization script but is called when a user disconnects from a device. The parameters sent to the script are identical to the ClientAuthorization script except the script is not required to return a value of 1 or 0. Using both the ClientAuthorization and ClientDeauthorization script makes it easy to track user-device usage e.g for logging and accounting purposes.

The OnDeviceKick script

When a client runs in adminstrator mode (using the -a argument when starting the client) the administrator can kick another user off a device by right clicking on the in-use device and selecting "Disconnect from User". If you would like to restrict which administrators can kick which users of which devices you can use the OnDeviceKick setting in the server config.ini file to specify a script to run to determine the action to be taken. This script is similar to the scripts above but should return 1 if the user can be kicked from the device and 0 otherwise.

For example, the following setting specifies the bash script onDeviceKick.sh and passes it 8 runtime parameters (all on one line)

onDeviceKick=/home/root/onDeviceKick.sh "$VENDOR_ID$" "$PRODUCT_ID$" "$KICKER_ID$" "$CLIENT_ID$" "$CLIENT_IP$" "$PRODUCT_SERIAL$" "$DEVPATH$" "$NICKNAME$"

Create a new file called onDeviceKick.sh in the directory specified in the line above (e.g /home/root) and add the following example code (This code will deny administrator kicking abilities to everyone except the username "michael"). Change it to suit your needs.

#!/bin/bash
# Example script for controlling who can kick off a user from a device,
# this script blocks all administrators from kicking except for michael
# Return 1 if the user can be kicked off the in-use device
# Return 0 if the user can NOT be kicked off an in-use device
# Parameters are passed in as:
# $1 = VENDOR_ID
# $2 = PRODUCT_ID
# $3 = KICKER_ID
# $4 = CLIENT_ID
# $5 = CLIENT_IP
# $6 = PRODUCT_SERIAL
# $7 = DEVPATH
# $8 = NICKNAME
logger "OnDeviceKick -> '$1' '$2' '$3' '$4' '$5' '$6' '$7' '$8'"
f [[ "$3" == *"(michael)"* ]]; then
logger "OK"
exit 1
else
logger "No"
exit 0
fi

Save the file and give it execute permissions chmod +x /home/root/onDeviceKick.sh

Now when you start the server it will call this script every time an administrator attempts to Disconnect from User a device. You can use the other parameters passed in to perform more specific qualification, for example using the device product ID or client IP and so forth.