This chapter describes how to use the authentication, authorization and accounting (AAA) modules in Oracle Communications Billing and Revenue Management (BRM) RADIUS Manager. Features of these AAA modules are also described:
BRM authentication and authorization module - mod_pin
Plain text authentication module - mod_text
Password authentication module - mod_unixpwd
Forwarding authentication requests to an external RADIUS server - mod_proxy
Selectively responding to RADIUS requests - mod_null
Before reading this chapter you should be familiar with "Understanding RADIUS Manager Modules".
To design module chains which process AAA requests, you need to understand these concepts:
local authentication
remote authentication
cascading authentication
Any local authentication request is a known request since you authenticate using the BRM database. RADIUS Manager uses the module, mod_pin, to perform authentication, authorization and accounting functions against your BRM database. All local BRM users log in with their user name.This is the default authentication method.
An authentication request from a remote server is an unknown request since AAA functions cannot be performed against the BRM database. BRM supports both VPDN and iPass roaming for remote users. Remote users log in using their full email address, including the user name, @ symbol, and domain name. Two types of authentication are available for managing unknown requests:
Password authentication. This method uses the mod_unixpwd module for password authorization.
Plain text password authentication. Uses the mod_text module to perform authentication against a text list of user names and passwords.
Unknown authentication requests require multiple authentication methods and are handled using a cascading authentication scheme.
Remote, or unknown, authentication requests require that you use more than one authentication method. To do this you must configure the RADIUS server to perform cascading authentication. This allows authentication requests to cascade from the most restrictive authentication check to the least restrictive check. Cascading authentication ensures that all requests are processed by the appropriate module.
For example, a check for *@isp.com should be performed before a check for *@*. If the less restrictive *@* check is placed before the more restrictive *@isp.com check, the request will never reach the more restrictive check.This is important for unknown authentication requests using iPass and VPDN where your RADIUS server does not perform the authentication. For information, see "Using a Virtual Private Dialup Network (VPDN)".
Three module configuration entries directly affect how requests are processed through a module chain which uses cascading authentication. These entries define how requests are passed from one module to another:
Ignore-No-Entry: Allows a failed accounting request to pass to the next module in the chain. This entry is supported by all modules except the proxy authentication module (mod_proxy).
Ignore-No-Response: This entry is used by the proxy authentication module (mod_proxy) It allows a failed authentication request to pass on to the next module worker class in the chain.
Class: The Class attribute is appended to accounting requests during authentication. Use it to indicate which module should the accounting request. The Class attribute is specified in the RFC 2865 and should be supported by your NAS.
Use the Class attribute whenever you use multiple authentication methods. The Class attribute ensures that accounting requests are handled efficiently.
For example, if the authentication request is from an iPass user, the reply packet is appended to contain the Class=ipass attribute-value pair. When the corresponding accounting request is received by the RADIUS server, the module worker classes checks the Class attribute to determine whether it should process the accounting request, or pass it to the next module worker.
This example shows the syntax for appending the Class attribute. In this example, the authentication request is for an iPass account. The send element is used to append the attribute-value pair iPass to the corresponding accounting request.
...
#Authentication Request#
{
type = mod_text
check {
Pseudo-Request-Type = Authentication-Request
}
send {
Class="ipass"
}
options=Ignore-No-Response
}
...
#Accounting Request#
type = mod_text
check {
Pseudo-Request-Type = Accounting-Request
Class="ipass"
}
}...
The module mod_null must always be the last module in the chain. Otherwise, incoming authentication and accounting requests are misdirected before special processing of the packets is performed. For information on mod_null, see "Selectively Responding to RADIUS Requests with the null Module".
The mod_pin module provides authentication and accounting support, and performs standard check processing for RADIUS requests. The mod_pin module supports:
User accounts with a /service/ip service
VPDN authorization and accounting.
iPass integration.
An authentication request is sent to the BRM database to authenticate a user name.
If the user name is found and authentication succeeds, the request is sent to BRM. The request includes any send attributes required to find the session setup information for the user.
If the user name is not found, the Ignore-No-Entry option specifies whether processing continues or NAK is returned.
If the user name is found, but authentication fails, NAK is returned.
If the authorization succeeds, an ACK is returned, including any attributes returned from the opcode.
If authorization fails, NAK is returned and the user is denied access.
This section describes the global settings that can be defined for the BRM authentication module (mod_pin). You configure these settings in the $CONFIG section of the RADIUS configuration file (BRM_home/apps/radius/config, where BRM_home is the directory in which BRM components are installed).
Set the timezone entry to define the time zone where your RADIUS Manager is physically located. RADIUS Manager sends the information in the TIMEZONE_ID string to the BRM server. The BRM server uses the time zone for rating purposes. If the time zone is not set, the default setting NULL allows real-time rating to use the RADIUS server's time zone. If RADIUS Manager, the NAS, and the end user are in different times zones, RADIUS Manager uses the time zone of the NAS.
The time zone string should use standard Java time zone ID format (see "About Time Zone IDs" in BRM Setting Up Pricing and Rating.) Wherever possible, use the unambiguous long descriptive format. (The short abbreviation is error-prone.)
For example:
timezone-id = "America/Los_Angeles"
If no standard Java time zone IDs are available for a particular time zone, then RADIUS Manager can accept encoded custom time zone strings in the format "GMT+14." You must set the number of seconds + (West) or - (East) of GMT.
For more information about time zones, see "Using the Correct Time Zone" in BRM Setting Up Pricing and Rating.
The charge_on_reboot entry controls how Accounting-On events are handled after a NAS system crash. Normally, a user is billed for the period between session start and session end. If the NAS crashes, the session is unexpectedly terminated without the standard session end calls.
The charge-on-reboot entry allows you to define how Accounting-On events are billed once the NAS has been restarted. Two values are available, charge and no charge.
If no charge (nc) is selected, then the user will not be charged for the period of the system crash. Session billing begins when the NAS is restarted and the Accounting-On events are sent. No charge (nc) is the default.
Selecting the charge (c) value will charge the user for the period between the original session start and the NAS restart when the Accounting-On events are sent to BRM. Selecting this option bills the customer for the entire period including the time of the system crash.
charge-on-reboot=NC
You can use the network entry to list the network name. This entry is used only when you need to track audit information on multiple networks. If the network name is supplied, it is stored in the /event/session/dialup storable object.
This section describes the settings you can configure for instances of mod_pin in the $MODULES section of the RADIUS configuration file (BRM_home/apps/radius/config). The mandatory type entry is mod_pin.
Use the check and send requests specify how RADIUS requests are processed.
type=mod_pin
check {
attribute = value ...
...
}
send {
attribute = value ...
...
}
Note:
You should configure mod_pin module after configuring all the other modules, as it prepares the RADIUS response and sends the response back to the client. Due to this, post processing of opcode is not possible when the mod_pin is being used.Use the options-Ignore-No-Entry entry when multiple authentication methods are configured in a cascading chain. If this value is set and a matching user name is not found in the BRM database, the request is sent to the next authentication module in the module chain. This allows an access request to be searched by several different databases.
You can also use the Ignore-No-Entry option when authentication needs to be performed only on the domain name (The domain name is the string after the "@" sign in the User-Name attribute.) If there is no "@" sign, the login name to validate against is empty ("")
options {
Ignore-No-Entry
Use the pass-through entry when multiple authentication methods are configured in a cascading chain. When the pass-through value is set, the request is first sent to the BRM database. If a matching user name and password are found, the request is recorded and forwarded to the next module in the chain.
Use this entry when you need to track access requests in BRM, but use another database for authentication. No response is sent back to the NAS, so that the mod_pin module behaves as a support or non-terminating module.
Important:
When the pass-through value is selected, mod_proxy must be the next module in the chain.Use the login entry with organizational models, such as VPDN and iPass, when you need to authenticate using only the domain name of the login name. This entry can be set to either a fixed string, like "ipass", or a string-replacement transformation can be applied to it. The default is the value in the User-Name attribute.
login = [fix_string | "Replace/target/replaceStr/"]
Use the desc entry when you need to track usage information for organizational accounts. Setting this entry provides audit information in organizational settings where many users are using a single login account.
For example, if all users from an organization are using the account user@corporate.com, but you need to know which users actually use the account, then you can record user names by setting the desc entry. If a desc value is specified, the actual user login name is recorded as a free text description and stored in the PIN_FLD_DESC field in the input flists.
desc = "... %u ..."
Note:
The %u setting maps to the user login and is the only available option.Use the service_type entry to track and route subtypes of the /service/ip request type. The service_type entry is useful when an Internet service provider (ISP) offers multiple service types and it is necessary to track requests for each different service type (such as /service/ip/email and /service/ip/broadband). The service_type entry can also be used when you need to route different types of IP service requests to different NAS for authentication.
You can use this entry to define any service type. It is usually used for organizational models such as VPDN. The default value is /service/ip.
service_type = /service/[ip | vpdn | other_services]
Example settings for an instance of mod_pin
This example shows configuration settings for an instance of mod_pin:
type=mod_pin
check {
attribute = value ...
...
}
send {
attribute = value ...
...
}
options {
Ignore-No-Entry
)
desc = "... %u ..."
service_type = /service/[ip | vpdn | other_services]
login = [fix_string | "Replace/target/replaceStr/"]
This sample code is configured to authenticate all requests against BRM. If the Access-Request fails, NAK is not returned. The request is passed on so other authentication mechanisms, such as VPDN or iPass, can be tried.
# Authenticate against Portal
auth_portal {
type=mod_pin
$INCLUDE=Basic-PPP
check {
Psuedo-Request-Type=Access-Request
}
send {
# Send Class=PIN so we can match up accounting requests.
# By returning it to the NAS, the NAS is required to return
# this attribute in Accounting requests.
Class=PIN
}
# If the user isn't in Portal, don't stop
options=Ignore-No-Entry
}
# Store accounting info in Portal.
# Note the match on Class=PIN to ensure that only sessions
# which were authenticated by Portal have the accounting
# data stored in Portal.
acct_portal {
type=mod_pin
check {
Psuedo-Request-Type=Accounting-Request
Class=PIN
}
}
The mod_text module lets you authenticate access requests using plain-text user login and password verification. Only Access-Request requests are considered by this module, other requests are ignored.
Standard check processing is performed against a request.
If the user name is not found, the Ignore-No-Entry option determines if processing continues or NAK is returned.
If a match for the user name is found, the User-Name value is compared with the elements of the password.
If a password match is found, ACK is returned along with any send attributes.
If no password match is found, NAK is returned.
No global configuration settings are supported for the mod_text module. You configure each instance of the mod_text module in the $MODULES section of the RADIUS configuration file (BRM_home/apps/radius/config). The mandatory type entry is mod_text.
In the user block include a list of username=username and password=password pairs which specify the cleartext password for each user name. If the password has special characters, enclose them in quotation marks.
user {
username = userxxxx
password = passxxxx
}
Use the check and send requests to specify how RADIUS requests are processed. See "How RADIUS Requests Are Processed Using check and send Requests".
check {
attribute = value ...
...
send {
attribute = value ...
...
Use the options-Ignore-No-Entry entry to allow an access request to be searched by several different databases. You can also use the Ignore-No-Entry option when authentication needs to be performed only on the domain name.
options {
Ignore-No-Entry
}
The mod_unixpwd module performs authentication against a password file. Only Access-Request requests are processed by this module; other requests are ignored.
Note:
CHAP authentication is not supported by this module because CHAP requires access to clear-text passwords. Attempting to use password authentication with CHAP introduces conflicting encryption methods and fails the procedure.When an access request is sent to the mod_unixpwd module a check is performed against a password database:
If the user name is not found, the Ignore-No-Entry option specifies whether processing continues or NAK is returned.
If a match is found, the domain name is stripped from the User-Name attribute, and checked against the password database.
If a matching User-Name is found, the user password is checked against the password database.
If the password also matches, ACK is returned along with any send attributes, otherwise NAK is returned.
Note:
For security reasons, the User-Name value "root" always fails.No global settings are supported for the mod_unixpwd module. You configure each instance of the mod_unixpwd module in the $MODULES section of the RADIUS configuration file (BRM_home/apps/radius/config). The mandatory type entry is mod_unixpwd.
The check and send requests specify how RADIUS requests are processed.
Use the options-Ignore-No-Entry entry to allow an access request to be searched by several different databases. You can also use the Ignore-No-Entry option when authentication needs to be performed only on the domain name.
options {
Ignore-No-Entry
}
The mod_proxy module forwards incoming requests to an external RADIUS server. All request types are accepted by this module. This module does not support retransmission because it assumes that the request source performs retransmission. Only one mod_proxy module can be used within a cascading authentication configuration.
This module is useful in a variety of scenarios. For example, if you have a legacy RADIUS server and do not want to perform data translation, you can forward requests from RADIUS Manager to the legacy server for authentication. This module is also useful with iPass roaming, since it allows requests to be forwarded from a remote server back to the home ISP for processing.
You can configure the mod_proxy module to proxy (forward) requests of a given type from one server to another server.
When a response is received from the external server, that response is passed back to the client after appending any send attributes.
If no response is received within the specified time-out period, the request is ignored or returns NAK according to the Ignore-No-Response option.
The original packets are not forwarded unmodified. A new RADIUS packet is created based on a new authenticator containing the shared secret for the destination and on the contents of the input request.
You configure these global settings in the $CONFIG block of the RADIUS configuration file (BRM_home/apps/radius/config). Information about both the remote authorization and remote accounting destination server must be set in the server blocks of each mod_proxy instance.
The name is a label used by BRM to reference the destination server(s). Referencing this name in a module configuration provides access to the server information listed in the server block.
name = remote-auth
Use the addr entry to list the IP address or host name of the server to which requests are to be forwarded.
addr = remote-host
Use the port entry to set the IP port to which access requests should be sent. If you define the authorization port using the authport entry then you must also define a port for forwarding accounting requests. Use the acctport entry to define the accounting port.
Example for authorization port:
server {
name = remote-auth
addr = remote-host
port = 1812
Example for accounting port
server {
name = remote-acct
addr = remote-host
port = 1813
Use the secret entry to define the secret shared with the destination server. Make sure this secret is also listed in the client block of your data dictionary. For information, see "Defining the Secret".
secret = testing123
Use these options to define the settings for each instance of the mod_proxy module.
The check and send requests specify how RADIUS requests are processed. See "How RADIUS Requests Are Processed Using check and send Requests".
proxy-auth {
check {
Pseudo-Request-Type = Access-Request
}
dest=server1
send {
Class = "proxy"
}
}
Use the options-Ignore-No-Entry entry to allow an access request to be searched by several different databases. You can also use the Ignore-No-Entry option when authentication needs to be performed only on the domain name.
options {
Ignore-No-Entry
}
Use the Ignore-No-Response option to pass an authentication request that cannot be validated on to the next module. The mod_proxy module waits till the end of the timeout period for a response from the server. After the timeout period, the request is sent to the module in the chain.
Use this option when you wish to configure a back up authentication system. If a remote server is down, this option forwards the request to another server for authentication.
options {
Ignore-No-Response
}
Use the pass-through entry when multiple authentication methods are configured in a cascading chain. When the pass-through value is set, the request is first sent to the BRM database. If a matching user name and password are found, the request is recorded and forwarded to the next module in the chain. Use entry when you need to track access requests in BRM, but use another database for authentication. No response is sent back to the NAS, so that the mod_pin module behaves as a support or non-terminating module. When the pass-through value is selected, mod_proxy must be the next module in the chain.
Use the dest entry to specify a single destination to which requests should be forwarded. The server details are retrieved from the type-specific configuration.
dest=server1
These sample code show how to forward Access-Request and Accounting-Stop packets.
# mod_proxy configuration to proxy Access-Request packets to server1
$CONFIG {
mod_proxy {
server {
name = server1
addr = zap
port = 1814
secret = testing123
timeout = 10
}
server {
name = server2
addr = zap
port = 1815
secret = testing123
timeout = 10
}
server {
name = server3
addr = zap
authport = 1814
acctport = 1815
secret = testing123
timeout = 10
}
}
}
$MODULES {
# mod_proxy configuration to proxy Access packets to server1
proxy-auth {
check {
Pseudo-Request-Type = Access-Request
}
dest=server1
send {
Class = "proxy"
}
}
# mod_proxy configuration to proxy Accounting-Stop packets to server2
proxy-acct {
check {
Pseudo-Request-Type = Accounting-Request
}
dest=server2
check {
Acct-Status-Type=Stop
}
}
# mod_proxy configuration to proxy Access and Accounting packets to server3
proxy-host {
dest=server3
}
}
The mod_null module allows selected requests to receive an ACK or NAK reply. This module accepts Access-Request and Accounting-Request packets but ignores the requests. It is useful as the last module in the module chain, or to put the RADIUS server in the promiscuous mode. Promiscuous mode is an emergency alternative which ACKs all requests when the database is down.
Note:
The last module in the chain must be mod_null, otherwise incoming authentication or accounting requests would be NAK or ACK respectively, before special processing of the packets.No global configuration settings are supported for the mod_null module. You configure each module instance of the mod_null module in the $MODULES section of the RADIUS configuration file (BRM_home/apps/radius/config). The mandatory type entry is mod_null.
The check and send requests specify how RADIUS requests are processed. See "How RADIUS Requests Are Processed Using check and send Requests".
check {
attribute = value ...
...
}
send {
attribute = value ...
...
}
Use the action block to define the list of possible actions to take for matching requests:
ack: Creates an Access-Accept or Accounting-Response packet for sending to the client, including any send attributes. Unrecognized request types are discarded. Valid for Access-Request and Accounting-Request only.
nak: Creates an Access-Reject or Accounting-Response packet for sending to the client, including any send attributes.
Note:
Since all accounting responses are processed, the action of NAK for accounting requests is equivalent to specifying ACK. This behavior simplifies the configuration of support module entries. Unrecognized request types are discarded.discard: Discards a request and takes no other action. Use this option to prevent a request from being processed by another module. This entry is valid for any request type.
ignore: Ignores a request and takes no action. This entry is valid for any request type.
type=mod_logging
check {
attribute = value ...
...
}
send {
attribute = value ...
...
}
action {
ack | nak | discard | ignore
}
The example below show how to NAK all Framed-User authentication requests and drop Accounting-Start requests:
# mod_null configuration to NAK all Framed-User authentication requests
disable_framed {
type=mod_null
action=nak
check {
Pseudo-Request-Type = Access-Request
User-Service = Framed-User
}
send {
Reply-Message = "All Framed-User logins temporarily disabled"
}
}
# mod_null configuration to drop Accounting-Start requests
drop_acct_start {
action=ack
check {
Pseudo-Request-Type = Accounting-Request
Acct-Status-Type=Start
}
}