Guest

Cisco Prime Access Registrar

Cisco Prime Access Registrar Customization Techniques

  • Viewing Options

  • PDF (1.2 MB)
  • Feedback

Cisco Prime Access Registrar is a feature-rich, RADIUS and Diameter-compliant authentication, authorization, and accounting (AAA) server. Cisco Prime Access Registrar is also a highly customizable application that offers flexibility and extensibility for service providers to meet access needs not already built into the product. This white paper discusses these customizable capabilities, which allow providers to meet unique business, regulatory, and technical requirements. These capabilities include:

A flow-through configuration interface that enables service providers to automate configurations and integrate with the operations support system (OSS)

Extension point scripting (EPS) that allows Cisco Prime Access Registrar users to interact with request processing and communicate with Cisco Prime Access Registrar at numerous extension points to develop and deploy custom logic for user authentication, authorization, and accounting

Support for writing custom AAA services when the built-in services such as Lightweight Directory Access Protocol (LDAP), Open Database Connectivity (ODBC), local, and proxy AAA services do not meet service provider needs

This paper discusses each of these customization techniques in detail, including a description of key concepts and examples showing how to use the feature. For additional detailed information about Cisco Prime Access Registrar, refer to the documentation links at http://www.cisco.com/go/car.

A major challenge that all service providers face is to develop and maintain an AAA infrastructure that can efficiently serve an increasingly diverse mix of access services, users, and partners. AAA systems have to be able to keep up with changes in services being sold, users subscribing to those services, and access servers managing the connections for new technologies.

Adding to this complexity is the changing nature of who is providing services because of ongoing consolidations and mergers, emerging broker services, and shifting wholesale/retail relationships that result in multivendor, heterogeneous AAA environments with increasingly complex business models.

Service providers also have to keep up with the need to integrate with OSS, centralize data stores, and adapt billing systems to keep pace with all the changes.

How Cisco Prime Access Registrar Can Help

Given the rapid rate and scope of change in the service provider AAA environment, successful service providers have had to balance the benefits of developing and maintaining their own proprietary AAA servers with the reality that the AAA world is too complex to be effectively and efficiently managed with in-house resources. To be successful, service providers need to keep their resources focused on their core business rather than AAA server development.

Cisco, a leader in providing networking solutions for service providers, fully understands these issues. Cisco Prime Access Registrar is the Cisco® AAA solution for service providers. Cisco Prime Access Registrar is designed as a comprehensive, out-of-the-box, standards-based, AAA system. It also can be customized to meet special AAA needs. Cisco Prime Access Registrar users get the best of both worlds - support for most Remote Authentication Dial-In User Service (RADIUS) and Diameter server needs, and customization capability for the rest.

Figure 1 shows the standard features of Cisco Prime Access Registrar as well as its customization support.

Figure 1. Cisco Prime Access Registrar Features

The figure shows the configuration interface that service providers can use to customize OSS functions by using automated scripts and OSS integration. Service providers also can launch extension point scripts during request/response cycles to change the results of the program flow. Finally, service providers can create their own custom services to replace or add to the built-in services such as LDAP and ODBC.

These three customization features provide the scalability (by allowing support for frequent and numerous configuration changes), power (by supporting the ability to manipulate each request), and functionality (by allowing support for new technologies) that service providers require without sacrificing flexibility and simplicity.

Automating Configurations

The aregcmd utility is a configuration tool that allows users to set Cisco Prime Access Registrar configurable options in either interactive or noninteractive modes. This section focuses on the noninteractive mode. From the noninteractive mode, administrators and external programs (as well as an OSS) can run a single command or multiple commands from a file.

By using individual aregcmd commands or by creating batches of aregcmd commands, service providers can customize their AAA server environment. Using individual aregcmd commands allows service provider support personnel to make configuration changes quickly. The benefit of using batch files of aregcmd commands is that service providers can simplify the repetitive configuration tasks by creating a file to do these tasks, and then reuse the file as often as necessary. The time-consuming tasks of creating new users, creating new RADIUS clients, or resetting passwords, for example, can be managed by creating configuration files and storing them for future use.

Batch files are also useful for creating AAA scenarios and testing them prior to deployment. Finally, single commands and batch files simplify the central configuration tasks of integrating OSS with multiple Cisco Prime Access Registrar servers. For more information on using aregcmd commands, see the “Using the aregcmd Commands” chapter of the Cisco Prime Access Registrar User Guide.

