Skip to main content
Version: 8.2405.x.x RR

RADIUS facade

RADIUS is a UDP based client-server protocol for authentication, authorization and accounting ("Triple-A") of users dialing into a network. The nevisAuth RADIUS facade provides an adapter through which RADIUS clients are integrated into a Nevis environment. The facade is configured by defining RadiusService blocks in the main configuration file of nevisAuth (the esauth4.xml file).

  • Attribute value pairs (AVPs) of incoming RADIUS requests are mapped directly into the inargs scope.
  • The incoming RADIUS request is transformed into a corresponding nevisAuth request and forwarded to the AuthEngine.
  • The resulting AuthResponse is evaluated and translated into a RADIUS response that is sent back to the client. AVPs are mapped according to the configuration leveraging the variable substitution mechanisms of nevisAuth.

A RadiusService configuration has the following basic structure:

<RadiusService SSODomain=".." listenAddress=".." secret="..">
      <!-- A set of input mappings -->
      <RadiusInput type=".." inArg=".."/>
      ..
      <!-- A set of possible responses with conditions -->
      <RadiusResponse code=".." if="..">
           <!-- A set of attribute mappings -->
           <RadiusAttribute type=".." value=".."/>
           ..
      </RadiusResponse>
      ..
</RadiusService>

Configuration​

The following list describes the configuration elements of the RADIUS facade.

  • <RadiusService>

    Defines a RADIUS service that listens on authentication and accounting ports. Contains the mapping for incoming RADIUS requests and a set of RADIUS response building rules.

    • listenAddress (string, required)

      An IP or a hostname to listen on

    • SSODomain (string, required)

      Incoming/valid RADIUS requests are forwarded to this domain. If received on the authentication port, an "authenticate" method is used. If received as accounting, a "stepup" is performed.

    • stateless (boolean, false)

      If set to true, the session will be killed immediately after processing in the AuthEngine has finished. Set to false if sessions are required.

    • threadPool (integer, 50)

      The maximum number of simultaneously running threads, which will process incoming RADIUS requests.

      The speed of processing is chiefly defined by the speed of authentication-relevant back ends such as LDAP servers and DBs. While waiting for the response of a back end, the thread processing the RADIUS request is blocked. Set the size of the thread pool accordingly.

    • queueSize (integer, threadPool*10)

      The maximum number of RADIUS requests queued while waiting for a worker thread to become free. When the queue is full any additionally received requests are dropped without sending a response.

    • keepAlive (integer, 30000, ms)

      The maximum time a request will remain in the queue before being marked as stale. This should match the clients time-out (5-30sec).

    • authPort (integer, 1812)

      The port for the UDP socket to listen for incoming RADIUS authentication requests.

    • acctPort (integer, authPort+1)

      The port for the UDP socket to listen for incoming RADIUS accounting requests.

    • secret (string, -)

      A shared secret a between a server and all its clients. See the Generic key material - Configuration attributes on hiding secrets.

  • <RadiusResponse>

    A generation rule for a RADIUS response. All rules are evaluated from top to bottom to find a matching condition. The first match will be used to generate the response. RADIUS attributes are filled as defined in the contained mapping. If no match can be found, the request is dropped without sending a response. For internal use it is advised to add a default reject config, even if the RADIUS standards specifies conditions under which a packet should be dropped silently.

    • code (string or 1-255, -)

      The code defines the RADIUS response for the response. It is either a keyword from the dictionary or any number between 1 and 255. The most commonly used codes are: "Access-Accept" (2), "Access-Reject" (3), "Accounting-Request" (4), "Accounting-Response" (5), "Access-Challenge" (11). All keywords defined by RFC3575 may be used.

    • if (string, -)

      The condition which must be fulfilled to send this RADIUS response. If this attribute is not set, it defaults to true. If the attribute value evaluates to the empty string (no match in case of a regular expression), the condition is not fulfilled.

      if="${response:status:1}" (evaluates to true if the processing resulted in a AUTH_DONE)
      if="${response:result:lockWarn}" (evaluates to true if the last AuthState transition was "lockWarn")

  • <RadiusInput>

    A mapping from a RADIUS attribute to an InArg value.

    • type (string or 1-255, -, required)

      The type describes a RADIUS attribute type (AVP-key) or a vendor specific attribute type (VSA-key). It can be any keyword from the dictionary or a number between 1 and 255.

      Commonly used types are: "User-Name" (1), "User-Password" (2), "NAS-IP-Address" (4), "NAS-Port" (5), "Reply-Message" (18), ....

    • inArg (string, -, required)

      The key of the nevisAuth input argument. Common inArgs are "isiwebuserid" and "isiwebpasswd" for username and passwords, respectively.

      This argument must be unique for the RADIUS service.

  • <RadiusAttribute>

    A value for an attribute in an outgoing RADIUS packet.

    • type (string or 1-255, -, required)

      Similar to the RadiusToNevisMapping: The type describes a RADIUS attribute type (key). It can be any keyword from the dictionary or a number between 1 and 255.

      The type must be unique per Builder.

    • value (string, -, required)

      Value is a substitutable expression that is evaluated and assigned to the specified AVP.

