# openam-auth-radius

*Open AM's Radius Feature-set Library*

The code in this repo implements three distinct features that share code for speaking the RADIUS protocol. First,

it holds a RADIUS authentication module enabling Open AM to act as a RADIUS client and delegate authentication to a remote

RADIUS server. Second, it also holds a RADIUS server backed by Open AM's authentication chains and modules allowing other RADIUS

clients to delegate authentication to Open AM. And third, it contains a RADIUS command line client called the ConsoleClient

that allows for testing of a RADIUS authentication against a RADIUS server like Open AM. The jar that is generated by

this module is executable and launches the ConsoleClient as is shown below.

Concerning incoming RADIUS requests leveraging authentication modules, some authentication modules clearly can not be

used by RADIUS clients. Traditionally, authentication modules have dealt only with Http based client. But RADIUS

represents a new and distinctly different type of client. For example, there is no mechanism in RADIUS for persisting content between

sessions such as can be done with cookies on Http clients. Any module that depends on use of an HttpServletRequest or

HttpServletResponse object without verifying that they actually have those objects will result in exceptions being

thrown and all authentication attempts via that module to be rejected.

With careful crafting most modules should be able to adjust their feature set to support RADIUS clients

in addition to Http clients albeit potentially with a smaller feature set for the former. This can be done by providing

different templates and different flows through the module to remove those features that are not applicable or adapt

them to the different interactions available to RADIUS clients.

*Launching the Radius Server Feature*

To use the RADIUS server functionality the following entry in Open AM's web.xml file kicks of loading of the RADIUS

server features:

<listener>

<listener-class>com.sun.identity.authentication.modules.radius.server.config.ServletContextListenerLauncher

</listener-class>

</listener>

There is also support for launching via a SpringFramework component-scan directive in a servlet file if desired. The

above web.xml declaration results in the following RADIUS server log entries appearing in catalina.out assuming a

tomcat deployment. At startup

you'll see these lines appear. Some parts have been snipped out in the content below to make it more clear:

26-Feb-2015 13:22:22.926 INFO [localhost-startStop-1] <snip/> ---> ServletContextListenerLauncher starting RadiusServiceStarter

26-Feb-2015 13:22:22.932 INFO [localhost-startStop-1] <snip/> Loaded OpenAM Authn Radius Module = built 2015-02-26 23:53 UTC

*Enabling the Radius Server*

Upon starting up, the RADIUS server functionality relies upon constructs in OpenAM's admin console for its configuration.

If such are not found they are automatically added so that the server can obtain the default configuration and register

for notification of changes by an administrator making adjustments in the admin console. If that auto-registration is

necessary you will see it taking place in catalina.out with lines like these:

26-Feb-2015 13:29:20.198 INFO [RADIUS-RadiusServiceStarter] <snip/> RadiusServerService not found. Loading...

26-Feb-2015 13:29:20.201 INFO [RADIUS-RadiusServiceStarter] <snip/> Service Descriptor file for RadiusServerService

found at: jar:file:/Users/boydmr/tomcat8/apache-tomcat-8.0.9/webapps/sso/WEB-INF/lib/openam-auth-radius-1.0.1.jar!/RadiusServerService.xml

Immediately following these lines you'll then see the default configuration being loaded including what the current

values are in very concise form. Similar lines to these will appear whenever Open AM starts up. Note that by default

the RADIUS server is disabled.

26-Feb-2015 13:29:22.307 INFO [RADIUS-RadiusServiceStarter] <snip/> Loading RADIUS Config...

26-Feb-2015 13:29:22.361 INFO [RADIUS-RadiusServiceStarter] <snip/> --- Loaded Config ---

[RadiusServiceConfig NO 1812 P( 1, 10, 10, 10)]

26-Feb-2015 13:29:22.362 INFO [RADIUS-RadiusServiceStarter] <snip/> RADIUS service disabled.

This default configuration and the constructs for configuring these values in Open AM's admin console are defined by

the RadiusServerService.xml file located the project source [in the resources directory](src/main/resources). You can

view the RADIUS configuration constructs by going to the __Configuration tab__,

