18.12. Using RADIUS

RADIUS can be used to allow new handsets to be registered dynamically without individual configuration by using RADIUS authentication to an external RADIUS server. RADIUS is also used to make call routing decisions.

RADIUS accounting can be used to log calls as they start and end to an external RADIUS server.

Note

RADIUS for VoIP is only available on a fully-loaded model.

Tip

You have to configure each of the radius functions in the VoIP config - leaving the radius setting unset will disable use of RADIUS for that feature. There are separate configuration settings for register, call and cdr.

18.12.1. RADIUS accounting

RADIUS accounting logs each call leg, so a typical call has an incoming and outgoing leg.

  • A RADIUS START message is sent when the call leg is created.
  • A RADIUS INTERIM update is sent if/when the call connects (i.e. status 200).
  • A RADIUS STOP message is sent when the call ends, even if it did not connect.

An interim update includes a call duration which is the time spent ringing. A final (stop) message contains a call duration which is the time from the connection of the call.

18.12.2. RADIUS authentication

RADIUS authentication is used for any requests with Authorization header, such as REGISTER, INVITE, REFER, SUBSCRIBE, OPTIONS etc. The Digest-Method is always included to indicate a VoIP request and identify the type of request.

You can have a RADIUS authentication before the FireBrick challenges the requestor setting the radius-challenge settings, allowing a RADIUS challenge response to customise the challenge. This also happens for a non local request where the user is not recognised as a local telephone user. Otherwise the FB2900 will send a challenge automatically and only send a RADIUS authentication when the authenticated message is received. This also happens if an Authorization header is presented without a response value.

Tip

For an unauthenticated request you can respond with an Access Challenge including the paramaters to challenge, but any attributes you omit will be completed automatically, so you can simply respond with an empty challenge to confirm the FB2900 is to go ahead and do the challenge itself.

For REGISTER an accept response can include a Called-Station-Id attribute to define the registered connection as a tel:number URI for call routing. Without this, the registration is not logged on the FB2900 and it is assumed the RADIUS server will record where to send calls based on the registration. The SIP-AOR AVP in the access request provides the Contact URI, and can be used in the reply to cause a 302 redirect response to a specified contact.

  • An access request is sent to approve any SIP request such as REGISTER, SUBSCRIBE, OPTIONS, etc.
  • An access request is sent to make call routing decision for INVITE and REFER.
  • An access request is sent to make a call routing decision when a 3xx response is received from a connection being made to a telephone. Acct-Terminate-Cause specifies the redirect code, e.g. 301, 302.

Access requests are made even when the request is coming from an locally configured telephone. In such cases the telephone must also pass validation against a locally configured password (if present). To identify such requests, the User-Name is the configured name (or extn or ddi) of the telephone user, and the Chargeable-User-Identity attribute is set based on the configured CUI.

Access requests are made even when from a recognised carrier. In such case the carrier is validated by the FireBrick directly, and then the access request is made to decide call routing. To identify such requests, the User-Name is the configured name of the carrier prefixed with an @ character.

Note

In the case of a telephone user, any @ characters at the start of the name are removed so that it cannot be confused with a carrier.

Note

A call can come from anywhere. An unknown request from a non local IP will send a RADIUS request before challenging the requestor so that the RADIUS server can decide if it is to be challenged or not. An Access reject with no message attribute will not send any error to a non local IP requestor - add a message to force this.

18.12.2.1. Call routing by RADIUS

To understand how call routing works you need to understand how call legs work. A call leg is a connection to or from the FB2900 to another SIP device. It could be a SIP carrier or a telephone. Typically there is an incoming call leg from a carrier or a phone, which needs to be authenticated, and then a call routing decision is made.

An Access Accept response can then contain the call routing attributes. This causes one or more outgoing call legs to be created. These would typically be ringing telephones. Once one of these legs answers the others are cancelled and the two legs are connected together to form a call. The purpose of the routing attributes is to create these outgoing call legs, and to set up attributes such as CDRs and call recording.

Each call leg has a CLI (calling number), a Dialled number, a display Name, a number of CDR records (each of which have CDR and Dialled as well), and finally a number of email addresses for call recording.

The response attributes are processed in order. Initially the last call leg is the originating call. When a new outgoing leg is added, that becomes the current call leg.

Table 18.3. Access-Accept

AVPNo.Usage
Calling-Station-Id31Replaces CLI of current call leg.
Called-Station-Id30Replaces Dialled number of current call leg.
User-Name1Replaces the Name of the current call leg.
Filter-Id11Adds a call recording email address to the current call leg.
Chargeable-User-Identity89Adds a CDR record with this CUI, and current CLI and Dialled attributes to the current call leg.
SIP-AOR121Creates a new outgoing call leg. See below for formats

An outgoing call leg is created for each SIP-AOR entry, and it can be in one of the following formats. Each of these can also include a number of digits and a + symbol at the start which specifies a delay before attempting to connect the outgoing leg.

  • number@carrier which causes a call via a known carrier. The part after the @ is the name of the carrier in the config. The Dialled number is set to the number specified, and the CLI is set from the originating call.
  • tel:number which causes a call via a registered telephone. The Dialled number is set to the number specified, and the CLI is set from the originating call.
  • sip:uri which causes a call via a an arbitrary SIP URI. The Dialled number and CLI are set from the originating call. This format allows sip:number@host and sip:user:pass@host and also sip:user:pass@host/number. This final version makes a call using the sip:number@host target but authenticates using user and pass.
  • NNN a custom response code, such as 404, 500, etc, can be provided to indicate that the call is actually to be rejected.
  • 3NN:URL A 3NN response code can be used, where 3NN is then replaced by sip: in the contact in the response. This feature is somewhat experimental.

Tip

If the originating call leg is incoming and not get been connected, a single SIP-AOR response can be provided in the format of a 3 digit response code, or 3xx:uri where 3xx is the response code (e.g. 302) and is replaced by sip: and used as a Contact header in a 3xx response. Redirect only works on some carriers/phones and serves to redirect the incoming call away from the FB2900.