5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen# openam-auth-radius
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen*Open AM's Radius Feature-set Library*
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenThe code in this repo implements three distinct features that share code for speaking the RADIUS protocol. First,
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenit holds a RADIUS authentication module enabling Open AM to act as a RADIUS client and delegate authentication to a remote
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenRADIUS server. Second, it also holds a RADIUS server backed by Open AM's authentication chains and modules allowing other RADIUS
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenclients to delegate authentication to Open AM. And third, it contains a RADIUS command line client called the ConsoleClient
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenthat allows for testing of a RADIUS authentication against a RADIUS server like Open AM. The jar that is generated by
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenthis module is executable and launches the ConsoleClient as is shown below.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenConcerning incoming RADIUS requests leveraging authentication modules, some authentication modules clearly can not be
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenused by RADIUS clients. Traditionally, authentication modules have dealt only with Http based client. But RADIUS
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenrepresents a new and distinctly different type of client. For example, there is no mechanism in RADIUS for persisting content between
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowensessions such as can be done with cookies on Http clients. Any module that depends on use of an HttpServletRequest or
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenHttpServletResponse object without verifying that they actually have those objects will result in exceptions being
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenthrown and all authentication attempts via that module to be rejected.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenWith careful crafting most modules should be able to adjust their feature set to support RADIUS clients
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenin addition to Http clients albeit potentially with a smaller feature set for the former. This can be done by providing
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowendifferent templates and different flows through the module to remove those features that are not applicable or adapt
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenthem to the different interactions available to RADIUS clients.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen*Launching the Radius Server Feature*
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenTo use the RADIUS server functionality the following entry in Open AM's web.xml file kicks of loading of the RADIUS
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenserver features:
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen <listener-class>com.sun.identity.authentication.modules.radius.server.config.ServletContextListenerLauncher
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen </listener-class>
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenThere is also support for launching via a SpringFramework component-scan directive in a servlet file if desired. The
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenabove web.xml declaration results in the following RADIUS server log entries appearing in catalina.out assuming a
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowentomcat deployment. At startup
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenyou'll see these lines appear. Some parts have been snipped out in the content below to make it more clear:
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 13:22:22.926 INFO [localhost-startStop-1] <snip/> ---> ServletContextListenerLauncher starting RadiusServiceStarter
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 13:22:22.932 INFO [localhost-startStop-1] <snip/> Loaded OpenAM Authn Radius Module = built 2015-02-26 23:53 UTC
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen*Enabling the Radius Server*
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenUpon starting up, the RADIUS server functionality relies upon constructs in OpenAM's admin console for its configuration.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenIf such are not found they are automatically added so that the server can obtain the default configuration and register
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenfor notification of changes by an administrator making adjustments in the admin console. If that auto-registration is
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowennecessary you will see it taking place in catalina.out with lines like these:
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 13:29:20.198 INFO [RADIUS-RadiusServiceStarter] <snip/> RadiusServerService not found. Loading...
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 13:29:20.201 INFO [RADIUS-RadiusServiceStarter] <snip/> Service Descriptor file for RadiusServerService
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 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
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenImmediately following these lines you'll then see the default configuration being loaded including what the current
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenvalues are in very concise form. Similar lines to these will appear whenever Open AM starts up. Note that by default
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenthe RADIUS server is disabled.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 13:29:22.307 INFO [RADIUS-RadiusServiceStarter] <snip/> Loading RADIUS Config...
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 13:29:22.361 INFO [RADIUS-RadiusServiceStarter] <snip/> --- Loaded Config ---
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen [RadiusServiceConfig NO 1812 P( 1, 10, 10, 10)]
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 13:29:22.362 INFO [RADIUS-RadiusServiceStarter] <snip/> RADIUS service disabled.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenThis default configuration and the constructs for configuring these values in Open AM's admin console are defined by
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenthe RadiusServerService.xml file located the project source [in the resources directory](src/main/resources). You can
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenview the RADIUS configuration constructs by going to the __Configuration tab__,
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenthe __Global sub-tab__, and selecting the __RADIUS Server__ entry in the __Global Properties__ table. Once in that page
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenyou can now define RADIUS Clients, set the port on which to listen for requests, and enable the RADIUS server.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenWhenever this configuration for the RADIUS server changes you'll immediately see log entries in catalina.out that show
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenthe RADIUS server configuration being reloaded. For example, once radius is enabled the following log entries will
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenappear indicating that the listener is active and information about the backing thread pool for connections:
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 13:52:11.338 INFO [RADIUS-RadiusServiceStarter] <snip/> RADIUS Config Changed. Loading...
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 13:52:11.339 INFO [RADIUS-RadiusServiceStarter] <snip/> --- Loaded Config ---
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen [RadiusServiceConfig YES 1812 P( 1, 10, 10, 10)]
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 13:52:11.343 INFO [RADIUS-RadiusServiceStarter] <snip/> RADIUS service enabled. Starting Listener.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 13:52:11.355 INFO [RADIUS-1812-Listener] <snip/> RADIUS Listener is Active.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen Threads Core : 1
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen Threads Max : 10
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen Thread Keep-alive : 10 sec
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen Request Queue : 10
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenNote that when configuration changes the logging includes each client's configuration in a very concise form. If any RADIUS requests are
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen received before any clients are
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenconfigured or if the configured clients don't match the IP
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenaddress of the incoming packets the RADIUS server will log the attempt and silently drop to packet as specified in
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenthe RFC like so:
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 27-Jan-2015 09:45:25.004 WARNING [RADIUS-1812-Listener] <snip/>
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen No Defined RADIUS Client matches IP address /127.0.0.1. Dropping request.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenThis log message is very useful in that it specifies the exact value of the client's IP address that must be specified
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenin the client configuration page for packets from that client to be accepted for authentication. Once this IP address
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen is specified for a defined client the packets are now accepted and authentication
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen against modules in the client's specified chain will proceed.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen*Testing with ConsoleClient*
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenTo exercise the RADIUS server we can use this module's generated jar file to run the included
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen__ConsoleClient__ command line tool. It allows a user to authenticate to openAM using the RADIUS protocol by providing
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowensimple prompts on the command line and translating user input to corresponding requests to the server. To run this
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowentool open a command
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenshell that has access to java. Now change directory to be in the Open AM's WEB-INF/lib directory or include the full
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenmodule's jar file, such as openam-auth-radius-1.0.1.jar, in the following command for your current directory:
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen java -jar <path-to-jar>
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenWhen starting up it will print out its build information indicating its version and build date and then look for
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowena __radius.properties__ file in the current directory. If not found, as shown here, it will prompt the user to add
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowena __radius.properties__ file in the current directory with the indicated properties shown:
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen java -jar ~/tomcat8/apache-tomcat-8.0.9/webapps/sso/WEB-INF/lib/openam-auth-radius-1.0.1.jar
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen Feb 26, 2015 5:09:53 PM <snip/>
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen INFO: Loaded OpenAM Authn Radius Module = 1.0.1 built 2015-02-26 23:53 UTC
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen Missing required config file 'radius.properties' in current directory /Users/boydmr/.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen Must Contain:
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen secret=<shared-secret-with-server>
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen host=<hostname-or-ip-address>
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen port=<port-on-target-host>
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen May Contain:
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen show-traffic=true
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenThe shared secret must match exactly the value specified for the RADIUS Client configured in Open AM for this particular
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowentraffic. More on that in a minute. The host can be either a DNS name or an IP address and must resolve to the
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenOpen AM server or cluster. The port must match the port configured for the RADIUS server in openAM's console. For
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenexample, I'll create a radius.properties file with these values including telling the ConsoleClient to log the RADIUS
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen secret=letmein
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen host=127.0.0.1
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen show-traffic=true
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenOnce I have the radius.properties file defined the ConsoleClient will now prompt for Username and Password. This must be a
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenuser in OpenAM's backing user store. For my testing where I use embedded OpenDJ I used the admin console and created a
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenuser __boydmr__ in the root realm.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenOnce username and password are entered the ConsoleClient will connect to the RADIUS server and attempt to authentication
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenvia username and password. As required in [section 3 of RFC 2865](https://tools.ietf.org/html/rfc2865#section-3) for
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenthis communication to be accepted by the RADIUS server the IP address of the incoming
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenpacket __must match an IP address of a defined client or the packet will be dropped silently__.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenFor example, I have not yet defined any clients in the admin console. So when ConstoleClient attempts to connect it hangs
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenwith this output after I enter my username and password:
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen java -jar ~/tomcat8/apache-tomcat-8.0.9/webapps/sso/WEB-INF/lib/openam-auth-radius-1.0.1.jar
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen Feb 26, 2015 2:08:26 PM <snip/>
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen INFO: Loaded OpenAM Authn Radius Module = 1.0.1 built 2015-02-26 23:53 UTC
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen ? Username: boydmr
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen ? Password: password
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen Packet To 127.0.0.1:1812
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen ACCESS_REQUEST [1]
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen - USER_NAME : boydmr
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen - USER_PASSWORD : *******
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen - NAS_IP_ADDRESS : localhost/127.0.0.1
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen - NAS_PORT : 0
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenThe ConsoleClient hangs at this point and stops responding because it is waiting for a UDP response packet which will
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowennever come. This is clearly seen in the server side logs by the following log entry that results:
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 17:39:37.254 WARNING [RADIUS-1812-Listener] <snip/>
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen No Defined RADIUS Client matches IP address /127.0.0.1. Dropping request.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenThe IP address listed in the log is what must be entered for the client before the server will accept packets from that
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenclient and not drop them. Hence, when configuring new clients it is very useful to first receive traffic from them to
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenknow what value to use when configuring that client.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen*Configuring a Radius Server Client*
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenSo I once again access the Radius Server configuration page in Open AM's console. But this time I press the __New__
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenbutton in the Secondary Configuration Instance table. This lets me define a client allowed to connect to the Open AM
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenRADIUS server port. Give the client a descriptive name. It is only used in the configuration page so it can be whatever
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenhelps us remember what remote client this configuration is for. The Client IP Address value must match that value that
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenwe 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
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowengenerated for you and can be shared with the remote client out-of-band. Here, I set it to the same value that we have
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenin out radius.properties file, __letmein__. I chose to enable traffic logging so that we can see how things look from
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenthe server's viewpoint. The handler class should be left alone but enables alternative
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenimplementations being plugged in. See the comments in the page for the interface to implement for such an attempt.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenFinally, we come to Handler Class Configuration Properties. The OpenAMAuthHandler class expects two values:
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen realm = the name of a realm that contains the authentication chain to be used
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen chain = the name of the authentication chain to use
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenI chose to use the root realm and the default authentication chain created with a default Open AM configuration __ldapService__.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen chain=ldapService
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenOnce I press the __Add__ button I see the log output change indicating that the new configuration has been noticed and
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenthe RADIUS Server's Listener shut down and restarted with the new values.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 17:54:14.961 INFO [RADIUS-RadiusServiceStarter] com.sun.identity.authentication.modules.radius.server.config.RadiusServiceStarter.run RADIUS Config Changed. Loading...
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen 26-Feb-2015 17:54:14.961 INFO [RADIUS-RadiusServiceStarter] com.sun.identity.authentication.modules.radius.server.config.RadiusServiceStarter.run --- Loaded Config ---
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowen [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})]
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenthe packet is accepted by the server it will then attempt to authenticate the user via
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenusername and password. Hence, the first module in the chain specified for this client must use username and password for
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenits callbacks.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenIf other modules are included in the chain then each field required by that module will be
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenconveyed back to the ConsoleClient and it will prompt for each additional field. Once all have been entered then it will
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenfinish authentication against that module. This continues until the user fails to provide proper values required by
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenmodule in the chain or successfully authenticates to all modules in the chain.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenAs requests arrive at the Server log entries are made in catalina.out that can be used to troubleshoot problems with configuration.
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenIf the RADIUS Client is not properly configured in the Server the incoming request will be seen and logged by the server
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenbut will be discarded. For example, suppose that I defined my client
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie BowenIf you have questions send them to Mark Boyd
5c124de5c36bfc236d55578429df5f048f0d0a07Jamie Bowenat boydmr@ldschurch.org.