the __Global sub-tab__, and selecting the __RADIUS Server__ entry in the __Global Properties__ table. Once in that page

you can now define RADIUS Clients, set the port on which to listen for requests, and enable the RADIUS server.

Whenever this configuration for the RADIUS server changes you'll immediately see log entries in catalina.out that show

the RADIUS server configuration being reloaded. For example, once radius is enabled the following log entries will

appear indicating that the listener is active and information about the backing thread pool for connections:

26-Feb-2015 13:52:11.338 INFO [RADIUS-RadiusServiceStarter] <snip/> RADIUS Config Changed. Loading...

26-Feb-2015 13:52:11.339 INFO [RADIUS-RadiusServiceStarter] <snip/> --- Loaded Config ---

[RadiusServiceConfig YES 1812 P( 1, 10, 10, 10)]

26-Feb-2015 13:52:11.343 INFO [RADIUS-RadiusServiceStarter] <snip/> RADIUS service enabled. Starting Listener.

26-Feb-2015 13:52:11.355 INFO [RADIUS-1812-Listener] <snip/> RADIUS Listener is Active.

Port : 1812

Threads Core : 1

Threads Max : 10

Thread Keep-alive : 10 sec

Request Queue : 10

Note that when configuration changes the logging includes each client's configuration in a very concise form. If any RADIUS requests are

received before any clients are

configured or if the configured clients don't match the IP

address of the incoming packets the RADIUS server will log the attempt and silently drop to packet as specified in

the RFC like so:

27-Jan-2015 09:45:25.004 WARNING [RADIUS-1812-Listener] <snip/>

No Defined RADIUS Client matches IP address /127.0.0.1. Dropping request.

This log message is very useful in that it specifies the exact value of the client's IP address that must be specified

in the client configuration page for packets from that client to be accepted for authentication. Once this IP address

is specified for a defined client the packets are now accepted and authentication

against modules in the client's specified chain will proceed.

*Testing with ConsoleClient*

To exercise the RADIUS server we can use this module's generated jar file to run the included

__ConsoleClient__ command line tool. It allows a user to authenticate to openAM using the RADIUS protocol by providing

simple prompts on the command line and translating user input to corresponding requests to the server. To run this

tool open a command

shell that has access to java. Now change directory to be in the Open AM's WEB-INF/lib directory or include the full

path to

the

module's jar file, such as openam-auth-radius-1.0.1.jar, in the following command for your current directory:

java -jar <path-to-jar>

When starting up it will print out its build information indicating its version and build date and then look for

a __radius.properties__ file in the current directory. If not found, as shown here, it will prompt the user to add

a __radius.properties__ file in the current directory with the indicated properties shown:

java -jar ~/tomcat8/apache-tomcat-8.0.9/webapps/sso/WEB-INF/lib/openam-auth-radius-1.0.1.jar

Feb 26, 2015 5:09:53 PM <snip/>

INFO: Loaded OpenAM Authn Radius Module = 1.0.1 built 2015-02-26 23:53 UTC

Missing required config file 'radius.properties' in current directory /Users/boydmr/.

Must Contain:

secret=<shared-secret-with-server>

host=<hostname-or-ip-address>

port=<port-on-target-host>

May Contain:

show-traffic=true

The shared secret must match exactly the value specified for the RADIUS Client configured in Open AM for this particular

traffic. More on that in a minute. The host can be either a DNS name or an IP address and must resolve to the

Open AM server or cluster. The port must match the port configured for the RADIUS server in openAM's console. For

example, I'll create a radius.properties file with these values including telling the ConsoleClient to log the RADIUS

traffic:

secret=letmein

host=127.0.0.1

port=1812

show-traffic=true

Once I have the radius.properties file defined the ConsoleClient will now prompt for Username and Password. This must be a

user in OpenAM's backing user store. For my testing where I use embedded OpenDJ I used the admin console and created a

user __boydmr__ in the root realm.

Once username and password are entered the ConsoleClient will connect to the RADIUS server and attempt to authentication