Example

This section illustrates the use of individual aregcmd commands, as well as batches of conguration commands in a le that is launched using the aregcmd –f <lename> command. The following example uses the aregcmd –f command to add the user Bob to the cisco.com userlist with the password car60ispower by placing the following into a file named newuser:

cd /radius/userlists/cisco.com
add bob
cd bob
set password car60ispower

Entering at the command prompt:

aregcmd –f newuser
[ //localhost/Radius/UserLists/cisco.com/bob ]
Name = bob
Description =
Password = <encrypted>
AllowNullPassword = FALSE
Enabled = TRUE
Group~ =
BaseProfile~ =
AuthenticationScript~ =
AuthorizationScript~ =
UserDefined1 =

Alternately, you can add the user Bob by entering into a le:

add /Radius/Userlists/cisco.com/bob "" car60ispower

Notice that the double quotes ("") represent an empty description.

An example of OSS executing the configuration change directly by running aregcmd follows:

aregcmd add /Radius/Userlists/cisco.com/bob "" car60ispower

Other examples of using aregcmd directly or in batch les to update congurations follow:

To reset a user password using the aregcmd command directly:

aregcmd set /Radius/Userlists/cisco.com/bob/password mynewpassword

To reset numerous user passwords, place the usernames and new passwords in a le and process the le using the aregcmd –f <lename> command. For example, to reset the user passwords for Bob, Sergio, and Pam, at Cisco, enter the following into a le named newpass:

set /Radius/Userlists/cisco.com/bob/password mynewpassword
set /Radius/Userlists/cisco.com/sergio/password mynewpassword
set /Radius/Userlists/cisco.com/pam/password mynewpassword

To execute the batch le, enter:

aregcmd -f newpass

To add a RADIUS client using the aregcmd command directly:

aregcmd add /Radius/Clients/TokyoNAS01 "main Tokyo NAS" 10.0.0.1 mysharedsecret

To add numerous new RADIUS clients, place the client name information in a le and process the le using the aregcmd –f <lename> command. For example, to add new RADIUS clients for Tokyo, London, and Paris, enter the following into a le named newradius:

add /Radius/Clients/TokyoNAS01 "main Tokyo NAS" 10.0.0.1 mysharedsecret
add /Radius/Clients/LondonNAS01 "main London NAS" 172.0.0.10 mysharedsecret
add /Radius/Clients/ParisNAS01 "main Paris NAS" 192.1.0.1 mysharedsecret

To execute the batch le, enter:

aregcmd -f newradius

For more information about batchable configuration files, refer to the samples included with your Access Registrar installation. These files are located at:

<CAR DIR>/examples/cli

Extension Point Scripting

To process RADIUS requests, service providers have to apply complex business rules that go beyond simply checking the user Domain Name System (DNS) domain, dialed number, or calling number. Occasionally, numerous values must be checked or a special parsing of the username is required. Service providers face a challenge in meeting this need: they have to be able to access the request, make the necessary changes, and allow the request-response cycle to complete - in real time.

Cisco Prime Access Registrar solves this problem with EPS, which allows service providers to examine, change, or delete attributes in the packet or change the packet flow. For example, service providers can identify and modify username sufxes or prexes as necessary. Usernames can be analyzed for illegal characters and reformatted.

In addition to being able to access attributes in the request and response, service providers can use EPS to communicate with Cisco Prime Access Registrar at predened extension points during packet processing by accessing the Cisco Prime Access Registrar environment variables.

Packet Flow

When Cisco Prime Access Registrar receives a request from a network access server (NAS), for example, it processes the request in the following manner:

1. Client validation: Cisco Prime Access Registrar server checks/Radius/Clients to see if the client IP address is listed.

2. Rules engine: Cisco Prime Access Registrar invokes the Rules/Policy engine if it is congured.

3. AAA: Cisco Prime Access Registrar performs the congured AAA service (which is an authentication, authorization, query, or accounting service).

4. Session management: Cisco Prime Access Registrar performs session management if it is configured.

5. Response: Cisco Prime Access Registrar creates the response (Access-Accept, for example), and sends it back to the client.

For more detailed information on how Cisco Prime Access Registrar processes, refer to the user documentation at http://www.cisco.com/c/en/us/support/cloud-systems-management/prime-access-registrar/products-user-guide-list.html.

Extension Points in Cisco Prime Access Registrar

At specic points during a Cisco Prime Access Registrar Request-Response packet ow, service providers can initiate scripts using REX (C/C++), Java, TCL, or internal script interfaces, to customize or modify the packet ow. When script nishes, the packet ow continues with the next step.

Note the following:

Internal script interface is an inbuilt, out-of-the-box, scripting option available from Cisco Prime Access Registrar Version 6.1 onward. For more information about internal scripts, see the “Using Extension Points” chapter of the Cisco Prime Access Registrar User Guide.

All the scripting points can be used for processing packets of type RADIUS, Diameter, or TACACS+.

The packet type - RADIUS, Diameter, or TACACS+ - can be obtained from the ‘Request-Type’ or ‘Response-Type’ attribute of the environment dictionary. For more details, refer to the “Environment Dictionaries” chapter of the Cisco Prime Access Registrar User Guide.

These scripting points are given in Table 1. You can find the scripting point information in the file/cisco-ar/examples/rexscript/rex.h.

Table 1. Scripting Point Details

Service

Scripting Point Number

Scripting Point

Description

-

1

Server incoming

Command-line interface (CLI) configuration path: /Radius/IncomingScript

Script runs for every request packet.

Sample use case: To inspect each packet and determine the kind of service (authentication, authorization, or accounting) to be provided.

Remote Server incoming

CLI configuration path: /Radius/RemoteServers/<remote server name>

Script runs when a packet is received from a remote server.

Sample use case: To add/modify/delete attributes coming from the remote server response.

-

2

Vendor incoming

CLI configuration path: /Radius/Vendors/<vendorname>/
IncomingScript

Script runs only for requests from all the clients mapped to a particular vendor.

Sample use case: To translate vendor proprietary attributes to RADIUS/Diameter vendor-specific attributes.

-

3

Client incoming

CLI configuration path: /Radius/Clients/<clientname>/IncomingScript

Script runs only for requests from the specied client (router, NAS, and so on).

Sample use case: To choose AAA service based on an NAS IP address.

4

Provider incoming

Reserved for internal/future use.

-

5

Service incoming CLI configuration path: /Radius/Services/<servicename>/IncomingScript

Script runs when a service is called.

Sample use case: To add/modify/delete attributes before calling a particular service.

Local

6

User group authentication
CLI configuration path: /Radius/UserGroups/<name>/AuthenticationScript

Script runs for authentication requests for a user belonging to a particular user group.

7

User record authentication
CLI configuration path: /Radius/UserLists/<Userlistname>/<username>/AuthenticationScript

Script runs for authentication requests for a particular user.

8

User group authorization
CLI configuration path: /Radius/UserGroups/<name>/AuthorizationScript

Script runs for authorization requests for a user belonging to a particular user group.

9

User record authorization
CLI configuration path: /Radius/UserLists/<Userlistname>/<username>/AuthorizationScript

Script runs for authorization requests for a particular user.

-

10

Service outgoing
CLI configuration path: /Radius/Services/<servicename>/OutgoingScript

Script runs after a service is executed.

Sample use case: To add/modify/delete attributes before sending the response.

11

Provider outgoing

Reserved for internal/future use.

-

12

Client outgoing
CLI configuration path: /Radius/Clients/<clientname>/OutgoingScript

Script runs when sending a response against the request received from a specific client (router, NAS, and so on.)

Sample use case: To add/modify/delete attributes before sending a response to the particular client.

-

13

Vendor outgoing
CLI configuration path: /Radius/Vendors/<vendorname>/OutgoingScript

Script runs when sending a response against the requests received from all the clients mapped to a particular vendor.

Sample use case: To translate RADIUS/Diameter vendor-specific attributes to the appropriate vendor proprietary attributes.

-

14

Server outgoing
CLI configuration path: /Radius/OutgoingScript

Script runs for every response packet.

Sample use case: To add/modify/delete attributes before sending the response.

Remote Server outgoing

CLI configuration path: /Radius/RemoteServers/<remote server name>

Script runs when a packet is sent out to a remote server.

Sample use case: To add/modify/delete attributes in a packet going to a remote server.

Remote

15

Remote service outage

Reserved for internal/future use.

Remote

16

Remote server outage
CLI configuration path: /Radius/Services/<service name>

Script runs when the remote server is down. Sample use case: To add/modify/delete attributes when the remote servers defined in the service are down.

-

17

Add session

Reserved for internal/future use.

-

18

Delete session

Reserved for internal/future use.

Session Manager

19

Session manager incoming
CLI configuration path: /Radius/SessionManagers/<session manager name>

Script runs to direct requests to be processed by a specific session manager after authentication and authorization.

Sample use case: To add attributes to the cache for a user before the session manager is called.

Session Manager

20

Session manager outgoing
CLI configuration path: /Radius/SessionManagers/<session manager name>

Script runs to direct responses from a specific session manager after authentication and authorization.

Sample use case: To translate the session cache attribute before sending the response.

-

21

Virtual server outgoing

Script set any time during packet run time and runs after Server Outgoing scripting point. Can be triggered from any other scripting point by setting the environment variable Virtual-Server-Outgoing-Script.

To learn more about environment variables, see the “Environment Dictionaries” chapter of the Cisco Prime Access Registrar User Guide.

This scripting point is applicable only for RADIUS packets.

SIGTRAN/M3UA

22

Global title translation
CLI configuration path: /Radius/RemoteServers/<remote server name>

Script runs before sending out request to Home Registration Register (HLR) to perform Global Title Translation (GTT).

Sample use case: To define GTT based on incoming International Mobile Subscriber Identity (IMSI) ranges.

EAP-AKA

23

Quintet generation
CLI configuration path: /Radius/Services/<EAP-AKA service name>

Script runs to generate quintets by using a simulator for Extensible Authentication Protocol (EAP)-Authentication and Key Agreement (AKA) service.

Sample use case: To fetch quintet information from a configured file based on the incoming IMSI.

Translation

24

IMSI translation
CLI configuration path: /Radius/RemoteServers/<remote server name>

Script runs to change the incoming IMSI.

Sample use case: To modify the incoming IMSI ranges before sending a request to a Signal Transfer Point (STP)/HLR.

FastRules

25

FastRule

Script is configured within a fast rule execution path.

Sample use case: To add an attribute in the same flow after authentication and authorization of a packet.

Request Translation

26

Prerequest translation
CLI configuration path: /Radius/Services/<service name>

To add/modify/delete incoming RADIUS/Diameter attribute values in the request before translation.

27

Postrequest translation
CLI configuration path: /Radius/Services/<service name>

To add/modify/delete translated Diameter/RADIUS attributes in the request after translation.

Response Translation

28

Preresponse translation
CLI configuration path: /Radius/Services/<service name>

To add/modify/delete Diameter/RADIUS attribute values in the response before translation.

29

Postresponse translation
CLI configuration path: /Radius/Services/<service name>

To add/modify/delete RADIUS/Diameter attributes in the response after translation.

The scripting point number is passed on to a REX script as the first argument. See the signature of ExecRealmRule script below for an example.

int REXAPI ExecRealmRule (int iScriptingPoint,
rex_AttributeDictionary_t * pRequest,
rex_AttributeDictionary_t * pResponse,
rex_EnvironmentDictionary_t * pEnviron )

An example for Java API is given below:

public int runExtension (int iExtensionPoint,
AttributeDictionary request,
AttributeDictionary response,
EnvironmentDictionary environment)

Note the following:

The scripting point number is not passed while using TCL.

Customer can choose to use this information to write code that behaves differently for different scripting points, or choose to ignore it. Refer to the “Cisco Prime Access Registrar Tcl, REX and Java Dictionaries” chapter of the Cisco Prime Access Registrar User Guide for complete API documentation.

All the above scripting points can be used with REX (C/C++), Java, and TCL on RADIUS, Diameter, or TACACS+ packets.

Following is a sample REX script snippet for Diameter:

// Setting SWx Application Id in Diameter packet Header and in AVP in Rex Service
pEnviron->put (pEnviron, "Diameter-Application-Id", "16777265" );
pRequest->put (pRequest,"Vendor-Specific-Application-Id",
"<Vendor-Specific-Application-Id>Vendor-Id=10415;Auth-Application-Id=16777265;</Vendor-Specific-Application-Id>",0 );

EPS allows request targeting. For example, a script applied at the server incoming extension point is invoked for all requests arriving at Cisco Prime Access Registrar, whereas a script applied at the client incoming extension point is invoked only for requests from the specified client. The outgoing scripting points work in the same fashion.

The packet flow is the same for all incoming packets, but the extension points invoked depend on the request type and service used. For example, an access request using the local Cisco Prime Access Registrar authentication/authorization service is illustrated in Figure 2.

Figure 2. Local Authentication/Authorization Packet Flow

Figure 3 shows the packet flow for remote authentication/authorization.

Figure 3. Remote Authentication/Authorization Packet Flow

Figure 4 Shows the Packet Flow for Diameter 3GPP.

Figure 4. Diameter 3GPP Packet Flow

Figure 5 shows the packet flow for RADIUS 3GPP.

Figure 5. RADIUS 3GPP Packet Flow

Figure 6 shows the packet flow for the SIGTRAN interface.

Figure 6. SIGTRAN Packet Flow

Using the Application Program Interface

EPS allows you to manipulate the request and response attributes using the Cisco Prime Access Registrar application programming interface (API) functions. This is useful for changing information contained in the request or the response. Manipulating environment variables also allows EPS to communicate with Cisco Prime Access Registrar as well as with other scripts. These values are grouped into: request attributes (which deal with requests), response attributes (which deal with responses), and environment variables. Examples of environment variables are discussed in the next section.

Cisco Prime Access Registrar supports many variables that scripts use to communicate with - or change the behavior of - the Cisco Prime Access Registrar server, or to communicate with other scripts. For example, if the “Accounting-Service” environment variable is set, the server directs the request to the specied accounting service for processing. Likewise, you can set the “Authentication-Service” and “Authorization-Service” environment variables to direct requests to the appropriate authentication/authorization service.

Other examples of environment variables follow:

You can set the “Ignore-Accounting-Signature” environment variable to tell the server not to verify the accounting request signature. This is done to work around those RADIUS implementations that do not sign accounting requests.

Cisco Prime Access Registrar sets the “Request-Type” environment variable and the script reads it to determine the type of request arriving (for example, access request or accounting request).

You can set the “Response-Type” environment variable to the type of response (for example, Access-Reject).

An extension point script can use the “Trace-Level” environment variable to set the debugging trace level.

For a complete listing of the environment variables and a full description of their usage, refer to the “Environment Dictionary” chapter of the Cisco Prime Access Registrar User Guide.

Extension Point Scripting Examples

The EPS examples shown here are written in Toolkit Command Language (TCL) for the purpose of clarity. All examples can be written in C/C++ or Java as per the available APIs.

Example 1

The following request attribute example adds the attribute Service-Type to a request with its value set to Outbound:
$request put Service-Type Outbound
Example 2

This response attribute example removes the State attribute from the Cisco Prime Access Registrar response (some noncompliant RADIUS clients behave unpredictably when they receive this attribute):

$response remove State

Example 3

The following environment variable example illustrates communicating with Cisco Prime Access Registrar to set AAA services:

$environ put Authentication-Service auth-service
$environ put Authorization-Service auth-service
$environ put Accounting-Service acc-service

Example 4

The following environment variable example returns the type of request received by Cisco Prime Access Registrar; for example, Access-Request:

$environ get Request-Type

Example 5

The following example illustrates how an extension point script looks at the DNS domain in the username and sets the AAA services. It also overrides the username in the request by setting the User-Name environment variable. The script can be run from the server incoming extension point so that it runs for every request that Cisco Prime Access Registrar processes.

proc RealmServiceSelection {request response environ} {set userName [ $request get User-Name ]if { [ regexp {([^@]+)@([^@]+)}

$userName dummy newUserName realm]}{
$environ put User-Name $newUserName$environ put Authentication-Service $realm$environ put Authorization-Service $realm$environ put Accounting-Service $realm
}
}

Example 6

The following example shows how an extension point script diverts accounting requests to a file. To find all the accounting requests, the script must process every request. Hence, the script runs from the server incoming extension point. The script identifies accounting requests by examining the Request-Type environment variable. All accounting requests with the attribute Acct-Status-Type set to Accounting-On or Accounting-Off are then written to the local file accounting service named SysAcc-file.

proc divert-AccOnOff { request response environ } {set request-type
[$environ get Request-Type]if { [string equal ${request-type}
"Accounting-Request"]}{set AST [ $request get Acct-Status-Type ]if {
( [string equal $AST "Accounting-On"] ||[string equal $AST
"Accounting-Off"]) } {$environ put Accounting-Service SysAcc-file}}}

Example 7

This example script checks the Request-Type environment variable. If the packet is an accounting request packet, the script sets the Ignore-Accounting-Signature environment variable to TRUE. This script is useful in situations where a service provider has NASs that do not sign the accounting requests properly. This script allows the service provider to tell Cisco Prime Access Registrar to ignore the accounting signature.

Because these NASs can be grouped under a vendor, this script can be run from the vendor incoming extension point.

proc ig-acc-sig { request response environ } {set request-type [ $environ get Request-Type ]if { [string equal
${request-type} "Accounting-Request"] } {
$environ put Ignore-Accounting-Signature TRUE
}
}

Translating RADIUS and Diameter Requests/Responses

Cisco Prime Access Registrar supports translation of incoming RADIUS requests and responses to Diameter and vice versa. There are two types of services:

RADIUS to Diameter translation service - To translate incoming RADIUS request to Diameter equivalent and then the Diameter response to RADIUS equivalent.

Diameter to RADIUS translation service - To translate incoming Diameter request to RADIUS equivalent and then the RADIUS response to Diameter equivalent,

For both the translation services, the following scripting points are used:

PreRequestTranslationScript

PostRequestTranslationScript

PreResponseTranslationScript

PostResponseTranslationScript

For details about these scripting points, see Table 1 - Scripting Point Details.

Following is the CLI for RADIUS to Diameter translation:

[ /Radius/Services/rad-dia ]
Name = rad-dia
Description =
Type = radius-diameter
DiameterApplicationId = 1
ProxyServiceName = dia-proxy
EnableCommandMappings = True
PreRequestTranslationScript~ =
PostRequestTranslationScript~ =
PreResponseTranslationScript~ =
PostResponseTranslationScript~ =
RequestMapping/
CommandMappings/
Radius-Access-Request = AA
AVPMappings/
NAS-Identifier = Origin-Host
NAS-Port = Session-Id
User-Name = User-Name
AVPsToBeAdded/
Origin-Realm = cisco.com
EnvironmentMappings/
ResponseMapping/
ResultCodeMappings/
Diameter-Success = Radius-Access-Accept
Diameter-Unable-To-Deliver = Radius-Access-Reject
AVPMappings/
AVPsToBeAdded/
EnvironmentMappings/

Following is the CLI for Diameter to RADIUS translation:

[ /Radius/Services/dia-rad ]
Name = dia-rad
Description =
Type = diameter-radius
ProxyServiceName = rad-proxy
PreRequestTranslationScript~ =
PostRequestTranslationScript~ = dia-rad-addpassword
PreResponseTranslationScript~ =
PostResponseTranslationScript~ = diareadwritetest
RequestMapping/
CommandMappings/
AA = Radius-Access-Request
AVPMappings/
Origin-Host = NAS-Identifier
User-Name = User-Name
AVPsToBeAdded/
NAS-Port = 1
EnvironmentMappings/
ResponseMapping/
ResultCodeMappings/
Radius-Access-Accept = Diameter-Success
Radius-Access-Reject = Diameter-Unable-To-Deliver
AVPMappings/
AVPsToBeAdded/
EnvironmentMappings/

Controlling Debugging

In service provider environments with large volumes of production traffic, it is not feasible to turn on debugging (tracing) for long periods of time because debugging is resource intensive. Specifically, in attempting to analyze data, debugging overhead slows request processing and uses large amounts of disk space. EPS offers an easy and elegant way to turn debugging on and off selectively.

In the following example, EPS turns debugging on only for requests with username bob@cisco.com. The environment variable Trace-Level sets the trace level, and Retrace-Packet makes Cisco Prime Access Registrar display the full contents of the request received. This script could be set at the server incoming extension point.

proc debug { request response environ } {set user [ $request get User-Name ]if { [ string equal $user "bob@cisco.com"]}{
$environ put Trace-Level 5$environ put Retrace-Packet TRUE}}

The following example illustrates how to use EPS to validate a response from a RADIUS server. In this example, the remote RADIUS server is not in your administrative control, so you need to validate its responses. Here, the script looks in the response for the Framed-IP-Address attribute value of 255.255.255.255. If the script finds this value, it removes the attribute.

To target a specific RADIUS server, use the remote server incoming extension point to target the response from that server:

proc remove-bad-IP {request response environ} {if { [ $request containsKey Framed-IP-Address ] &&[ string equal [ $request get Framed-IP-Address ]"255.255.255.255"]}{
$request remove Framed-IP-Address
}
}

To configure this example, create a file containing the TCL code. Name the file remove-bad-IP.tcl. Then, in aregcmd enter:

cd /Radius/Scripts
add remove-bad-IP
cd remove-bad-IP
set Language tcl
set Filename <yourscripts dir>/remove-bad-IP.tcl

cd /Radius/RemoteServers
cd myRemoteServer
set IncomingScript remove-bad-IP

save
reload

For more information on EPS scripting examples, refer to the samples that are part of your Cisco Prime Access Registrar installation at:
For EPS examples in C:

/cisco-ar/examples/rexscript/rexscript.c

For EPS examples in TCL:

/cisco-ar/scripts/radius/tcl/tclscript.tcl

In cases where you need a service not provided directly by Cisco Prime Access Registrar (such as those shown in Figure 1), you can create your own C++ custom service using the Cisco Prime Access Registrar API functions. (These are the same API functions used in EPS discussed in the previous section.)

Custom services packet flow is shown in Figure 7.

Figure 7. Custom Services Packet Flow

Also, refer to the rex.h file found at <Prime Access Registrar DIR>/examples/rexservice/ for more information on service points.

Figure 7 displays a custom authentication/authorization service that uses an external plug-in library written in C++/Java. The core authentication/authorization custom logic is implemented within this custom library. For instance, you can write a plug-in to interact with a POP3 server and perform the authentication/authorization based on the interaction.

Custom services can control the packet flow within Cisco Prime Access Registrar. In the case of REX, a custom service can return REX_PENDING. This return value indicates that the service is taking over responsibility for the request and later will call the reschedule () function to let the server know when the service is done with the request, and the server can resume processing. This allows the service to pass the request to a different thread for background processing, freeing the current thread. This feature is useful and is recommended to implement a custom service that requires to access another process or server to return an answer.

This section describes some examples of custom services. For more information on custom service examples, refer to the sample that is included as part of your Cisco Prime Access Registrar installation. The sample is located at:

/cisco-ar/examples/rexservice/rexservice.cpp

In these examples, REX refers to the Cisco RADIUS Extension.

A Basic Custom Service

The following example illustrates the framework for a minimal access request service named BlindAA. Note that this illustrates the power of extensibility/customization by creating a completely new authentication service in addition to those already present in Cisco Prime Access Registrar. This can also be used to create custom authentication services such as POP3 authentication, web service-based authentication, and open ID authentication.

int REXAPI BlindAA (int iServicePoint,rex_AttributeDictionary_t * pRequest,rex_AttributeDictionary_t * pResponse, rex_EnvironmentDictionary_t * pEnviron )
{
int iResult = REX_OK;
switch (iServicePoint)
{
case REX_START_SERVICE:
break;
case REX_STOP_SERVICE:
break;
case REX_AUTHENTICATION_SERVICE:
break;
case REX_AUTHORIZATION_SERVICE:
break;
case REX_AUTHENTICATION_AND_AUTHORIZATION_SERVICE:
pEnviron->put (pEnviron, "Response-Type","Access-Accept" );break;
default:pRequest->log (pRequest, REX_LOG_ERROR,
"Unsupported Service Point" );
iResult = REX_ERROR;
break;
}
return iResult;
}

This service looks for authentication and authorization requests. It is not an accounting service. This service, BlindAA, checks the service point from which it is being called. If the service detects that Cisco Prime Access Registrar is starting or stopping, it does nothing. If it detects that it is being run as an authentication/authorization service, it sets the Response-Type environment variable to Access-Accept (that is, it accepts the request). If the service detects that it is being run as anything else (for example, an accounting service), it creates the error message “Unsupported Service Point.”

To use BlindAA: Compile the completed program. (Use the compiler recommended for your version of Cisco Prime Access Registrar. For example, use gcc-2.95.3 for Cisco Prime Access Registrar 3.0.) For the header file and the make file, refer to <Cisco Access
Registrar DIR>/examples/rexservice.
In aregcmd, enter:

cd /Radius/Services
add BlindAA
cd BlindAA
set Type rex
set Filename <location/filename of shared object file>
set EntryPoint BlindAA

Now you can use this service like one of the provided services in Cisco Prime Access Registrar by entering:

cd /Radius
set DefaultAuthenticationService BlindAA
set DefaultAuthorizationService BlindAA
save
reload

The following example shows a custom accounting service named RexAccountingService.

int REXAPI RexAccountingService (int iServicePoint,rex_AttributeDictionary_t * pRequest,rex_AttributeDictionary_t * pResponse, rex_EnvironmentDictionary_t * pEnviron )
{
if( iServicePoint == REX_START_SERVICE )
{
//open connection to datastore
int iResult = openDatastoreConnection() ;
}
else if( iServicePoint == REX_STOP_SERVICE )
// close connection to datastore
iResult = closeDatastoreConnection() ;
else if( iServicePoint == REX_ACCOUNTING_SERVICE ){
// send accounting attributes to datastore
iResult = sendToDatastore( pRequest ) ;
}
else
{
pRequest->log( pRequest, REX_LOG_ERROR, "Unsupported Service Point" );
iResult = REX_ERROR;
}
return iResult;
}

In this example of the accounting service RexAccountingService, the service checks the service point from which it is being launched. If it detects that Cisco Prime Access Registrar is starting, it opens a connection to the data store. If it detects that Cisco Prime Access Registrar is stopping, it closes any open connections. This ensures that any actions that require writing data have a connection to the data store when needed and connections are closed gracefully when Cisco Prime Access Registrar is shutting down.

If the service detects an accounting request (that is, the service is being launched by the accounting service point), it writes the accounting attributes to the data store. If the service detects that it is being run as anything else, it creates the error message “Unsupported Service Point.”

The following example uses the same accounting service as in the previous example, but uses the REX_PENDING/reschedule facilities.

int REXAPI RexAccountingService (int iServicePoint,rex_AttributeDictionary_t * pRequest,rex_AttributeDictionary_t * pResponse, rex_EnvironmentDictionary_t * pEnviron )
{
int iResult = REX_OK;
if( iServicePoint == REX_START_SERVICE )
{
// open connection to datastore
If (iResult = openDatastoreConnection() )
{
// start thread that sends accounting attributes to datastore
iResult = startDatastoreProcessingThread() ;
}
}
else if (iServicePoint == REX_STOP_SERVICE )
{
// stop datastore thread
stopDatastoreProcessingThread() ;
// close connection to datastore
closeDatastoreConnection() ;
}
else if (iServicePoint == REX_ACCOUNTING_SERVICE )
{
// send accounting attributes to datastore processing thread
// Datastore processing thread will return REX_PENDING immediately once it
// has the request. Once the request is processed to the datastore, it will
// call reschedule() for each request it has processed
iResult = sendToDatastoreProcessingThread (pRequest ) ;
}
else
{
pRequest->log (pRequest, REX_LOG_ERROR, "Unsupported Service Point" );
iResult = REX_ERROR;
}
return iResult;
}

In this extension of the example of the accounting service RexAccountingService, the service checks the service point from which it is being launched to determine if the service is being launched by the accounting service point. If it detects that Cisco Prime Access Registrar is starting, it opens a connection and starts a thread to write data to the data store. If the service detects that Cisco Prime Access Registrar is stopping, it stops any threads and closes any open connections. This ensures that connections and threads are properly managed.

If the service detects an accounting request, it sends the accounting attributes to the processing thread. Upon receipt of the request, the data store processing thread returns REX_PENDING to let the server know that the service has taken responsibility for the request. As soon as the request is processed to the data store, the thread calls the reschedule () function to let the server know that the service is done with the request and that the server can resume processing the request.

If the service detects that it is being run as anything else, it creates the error message “Unsupported Service Point.”

Conclusion

Service providers today compete in a complicated and fast-paced environment of constant change. AAA services are critical in this dynamic and demanding environment, and service providers need an AAA solution that is scalable, powerful, and flexible.

Cisco Prime Access Registrar is designed to meet these needs by providing a feature-rich, off-the-shelf AAA server. Just as importantly, Cisco Prime Access Registrar also includes special interfaces that allow service providers to automate and centralize AAA configuration, provide control and customization over the processing of each request, and allow for the customization of the AAA function itself.

These special interfaces provide the scalability (by allowing support for frequent and numerous configuration changes), the power (by supporting the ability to manipulate each request), and the flexibility (by allowing support for new technologies) that service providers require to be able to meet AAA demands.