RADIUS PAP

Introduction

Use this valve to authenticate a user against a RADIUS server using PAP (Password Authentication Protocol). The valve sends an Access-Request and resolves on Access-Accept or rejects with an error on Access-Reject.

Optionally the valve handles a two-step Access-Challenge → OTP flow when the otp property is configured. In that case, the State attribute returned in the challenge is automatically included in the follow-up Access-Request.

On a successful Access-Accept, any response attributes returned by the RADIUS server are exported to the current item as radius_attr_<type>. Text attributes (printable UTF-8) are stored as strings; binary attributes are stored as lowercase hex.

Prerequisites

Before using this valve the RadiusClient module must be configured and deployed.

Configuration

Note

Valve name: RadiusPAP

Properties

Name	Description	Default	Mandatory	Expanded
username	RADIUS User-Name sent in the Access-Request.
password	RADIUS User-Password sent in the Access-Request.
otp	OTP value sent in the follow-up Access-Request after an Access-Challenge. When omitted, challenge responses cause the valve to fail.
destination	RadiusClient instance to use.	default
request_attrs	Optional array of additional RADIUS attributes to include in every Access-Request sent by this valve. The value field is template-expanded per request. See Request attributes.

Example

{
  "name": "RadiusPAP",
  "config": {
    "username": "${request.identifier}",
    "password": "${request.password}",
    "destination": "default"
  }
}

Example (with OTP)

{
  "name": "RadiusPAP",
  "config": {
    "username": "${request.identifier}",
    "password": "${request.password}",
    "otp": "${request.otp}",
    "destination": "default"
  }
}

Example (with request attrs)

{
  "name": "RadiusPAP",
  "config": {
    "username": "${request.identifier}",
    "password": "${request.password}",
    "destination": "default",
    "request_attrs": [
      { "type": 30, "value": "${item.station_id}" },
      { "type": 31, "value": "${request.phone}" }
    ]
  }
}

Request attributes

The request_attrs array lets the operator include additional RADIUS attributes in every Access-Request sent by this valve. The value field supports template expressions and is expanded per request, making it suitable for dynamic values such as the calling station or NAS port.

Note

Static attributes that are the same for every request (e.g. NAS-Identifier) should instead be configured on the RadiusClient module using its own request_attrs. Valve-level attributes are appended after module-level attributes in the outgoing packet.

Caution

Attribute types 1 (User-Name) and 2 (User-Password) are reserved and cannot be used in request_attrs.

Properties

Name	Description	Default	Mandatory
type	RADIUS attribute type code (integer, 3–255).
value	Attribute value as a template expression, expanded per request.
value_type	Encoding of the value. One of: string (UTF-8), integer or time (4-byte big-endian), ipaddr (dotted-decimal IPv4), ipv6addr (IPv6), octets (hex-encoded raw bytes).	"string"

Example

"request_attrs": [
  { "type": 30, "value": "${item.station_id}" },
  { "type": 31, "value": "${request.phone}" },
  { "type": 5,  "value": "${item.nas_port}", "value_type": "integer" }
]

Item handling

The valve accepts 0 or 1 items in the current item set:

• 1 item — the existing item is used as context for template expansion and RADIUS response attributes are set on it.
• 0 items — the valve creates a new item using the expanded username as ID. Response attributes are set on the created item.
• More than 1 item — the valve fails with an error.

Response attributes

On Access-Accept, all RADIUS response attributes are exported to the item as radius_attr_<type>:

Item property	Description
radius_attr_18	Reply-Message — decoded as UTF-8 string when printable
radius_attr_6	Service-Type — stored as hex (4-byte integer)
radius_attr_<N>	Any other attribute type returned by the server

Text attributes (all bytes printable, no control characters) are stored as UTF-8 strings. Binary attributes such as State (24) or 4-byte integers containing null bytes are stored as lowercase hex strings.

These values are available in subsequent valves via ${item.radius_attr_<N>}.

Authentication pipe example

A simple RADIUS PAP authentication pipe:

{
  "id": "radius-auth",
  "config": {
    "valves": [
      {
        "name": "RadiusPAP",
        "config": {
          "username": "${request.identifier}",
          "password": "${request.password}",
          "destination": "default"
        }
      }
    ]
  }
}

Two-step OTP flow

When the RADIUS server responds with Access-Challenge, the valve automatically sends a follow-up Access-Request using the configured otp value and the State attribute from the challenge:

{
  "name": "RadiusPAP",
  "config": {
    "username": "${item.id}",
    "password": "${request.password}",
    "otp": "${request.otp}",
    "destination": "default"
  }
}

The flow becomes:

1. Access-Request (username + password)
2. RADIUS → Access-Challenge (state)
3. Access-Request (username + otp + state)
4. RADIUS → Access-Accept / Access-Reject