via username and password. As required in [section 3 of RFC 2865](https://tools.ietf.org/html/rfc2865#section-3) for

this communication to be accepted by the RADIUS server the IP address of the incoming

packet __must match an IP address of a defined client or the packet will be dropped silently__.

For example, I have not yet defined any clients in the admin console. So when ConstoleClient attempts to connect it hangs

with this output after I enter my username and password:

java -jar ~/tomcat8/apache-tomcat-8.0.9/webapps/sso/WEB-INF/lib/openam-auth-radius-1.0.1.jar

Feb 26, 2015 2:08:26 PM <snip/>

INFO: Loaded OpenAM Authn Radius Module = 1.0.1 built 2015-02-26 23:53 UTC

? Username: boydmr

? Password: password

Packet To 127.0.0.1:1812

ACCESS_REQUEST [1]

- USER_NAME : boydmr

- USER_PASSWORD : *******

- NAS_IP_ADDRESS : localhost/127.0.0.1

- NAS_PORT : 0

The ConsoleClient hangs at this point and stops responding because it is waiting for a UDP response packet which will

never come. This is clearly seen in the server side logs by the following log entry that results:

26-Feb-2015 17:39:37.254 WARNING [RADIUS-1812-Listener] <snip/>

No Defined RADIUS Client matches IP address /127.0.0.1. Dropping request.

The IP address listed in the log is what must be entered for the client before the server will accept packets from that

client and not drop them. Hence, when configuring new clients it is very useful to first receive traffic from them to

know what value to use when configuring that client.

*Configuring a Radius Server Client*

So I once again access the Radius Server configuration page in Open AM's console. But this time I press the __New__

button in the Secondary Configuration Instance table. This lets me define a client allowed to connect to the Open AM

RADIUS server port. Give the client a descriptive name. It is only used in the configuration page so it can be whatever

helps us remember what remote client this configuration is for. The Client IP Address value must match that value that

we saw in the log file __/127.0.0.1__ in this case. The Client Secret can be whatever you want it to be. A random one is

generated for you and can be shared with the remote client out-of-band. Here, I set it to the same value that we have

in out radius.properties file, __letmein__. I chose to enable traffic logging so that we can see how things look from

the server's viewpoint. The handler class should be left alone but enables alternative

implementations being plugged in. See the comments in the page for the interface to implement for such an attempt.

Finally, we come to Handler Class Configuration Properties. The OpenAMAuthHandler class expects two values:

realm = the name of a realm that contains the authentication chain to be used

chain = the name of the authentication chain to use

I chose to use the root realm and the default authentication chain created with a default Open AM configuration __ldapService__.

realm=/

chain=ldapService

Once I press the __Add__ button I see the log output change indicating that the new configuration has been noticed and

the RADIUS Server's Listener shut down and restarted with the new values.

26-Feb-2015 17:54:14.961 INFO [RADIUS-RadiusServiceStarter] com.sun.identity.authentication.modules.radius.server.config.RadiusServiceStarter.run RADIUS Config Changed. Loading...

26-Feb-2015 17:54:14.961 INFO [RADIUS-RadiusServiceStarter] com.sun.identity.authentication.modules.radius.server.config.RadiusServiceStarter.run --- Loaded Config ---

[RadiusServiceConfig YES 1812 P( 1, 10, 10, 10), C( /127.0.0.1=ConsoleClient test, letmein, true, com.sun.identity.authentication.modules.radius.server.spi.handlers.OpenAMAuthHandler, {realm=/, chain=ldapService})]

the packet is accepted by the server it will then attempt to authenticate the user via

username and password. Hence, the first module in the chain specified for this client must use username and password for

its callbacks.

If other modules are included in the chain then each field required by that module will be

conveyed back to the ConsoleClient and it will prompt for each additional field. Once all have been entered then it will

finish authentication against that module. This continues until the user fails to provide proper values required by

each

module in the chain or successfully authenticates to all modules in the chain.

As requests arrive at the Server log entries are made in catalina.out that can be used to troubleshoot problems with configuration.

If the RADIUS Client is not properly configured in the Server the incoming request will be seen and logged by the server

but will be discarded. For example, suppose that I defined my client

# Questions?

If you have questions send them to Mark Boyd

at boydmr@ldschurch.org.