Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation  Back up to About Overview 
  
[+] Expand All
[-] Collapse All

Writing Steel-Belted Radius Carrier Scripts in JavaScript

This section provides general information and guidelines for writing Steel-Belted Radius Carrier scripts in JavaScript. For descriptions of the Steel-Belted Radius Carrier API functions available to LDAP, realm selection, and attribute filter scripts, see Script Reference.

Programming in JavaScript

The Steel-Belted Radius Carrier script engine supports JavaScript 1.7 (ECMA-262). You can use any legal JavaScript syntax in your scripts and invoke the standard global object function and attributes, such as Math, String, and Date.

The JavaScript engine runs entirely within the Steel-Belted Radius Carrier server and is not associated with any Web browser. Browser-specific data objects and JavaScript language extensions are not supported by Steel-Belted Radius Carrier.

For in-depth information about JavaScript programming, see the official ECMAScript standard documentation at this URL:

http://www.ecma-international.org/publications/standards/Ecma-262.htm

Hidden Wrapper Function

Before Steel-Belted Radius Carrier compiles your script, it wraps the [Script] section statements in a JavaScript function named _sbrScriptMain_. When the server executes the script, the script invokes this function first. There are no arguments to the function call.

The hidden wrapper function enables your scripts to return result values to the server. This is required because the JavaScript language does not support return statements from the global execution context. For convenience, the hidden function call does not appear in script traces, and line numbers in script traces and error messages are adjusted to refer to the exact lines of your JavaScript initialization files.

With few exceptions involving advanced JavaScript programming, the existence of the hidden wrapper function is transparent to your scripts.

Script Return Values

Steel-Belted Radius Carrier uses the script return value to determine what action to take on the pending RADIUS request once the script finishes executing. The script type determines how the return value is interpreted by the server. A legal return value must be:

  • A pre-defined return code such as SCRIPT_RET_SUCCESS
  • A text string
  • The JavaScript null object

The SCRIPT_RET_SUCCESS and the SCRIPT_RET_FAILURE codes are defined in the global object for all script types. Returning SCRIPT_RET_SUCCESS indicates to Steel-Belted Radius Carrier that script execution completed normally.

Returning SCRIPT_RET_FAILURE indicates that an unexpected error occurred during script execution (for example, a database search returned invalid results). If a script returns SCRIPT_RET_FAILURE and a [Failure] string is defined for that script, that string is returned as the script result. Otherwise, an error message appears in the server log and the pending RADIUS request is rejected.

Result strings are used by realm selection scripts to return the name of the selected realm. Attribute filter scripts use result strings to return the name of a static filter to execute.

Returning JavaScript null is equivalent to returning SCRIPT_RET_SUCCESS.

The processing of return codes by LDAP authentication scripts is more complicated than for other script types. For information about choosing the LDAP authentication script return code, see Choosing the Return Code.

Initializing Reusable Data Objects

In JavaScript, when you declare a variable using the var keyword, that variable is allocated temporarily on the program stack. When your script returns, the variable goes out of scope and is marked for garbage collection by the script engine. However, variables declared without a var keyword become properties of the script engine’s Global object and persist across invocations of the script.

To avoid allocating and deallocating data objects each time a script runs, you can create initialization blocks to allocate reusable global objects the first time a script runs. These objects remain available to use in subsequent executions of the script. This code example shows this technique.

// Initialization block
if (!this.initialized) {// Create persistent data as global object properties.filter = new AttributeFilter();accessor = new DataAccessor();someString = “This is a persistent string”  // Set initialized flag for next time.initialized = true;}
else {// /Clear left-over data from prior request.accessor.Clear();}

In this example, the variable initialized is a global flag that is tested each time the script runs. If initialized is not set, the persistent data objects are allocated and the flag is set. On subsequent calls to the script, the initialization block is skipped but a call is made to clear the prior contents of the Data Accessor.

General Recommendations

Follow these recommendations when developing Steel-Belted Radius Carrier scripts.

  • JavaScript comments begin with // or /*. Within the [Script] section, lines starting with a semicolon (;) are not treated as comments. In these example, compilation fails with a syntax error because the commented-out [Failure] section is passed to the JavaScript compiler.
    [Script]SbrWriteToLog(“hello, world” );return SCRIPT_RET_SUCCESS;;[Failure];SomeString
  • Thoroughly test all scripts for speed and monitor the performance of Steel-Belted Radius Carrier after you deploy a new script. In general, the performance impact of a script on the server is directly related to its complexity.
  • After you modify a realm selection or attribute filter script, you can reload it by executing a platform specific HUP command. It is not necessary to restart the server. You cannot use the HUP command to reload LDAP scripts.

Modified: 2017-03-07