RadiusInput​

The "type" specifies a key for a RADIUS attribute (AVP). Any word from the predefined dictionary may be used or an attribute number can be set directly (from 1 to 255). It can also be a keyword for a vendor specific attribute (VSA).

  • The RADIUS attribute type "User-Name" is equivalent to "1".
  • The VSA type "WISPr-Location-ID" defines the VSA 1 of AVP "Vendor-Specific".

If the mapping goes from RADIUS to Nevis, the inArg specifies the key of the input argument property. This inArg is part of the AuthRequest sent to the AuthEngine and comparable to input fields in a form. Common values are for example "isiwebuserid" and "isiwebpasswd" for username and password, respectively.

If a received RADIUS request does not contain an AVP specified in a mapping, it is ignored. Other than that, the input mapping is a static mapping without conditions.

All AVPs are converted to strings. Binary attributes are converted to Base64. Enumerated attributes of type integer are mapped to the identifier specified in the dictionary.

Examples:

  • An attribute of type "NAS-IP-Address" can map to the string "127.0.0.1".
  • An attribute of type "State" is binary and can map to a Base64 encoded string such as "dGVzdAo=".
  • The attribute "Service-Type" is an enumerated integer. Assuming this attribute holds the value 3, it is mapped to "Callback-Login-User", according to the dictionary in use.
info

Special case: If PAP authentication is used, the binary attribute "User-Password" (2) is mapped to plaintext for convenience.

Use the TransformAttributes AuthState for complex transformations of input values.

RadiusAttribute​

A mapping of a value to an attribute in an outgoing RADIUS packet.

The "type" specifies an AVP via keyword or a number (1..255) as before. The same holds for vendor specific attributes.

The "value" can be a constant or a Nevis variable expression. The class of the value must match the type of the AVP. If any mapping fails, no packet is sent at all.

  • An attribute of type "NAS-IP-Address" must be filled with a valid IP-address.
  • Binary attributes must be filled with Base64 encoded values.
  • Enumerated integer attributes can be filled with an identifier or a valid integer. For example "Service-Type" accepts "Callback-Login-User" as well as "3".
info

The "Proxy-State" (type 33) is always filled with the proxy state of the incoming packet if present. This allows propagation through a basic RADIUS proxy. The value can be overwritten by the mapping.

Default dictionary​

Instead of working with RADIUS type numbers, it is more convenient to use identifiers provided by the dictionary. Certain types, for example all vendor specific ones, are only accessible using identifiers. The dictionary can be found in the default config directory: /var/opt/nevisauth/default/conf/radius_dictionary.

An alternative location may be configured using the following system property: ch.nevis.esauth.auth.adapter.radius.defaultDictionary

The dictionary may be extended to support new vendor attributes. The format is described in the dictionary file itself and is compatible to the ones used by wireshark and freeradius.

As an example, a small subset of frequently used attributes is given.

ATTRIBUTE User-Name 1 string
ATTRIBUTE User-Password 2 octets
ATTRIBUTE NAS-IP-Address 4 ipaddr
ATTRIBUTE NAS-Port 5 integer
ATTRIBUTE Service-Type 6 integer
ATTRIBUTE Reply-Message 18 string
ATTRIBUTE Vendor-Specific 26 octets

Values of enumerated integers are also translated to its identifiers. As an example, the service type is given:

VALUE Service-Type Login-User 1
VALUE Service-Type Framed-User 2
VALUE Service-Type Authenticate-Only 8
VALUE Service-Type Callback-NAS-Prompt 9
VALUE Service-Type Authorize-Only 17

Vendor specific attributes (VSA) are a special case of RADIUS attributes wrapped by the "Vendor-Specific" (26) AVP as defined in RFC 2138. This attribute should never be used directly. Instead, VSAs should be defined in the dictionary and treated as normal attributes, letting the RadiusService take care of the internals.

Identifiers for a set of RADIUS package codes are hard coded. A subset is provided here:

CODE Access-Request 1
CODE Access-Accept 2
CODE Access-Reject 3
CODE Accounting-Request 4
CODE Accounting-Response 5
CODE Password-Reques 7
CODE Password-Ack 8
CODE Password-Reject 9
CODE Accounting-Message 10
CODE Access-Challenge 11
CODE Next-Passcode 29
CODE New-Pin 30

Limitations​

EAP is currently not supported and no defragmentation of attributes takes place.

Multiple AVPs of the same type in a single RADIUS packet are not supported by the mapping mechanism and will cause the processing of a request to fail. Exceptions to this rule are the vendor specific attributes which will work using dictionary-identifiers.