Remote Authentication System (RAS) v2.1 allows you to perform username/password authentication from your own web site. This is enabled by hosting a script on your website (using PHP, ASP, JSP, Perl, etc..) that accepts two parameters; a username, and a password; and returns plain text content indicating the privilege levels and default settings for the user requesting access.
This document is technical in nature. Before continuing, we recommend that you have some familiarity with a scripting language such as PHP, Perl, JSP, Python, Ruby, etc..
Most remote authentication scripts consult a local database to determine user privileges.
If your script will require nothing more than to simply indicate if a user is denied access, allowed access, or allowed administrative access; we recommend using RAS v1.0 instead as it is a much faster to implement.
SCRIPT INPUT PARAMETERS
The following parameters are passed to your script as CGI GET variables:
username : Requesting user's name
password : Requesting user's password
transname : (Deprecated)
ip : Requesting user's IP address
rasver : Most recent supported RAS version by server (for use during AddonChat Beta testing)
scras.version = 2.1
user.usergroup.id = {numeric, required; internal user group id, or 0 (zero) to auto-generate.}
Recommended Parameters for All Users:
user.uid = {numeric; user ID as passed back through external functions}
user.usergroup.can_login = {boolean; Permit log in?}
user.usergroup.icon = {numeric; specify a custom icon; see below for details.}
user.usergroup.can_msg = {boolean; permit user to send messages?}
user.usergroup.idle_kick = {boolean; Kick user if he/she remains idle in chat room?}
Recommended Parameters for Non-Administrative Users:
user.usergroup.can_action = {boolean; permit user to send action messages?}
user.usergroup.post_delay = {numeric; time delay before user may enter another message}
user.usergroup.allow_pm = {boolean; Permit private messages?}
user.usergroup.allow_room_create = {boolean; Permit user to create new rooms?}
user.usergroup.allow_avatars = {boolean; permit user to select an avatar?}
user.usergroup.can_random = {boolean; permit use of /roll command?}
user.usergroup.allow_bbcode = {boolean; allow BBCode in messages?}
user.usergroup.allow_color = {boolean; allow user to set message color?}
user.usergroup.msg_scroll = {boolean; enable message scroll-back feature?}
user.usergroup.max_msg_length = {numeric; maximum message length in characters}
user.usergroup.filter_shout = {boolean; apply shout filter to this user?}
user.usergroup.filter_profanity = {boolean; apply word filters to this user?}
user.usergroup.filter_word_replace = {boolean; apply text replacement filters to this user?}
user.usergroup.can_nick = {boolean; permit user to change his/her name using /nick command}
user.usergroup.level = {numeric; specify user rank/level used in room access control.}
user.usergroup.title = {string; optionally used to specify a user group title.}
Recommended Parameters for Administrators, Moderators & Guest Speakers:
user.usergroup.is_admin = {boolean; Define this user as an Administrator?}
user.usergroup.allow_html = {boolean; allow HTML content in messages?}
user.usergroup.can_kick = {boolean; Permit user to kick other users?}
user.usergroup.can_affect_admin = {boolean; Permit user to affect administrators?}
user.usergroup.can_grant = {boolean; can this user grant administrative privileges?}
user.usergroup.can_cloak = {boolean; can this user cloak?}
user.usergroup.can_see_cloak = {boolean; can this user see cloaked users?}
user.usergroup.login_cloaked = {boolean; forces user to be logged in cloaked.}
user.usergroup.can_ban = {boolean; can this user ban IP addresses?}
user.usergroup.can_ban_subnet = {boolean; can this user ban Class C subnets?}
user.usergroup.can_system_speak = {boolean; can this user speak as the system user?}
user.usergroup.can_silence = {boolean; can this user silence others?}
user.usergroup.can_fnick = {boolean; permit user use of /fnick command?}
user.usergroup.can_launch_website = {boolean; permit user to launch websites for other users?}
user.usergroup.can_transfer = {boolean; permit user to transfer users to another room?}
user.usergroup.can_join_nopw = {boolean; permit user to join password protected rooms freely?}
user.usergroup.can_topic = {boolean; permit user to set room topics?}
user.usergroup.can_close = {boolean; permit user to close rooms?}
user.usergroup.can_ipquery = {boolean; permit user to query IP addresses of other users?}
user.usergroup.can_geo_locate = {boolean; permit user to query geographic location of other users?}
user.usergroup.can_query_ether = {boolean; permit user to query ether?}
user.usergroup.can_clear_screen = {boolean; permit user to clear screens of other users?}
user.usergroup.can_clear_history = {boolean; permit user to clear recent room history?}
user.usergroup.allow_img_tag = {boolean; permit use of IMG BBCode tag?}
Parameters Specific to Moderated Events: (Enterprise Editions)
user.usergroup.is_speaker = {boolean; Define this user as a Guest Speaker?}
user.usergroup.is_super_moderator = {boolean; permit this user to Moderate events?}
user.usergroup.can_enable_moderation = {boolean; permit user to enable room moderation?}
user.usergroup.is_unmoderated = {boolean; permit user to send un-moderated messages?}
Remote Administrator Console Parameters:
user.usergroup.allow_admin_console = {boolean; permit use of Remote Administrator Console (RAC)?}
user.usergroup.can_view_transcripts = {boolean; permit user to view transcripts within RAC?}
Daisy Chain Parameters: (Advanced Use Only)
auth.daisy = {url; RAS script to process before current script.}
auth.daisy.retreat {none; Retreat to previous script in daisy chain.}
numeric : A signed 32 bit integerPARAMETER NOTES
boolean : A single 0 (zero) or 1 (one) to indicate false or true respectively.
string : An unquoted string of ASCII or UTF-8 characters
url : A fully qualified web address, beginning with http://
none : A parameter which requires no value
Starting with RAS v2.1, we recommend setting the user.usergroup.id parameter to 0 (zero) for complicated scripts. Scripts that consult a database with a single, signed integer user group should use their system's user group ID number instead. By setting the user.usergroup.id parameter to 0, the AddonChat server will automatically match the provided user group privileges with other user groups in use; if no match is found a unique user group ID will be automatically assigned.
This parameter allows you to specify the icon to be used for the user group privilege set provided. The following built-in icons are provided for your use:
Custom user group icons (See Icons & Avatars: Emoticons: Advanced Help: Custom Icons: Custom User Group Icons) may also be used. To use a custom user group icon, simple add 100 to the ID number of your custom user group icon. E.g., if you have created an icon called icon.usergroup.custom.2, your script should output the following:
- 0: Blue Pawn Icon (Typically used for regular, non-administrative users)
- 1: Green Pawn Icon (Typically used for Guest Speakers in moderated Enterprise events)
- 2: Red Pawn Icon (Typically used for Administrators)
- 3: Yellow Pawn Icon (Typically used for Moderators in moderated Enterprise events)
- 4: White Pawn Icon (Typically reserved to indicate VIP status of user)
user.usergroup.icon = 102
A user group level should be provided if you're restricting room access based on Rank Access Permissions (Rooms tab in your control panel) The value specified must be between 1 and 20. Level 1 is typically reserved for no-access privileges. If you are not using rank access room permissions, your default (Guest) user group setting should suffice.
This parameter was provided in RAS v2.1 by popular request. It is important to note that when providing users with the ability to change their names using this parameter, that your authentication script will not be consulted again when a user performs a /nick (user name change) command. I.e., they could easily change their name to that of an administrator or a guest speaker if that user is not currently logged in. It is recommended that this privilege only be given to trusted users. If you intend to restrict use of this feature to trusted administrators only, the user.usergroup.can_fnick parameter should be used in preference to user.usergroup.can_nick.
The user.usergroup.allow_img_tag privilege should only be given to trusted users. The IMG BBCode tag permits the user to display an image from any location on the web to all users within the current room. Dial-up users may not appreciate having to wait for very large images to download, and there exist no means to easily moderate image content.
The user.usergroup.is_admin parameter is only a privilege in the sense that it prevents users who do not have the user.usergroup.can_affect_admin privilege from taking certain actions (e.g., silencing, kicking, banning, etc..) against them. In RAS v2.0 (the previous version) this parameter was a prerequisite to other administrative functions; this is no longer the case. Users without the user.usergroup.is_admin privilege may still be given any other privilege/parameter defined in RAS v2.1.
Beginning with AddonChat v8.5, RAS v2.0 and RAS v2.1 now support daisy chaining up to three remote authentication scripts. Enterprise level chat rooms which are used on multiple systems (for example, two separate bulletin board systems) can use daisy chaining to permit authentication from multiple sources using a single Enterprise account. For security purposes, the auth.daisy parameter should be output before any other content; including the scras.version parameter. When the AddonChat RAS processor detects a valid auth.daisy parameter value, it will immediately proceed to process the specified script. The auth.daisy.retreat parameter (which requires no value be specified) will cause the RAS processor to immediately cease processing the current authentication script and fall back to the previous script in the chain. Careful thought and caution should be taken when implementing a RAS daisy chain; including consideration for the possibility that identical user names may be in use on multiple systems. The auth.daisy parameter may be used to daisy chain to an older (1.x) RAS version; however RAS v1.x scripts may not include the auth.daisy or auth.daisy.retreat parameters.
EXTERNAL / REMOTE FUNCTION INTEGRATION (ADVANCED)
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 web site. See the External (Remote) Functions knowledge base article for more details regarding this. The third parameter specifies the browser frame or window name that the link should open 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.
UNDOCUMENTED SCRIPT OUTPUT PARAMETERS (NON-AUTHENTICATION RELATED)url.remote.room.0 = "Room Function 0", "http://www.mysite.com/room_function.pl", "_blank", "false"