Loading...
Changes Saved.
Error Occurred!

KnowledgeBase

Remote Authentication System v2.0

Remote Authentication System (RAS) v2.0 allows you to perform username/password verification from your own web site. This is performed by hosting a script on your own website (using CGI, PHP, ASP, or similar) that accepts two parameters; a username, and a password; and returns content indicating privilege levels and default settings for the requesting user.

This document is highly technical in nature. Before continuing, we recommend that you have some familiarity with the following technologies:
  • A server side scripting language such as PHP, Perl, ASP, Python, Ruby, etc..
  • Very basic knowledge of HTTP
Most remote authentication scripts consult a local database to determine a user's privileges.

RAS v2.0 is very powerful, and is provided as a replacement for v1.1. If your script will require nothing more than to simply indicate if a user is denied access, allowed access, or allowed admin access; we recommend using RAS v1.0 instead as it is a much easier protocol.

SCRIPT INPUT PARAMETERS


The following parameters are passed to your script http-encoded as CGI get variables.

username: Requesting username
password: Requesting user's password
ip: Requesting user's ip address
transname: DEPRECATED: Requesting user's username

SCRIPT OUTPUT PROTOCOL

Your script should output it's data in text/plain format, and should not contain any leading or trailing whitespaces, carriage returns, or linebreaks. Output values are specified in parameter = value format and should be followed by a single linefeed (LF, \n) or a carriage return and linefeed (CR+LF, \r\n)

RAS v2.0 does not support comments.

REQUIRED SCRIPT OUTPUT PARAMETERS

The following output is required by your script. All scripts should start with the 'scras.version' parameter. An explanation of data types is provided later in this document. Values shown in braces indicate: {data type; description of parameter value}. Please read the note below concerning the user.usergroup.id parameter in the Customizable Script Output Parameters section.

scras.version = 2.0
user.usergroup.id = {numeric, non-zero value; required; usergroup id that you use internally}

DEFAULT PARAMETERS DISCUSSION

Your default user and usergroup parameters are taken from your Guest usergroup. You may specify Guest usergroup settings from within your AddonChat account control panel. Settings not

CUSTOMIZABLE SCRIPT OUTPUT PARAMETERS (AUTHENTICATION RELATED)


The following output is optional and directly effects how the server will authenticate the user, and which privileges the user will receive. An explanation of data types is provided later in this document. Values shown in braces indicate: {data type; description of parameter value}.

user.usergroup.can_login
= {numeric boolean; Is this user allowed in?}
user.usergroup.post_delay = {numeric; silence user for N seconds before they may type again}
user.usergroup.allow_pm = {numeric boolean; Allow this user to instant message others?}
user.usergroup.allow_room_create = {numeric boolean; Allow user to create new rooms?}
user.usergroup.idle_kick = {numeric boolean; Kick this user if they are idle in the chat room?}
user.usergroup.is_admin = {numeric boolean; Is this user an admin?}
user.usergroup.is_speaker = {numeric boolean; Is this user a guest speaker by default?}
user.usergroup.is_super_moderator = {numeric boolean; Is this user a moderator by default?}
user.usergroup.can_kick = {numeric boolean; can this admin kick other users?}
user.usergroup.can_kick_admin = {numeric boolean; can this admin kick other admins?}
user.usergroup.can_grant = {numeric boolean; can this admin grant admin privileges to others?}
user.usergroup.can_cloak = {numeric boolean; can this admin cloak?}
user.usergroup.can_see_cloak = {numeric boolean; can this admin see cloaked admins?}
user.usergroup.can_ban = {numeric boolean; can this admin ban IP addresses?}
user.usergroup.can_ban_subnet = {numeric boolean; can this admin ban subnets?}
user.usergroup.can_system_speak = {numeric boolean; can this admin speak as the system user?}
user.usergroup.can_enable_moderation = {numeric boolean; can admin user enable room moderation?}
user.usergroup.can_silence = {numeric boolean; can this admin silence others?}
user.usergroup.allow_bbcode = {numeric boolean; allow BBCode in messages?}
user.usergroup.allow_html = {numeric boolean; allow HTML content - not recommended;}
user.usergroup.allow_color = {numeric boolean; allow user to set message color?}
user.usergroup.msg_scroll = {numeric boolean; enable message scrollback feature?}
user.usergroup.max_msg_length = {numeric; maximum message length in characters}
user.usergroup.filter_shout = {numeric boolean; apply shout filter to this user?}
user.usergroup.filter_profanity = {numeric boolean; apply profanity filter to this user?}
user.usergroup.filter_word_replace = {numeric boolean; apply word replacement filter to this user?}
user.usergroup.can_launch_website = {numeric boolean; may this admin launch websites for other users remotely?}
user.usergroup.mark_as_guest = {numeric boolean; is this user considered a guest?}
user.usergroup.can_fnick = {numeric boolean; can this admin change user's nicknames with the /fnick command?}
user.uid = {numeric; user ID as passed back through external functions}

Please note that some values specified may not be honored if they conflict with higher priority settings. E.g., usergroup.can_ban_subnet will not be honored unless usergroup.is_admin is set to '1'.

Important: The user.usergroup.id parameter must be set to a unique numeric value for each individual set of permissions that your script returns. Failure to set this parameter, or setting this parameter incorrectly will result in a wide range of issues, including security issues. For example, if your script has three sets of permissions it returns (e.g., users, administrators, and moderators) you would need to set this value uniquely for each usergroup (e.g., users would return 1 for the user.usergroup.id parameter, administrators would return 2, and moderators would return 3)

EXTERNAL / REMOTE FUNCTION INTEGRATION (ADVANCED)

RAS v2.0 allows you to specify external (or remote) functions (the same as set in your AddonChat control panel) directly. The format is as follows:
url.remote.user.0 = "Function Descriptor 0", "http://www.mysite.com/mylink.php", "_blank", "false"
url.remote.user.1 = "Function Descriptor 1", "http://www.mysite.com/admin_function.cgi", "_blank", "true"

The list must begin with url.remote.user.0, and count upwards with no ID exclusions. The first parameter is the function descriptor (as it is displayed in the userlist right-click menu. The second paramater is the full URL to the link. See the External (Remote) Functions knowledge base article for more details regarding this. The third paramter specifies the browser frame or window name that the link should be launched in. The fourth parameter specifies whether or not the function should only be available to administrators.

This system also applies to Room functions. E.g.

url.remote.room.0 = "Room Function 0", "http://www.mysite.com/room_function.pl", "_blank", "false"
UNDOCUMENTED SCRIPT OUTPUT PARAMETERS (NON-AUTHENTICATION RELATED)

Additional parameters provided by your script will be sent directly to the chat client. Some parameters may be filtered based upon your service edition. The AddonChat document concerning Direct Settings, as well as Translation Files will provide you with information regarding variables that can be sent directly to the chat client. As remote authentication is performed after the applet has loaded it's initial configuration, some parameters passed may have no effect on the chat client. We recommend that you keep RAS output to a minimum so as not to impede login speed.

DATA TYPES

numeric: A positive or negative integer. Integers larger than 32 bits may not be tolerated.
numeric boolean: A single 0 (zero) or 1 (one) to indicate false or true respectively.
string: An unquoted string of ASCII or UTF-8 characters

SAMPLE PHP SCRIPT

<?php
    /* This script will allow any user to login using RAS v2.0 */

    $user_name = $_REQUEST['username'];
    $user_ip = $_REQUEST['ip'];
    $user_password = $_REQUEST['password'];

    header("Content-type: text/plain");
   
    /* Required:
        1. Specify the version of RAS that you're using.
        2. Specify a unique value for user.usergroup.id (this value should be unique
           for each different set of permissions that your script returns. I.e.,
           1 for regular users, 2 for admins, 3 for super-admins, etc.. You may choose
           whatever ID numbers you'd like.
    */
    print "scras.version = 2.0\n";
    print "user.usergroup.id = 1\n";

    /* Recommended: Specify a unique ID number for this user. */
    print "user.uid = 1\n";

    /* Here we specify the permissions for this user / usergroup */
    print "user.usergroup.can_login = 1\n";
    print "user.usergroup.mark_as_guest = 0\n";
?>


TESTING YOUR AUTHENTICATION SCRIPT

After you have put your authentication script online, test it using a simple username and password.  We recommend testing with a user and password that does contains only alpha-numeric characters and no spaces so as to avoid HTTP encoding issues. For this example, we'll assume that your username is 'Bob' and your password is '12345' and your script is located at http://www.mysite.tld/auth.php.

First, test your script manually by entering your script URL followed by a sample username and paramter in GET format directly into a web browser. E.g., visit:

http://www.mysite.tld/auth.php?username=Bob&password=12345

Verify that the output is as expected.

You may also wish to test how AddonChat will process your script. For this test, you'll need to know your account ID (number only), assigned server ID, your assigned port number, and you'll need to use an imaginary (but valid, and non-local/LAN) IP address and socket ID. The test URL is:

http://clientX.addonchat.com/rauth.php?sfd=9999&aid=ACCOUNT_ID&un=USERNAME&upw=PASSWORD&port=PORT&ip=IP&debug=1

Where:

X : AddonChat Server ID
ACCOUNT_ID: AddonChat numeric account ID
USERNAME : Chat username you wish to test with
PASSWORD : Chat password you wish to test with
PORT : Your assigned AddonChat Port
IP : Any real IP address

The script will produce a lot of output. Provided it does not break, and the output looks sufficient to you, it should be OK for production use.

ENABLE REMOTE AUTHENTICATION SYSTEM IN YOUR ADDONCHAT CONTROL PANEL

Follow the steps below to enable remote authentication for your AddonChat chat room.
  1. Login to your AddonChat Customer Account at http://www.addonchat.com/
  2. Enter the AddonChat Account Control Panel for the account you wish to enable remote authentication for
  3. Select the Settings tab from within the AdodnChat Account Control Panel
  4. Select the Site Integration link in the Settings submenu
  5. Select the Remote Authentication link in the Site Integration submenu
  6. Set Enable Remote Authentication to Yes
  7. Enter the full URL (beginning with http://) to your authentication script next to Authentication URL
  8. Click the Click Here to Save Changes button
If your chat room is currently open, please close it's browser window and reload before testing.

NOTES

As of AddonChat v8.0, remote authentication scripts are not consulted for access to the AddonChat Admin. Console. You may need to temporarily disable remote authentication in your control panel and add administrator user's to allow user access to the Admin. Console.

Remote authentication scripts stored on secure (https) servers are not supported.

RAS v2.0 SUPPORT

Support for advanced remote authentication use may be limited. If you have any questions, please contact us via eMail at support@addonInteractive.com or submit a support ticket. When submitting a support ticket regarding RAS v2.0, please include the following:
  1. Your account ID
  2. Indicate that you have read this knowledge base document (RAS v2.0 specification)
  3. Provide a full URL to your working (though possibly buggy) authentication script
  4. Indicate the exact nature of the problem
  5. Provide a valid username and password that we may test with



Related Articles