Access Management 7.4.1

RADIUS Server

This guide shows you how to configure, maintain, and troubleshoot ForgeRock Access Management when acting as a Remote Authentication Dial-In User Service (RADIUS) server.

About RADIUS

Learn about the RADIUS protocol and how AM supports it.
The RADIUS Server Service

Discover how AM acts as a RADIUS server.
Troubleshooting

Configure AM to troubleshoot the RADIUS Server service.
The RADIUS Authentication Module

AM as a RADIUS client can delegating authentication to an external RADIUS server.

ForgeRock® Identity Platform serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Introducing RADIUS

RADIUS is a lightweight, datagram-based protocol formally specified in RFC 2865 that is supported by many devices and servers for external authentication. VPN concentrators, routers, switches, wireless access points, and many other devices have native RADIUS support. Such devices are known as RADIUS clients. Using the RADIUS protocol, they converse with RADIUS servers to authenticate entities, such as users attempting to access their resources.

The RADIUS protocol itself is quite simple. There are four packet types:

  • Access-Request packets are sent from a client to a server to begin a new authentication conversation, or to respond to a previous response in an existing conversation and provide requested information.

  • Access-Accept packets are sent from a server to a client to indicate a successful authentication.

  • Access-Reject packets are sent from a server to a client to indicate a failed authentication.

  • Access-Challenge packets are sent from a server to a client to solicit more information from the entity being authenticated.

Each packet type defines:

  • A set of fields that must be included

  • Other fields that can be included to convey:

    • Additional requirements

    • Information about the context of the conversation

    • Attributes of the entity after successful authentication

An Access-Request packet always contains username and password fields but can contain additional fields that provide information about the client making the request. For example, the optional State field indicates that a packet is part of an authentication conversation already in progress; its absence indicates the start of a new conversation.

An authentication conversation always begins with an Access-Request packet that does not have a State field. If the RADIUS server only requires the username and password for authentication, then conversations will complete after the server sends an Access-Accept or Access-Reject packet, depending on whether the authentication credentials were valid.

If more information is required by the server, such as an SMS-relayed one-time password sent to the user’s phone, the additional requirement can be solicited using an Access-Challenge response to the client, followed by an Access-Request packet that has a State field that associates it with the existing conversation. The conversation completes with an Access-Accept or Access-Reject packet depending on whether the one-time password supplied in the second request matches the password sent to the user’s phone.

This conversational style in which the server accepts, rejects, or solicits more information makes RADIUS an excellent match for AM’s authentication infrastructure. AM performs authentication using chains of authentication modules found in realms.

These modules identify authentication requirements that are conveyed to clients wishing to authenticate. The modules then accept values submitted by the user for verification. The mechanism for modules to convey these requirements to AM is through a finite set of constructs known as callbacks. By leveraging AM’s flexible and extensible authentication mechanism, organizations can craft an authentication experience suitable for their needs, while using the same mechanisms for both HTTP and RADIUS authentication.

Two AM features support the RADIUS protocol: RADIUS server service and RADIUS authentication module.

RADIUS server service

The RADIUS server service provides a RADIUS server within AM. The server authenticates RADIUS clients that are external to AM. The server is backed by AM’s authentication chains and modules, thereby providing the possibility of multi-factor authentication in addition to simple username and password authentication.

The following example shows the flow of a successful username and password authentication attempt from a RADIUS client:

RADIUS server service: simple authentication flow
Figure 1. RADIUS server service: simple authentication flow

The following example shows the flow of a successful multi-factor authentication scenario in which the RADIUS Server service is backed by an authentication chain that includes the LDAP and the ForgeRock Authenticator (OATH) authentication modules. First, the LDAP authentication module requires the user to provide a user name and password. Then, the ForgeRock Authenticator (OATH) module requires the user to enter a one-time password obtained from the authenticator app on a mobile phone:

RADIUS server service: multi-factor authentication flow
Figure 2. RADIUS server service: multi-factor authentication flow

The AM RADIUS server is disabled by default. To enable it, perform the following steps:

Enable and configure the RADIUS server

  1. In the AM admin UI, go to Configure > Global Services, and click RADIUS Server.

  2. Under Secondary Configuration Instance, click New.

    AM uses secondary configuration instances in the RADIUS Server service to encapsulate RADIUS clients. You must configure one secondary configuration instance, also known as a subconfiguration, for each client that will connect to the RADIUS Server.

  3. Configure attributes for the subconfiguration.

    Refer to RADIUS server for information about configuring the subconfiguration attributes.

  4. Click Add to add the configuration for the RADIUS client to the overall RADIUS server service configuration.

  5. If you have multiple RADIUS clients that will connect to the AM RADIUS server, add a subconfiguration for each client.

    You don’t need to configure all your RADIUS clients when you configure the RADIUS server service initially—you can add and remove clients over time as you need them.

  6. Configure global attributes of the RADIUS server service.

    At a minimum, set the Enabled field to YES to start the RADIUS server immediately after you save the RADIUS server service configuration.

    Refer to RADIUS server for information about configuring the RADIUS server service’s global attributes.

  7. On the main configuration page for the RADIUS server service, click Save.

The RADIUS server starts immediately after you save the configuration if the Enabled field has the value YES. If you make changes to the RADIUS server service configuration, the changes take effect as soon as you save them.

Troubleshooting

To troubleshoot the RADIUS server service, enable message-level debug logging.

With message-level debug logging enabled, AM writes messages to the Radius debug log file when notable events occur, including the following:

  • RADIUS server startup

  • Changes to the RADIUS server configuration

  • Successful and unsuccessful client connections

  • Various error events

You can configure the RADIUS server service to log the packets sent between RADIUS clients and AM. To enable packet logging, use the Log Packet Contents for this Client property when configuring RADIUS clients in the RADIUS server service.

Solutions to common RADIUS server service issues

This section offers solutions to issues that you might encounter when configuring communication between RADIUS clients and the RADIUS server service. The solutions assume that you have enabled message-level debugging for the RADIUS server service and have access to the debug logs.

Client cannot connect

When a RADIUS client connects to AM’s RADIUS server and hangs without receiving a response, the problem could be one of four possible issues:

  • The AM RADIUS server service is not enabled.

    An entry similar to the following in the Radius debug log indicates that AM’s RADIUS server was started:

    amRadiusServer:10/12/2015 12:00:14:814 PM PDT: Thread[RADIUS-1812-Listener,5,main]:
TransactionId[27350419-8c21-429e-b580-35abf64604cf]
RADIUS Listener is Active.
Port              : 1812
Threads Core      : 2
Threads Max       : 10
Thread Keep-alive : 10 sec
Request Queue     : 10

    If no such entry exists in the debug log, re-examine the configuration for the RADIUS server service and correct the problem.

  • The client is not defined.

    An entry similar to the following in the Radius debug log indicates that the client cannot connect:

    amRadiusServer:10/12/2015 04:05:53:681 PM PDT: Thread[RADIUS-1812-Listener,5,main]:
TransactionId[270084d5-b7d0-42e4-8709-eeaeaf435aff]
WARNING: No Defined RADIUS Client matches IP address /192.168.10.10. Dropping request.

    To fix the problem, correct the client configuration in the RADIUS server service.

  • The handler class for the client is incorrect.

    An entry similar to the following in the Radius debug log indicates an incorrect handler class:

    ERROR: Configuration setting handlerClass in RADIUS Client configuration named
'TestClient' is invalid. Requests from this client will be ignored.

    To fix the problem, correct the client configuration in the RADIUS server service.

  • Traffic is not arriving at the AM server.

    No specific debug log entries appear for this problem.

    This is likely a network communication problem. Investigate the route for traffic between the RADIUS client and the RADIUS server to see where communication is lost.

Authentication always fails

When authentication always fails, the probable cause is one of the following three issues:

  • The client secret configured for the client in the RADIUS Server service is incorrect.

    In an Access-Request packet, the shared secret is used along with the random value sent in the request authenticator field to encrypt the password field value that is passed across the wire. If the client and server’s shared secrets are not identical, the password expected by the server will not match the password sent by the client, resulting in authentication always failing. The user’s password is always incorrect in such a scenario and there is no way for the server to differentiate between the client secret being incorrect and the password sent from the client being incorrect. The log file indicates that AM has sent an Access-Reject packet to the client, similar to the action that would be taken if the shared secret matched on the client and server and the user entered an invalid password:

    amRadiusServer:10/12/2015 04:27:55:785 PM PDT: Thread[RADIUS-1812-Listener,5,main]:
TransactionId[270084d5-b7d0-42e4-8709-eeaeaf435aff]
finalPacketType sent in response to auth request: 'ACCESS_REJECT'

    Since the shared secret is specific to each client, such messages might appear for one RADIUS client, while other clients can authenticate successfully.

    To fix this problem, correct the configuration for your client in the RADIUS Server service.

  • The realm configured for the client in the RADIUS Server service is incorrect.

    An entry similar to the following in the Radius debug log indicates an invalid realm in the RADIUS Server service configuration:

    ERROR: Unable to start login process. Denying Access.
com.sun.identity.authentication.spi.AuthLoginException: Domain is invalid\|
invalid_domain.jsp

    If the realm is missing from the configuration, an error similar to the following appears:

    ERROR: Unable to initialize declared handler class
'org.forgerock.openam.radius.server.spi.handlers.OpenAMAuthHandler' for RADIUS
client ''. Rejecting access.
java.lang.IllegalStateException: Configuration property 'realm' not found in
handler configuration. It must be added to the Configuration Properties for this
class in the Radius Client's configuration.

    To fix this problem, correct the client configuration in the RADIUS Server service.

  • The authentication chain configured for the client in the RADIUS Server service is incorrect.

    An entry similar to the following in the Radius debug log indicates an invalid authentication chain in the RADIUS Server service configuration:

    amRadiusServer:10/12/2015 05:32:21:771 PM PDT: Thread[pool-5-thread-2,5,main]:
TransactionId[378a41cf-0581-4b62-a92f-be2b008ab4d3] ERROR: Unable to start login
process. Denying Access.

    If the chain is missing from the configuration, an error similar to the following appears:

    ERROR: Unable to initialize declared handler class
'org.forgerock.openam.radius.server.spi.handlers.OpenAMAuthHandler' for RADIUS
client ''. Rejecting access.
java.lang.IllegalStateException: Configuration property 'chain' not found in
handler configuration. It must be added to the Configuration Properties for this
class in the Radius Client's configuration.

    To fix this problem, correct the client configuration in the RADIUS Server service.

Configuration is correct but authentication fails

In this case, you might have a client-specific problem. AM provides a tool that you can use to eliminate AM and its configuration as the cause of the problem. You can declare an alternate handler class implementation in the RADIUS Server service configuration. Two test handlers are available for troubleshooting purposes:

  • The org.forgerock.openam.radius.server.spi.handlers.AcceptAllHandler handler always returns an Access-Accept packet, indicating successful authentication for all requests.

  • The org.forgerock.openam.radius.server.spi.handlers.RejectAllHandler handler always returns an Access-Reject packet, indicating failed authentication for all requests.

In a case where you believe that configuration is correct but authentication always fails, you could specify the org.forgerock.openam.radius.server.spi.handlers.AcceptAllHandler handler class in the RADIUS Server service configuration for your client. With packet logging enabled, all requests received from the client should log packet contents traffic similar to the following even if the password is incorrect:

WARNING:
Packet from TestClient:
  ACCESS_REQUEST [1]
    - USER_NAME : demo
    - USER_PASSWORD : *******
    - NAS_IP_ADDRESS : /127.0.0.1
    - NAS_PORT : 0

This is followed by:

WARNING:
Packet to TestClient:
  ACCESS_ACCEPT [1]

If the client still indicates that authentication has failed, refer to the documentation for the client to determine why the Access-Accept response is rejected. Most likely, the client expects specific fields in the Access-Accept response that are not provided by AM. There is currently no facility in AM to return fields in Access-Accept responses.

Authentication always succeeds, even with a bad password

This would be a very unusual situation, probably due to the org.forgerock.openam.radius.server.spi.handlers.AcceptAllHandler handler being left in place after troubleshooting an error scenario in which authentication always suceeds.

To resolve the problem, verify that the correct handler class is specified in the RADIUS Server service configuration for the client. If it is not specified, review the authentication modules in the chain that authenticates users and determine whether one of the modules might be accepting all authentication requests. This situation could also occur because of incorrectly-specified module criteria in the chain’s definition.

Limitations

Deploying AM’s RADIUS server lets an organization consolidate RADIUS and HTTP authentication into a single solution, facilitating reuse of existing authentication mechanisms between both types of clients. However, there are several limitations:

  • Because RADIUS authentication attempts always start with a username and password transmitted in an Access-Request packet, the first module in an authentication chain used for RADIUS clients must accept a username and a password.

  • By default, AM caches up to 5,000 RADIUS clients concurrently.

    If necessary, you can change the maximum number of RADIUS clients that can be cached concurrently on an AM server by configuring the org.forgerock.openam.radius.server.context.cache.size advanced server property.

    Refer to Configuring Servers for information about how to configure advanced server properties.

  • Some AM callback types are not applicable to RADIUS clients. For example, a RedirectCallback directs HTTP clients, such as browsers, to HTTP resources to be used for some aspect of authentication. Redirects make no sense to RADIUS clients and cannot be consumed in any meaningful way.

    A ConfirmationCallback also presents challenges for RADIUS clients.

    As a result, some AM authentication modules cannot be used with RADIUS clients. Before attempting to use an authentication module with RADIUS clients, review the module’s callbacks to determine whether the module will support RADIUS clients. You can use the REST API to determine the callbacks for an authentication module as described in Authenticate over REST.

  • Some client mechanisms leveraged by authentication modules might not be applicable to RADIUS clients. For example, suppose a customized SMS one-time password module sends a one-time password over an SMS service, and then provides a ChoiceCallback that lets the user set a cookie in their browser that expires after 30 days. Such a module might first determine whether the cookie was available, still valid, and applicable to the current user before reissuing a new one-time password and soliciting the value from the user.

    RADIUS clients are unable to process HTTP cookies. Although RADIUS clients can support a ChoiceCallback, the customized feature described in the previous paragraph would not function correctly for RADIUS clients, and therefore should not be deployed with RADIUS clients. As a result, some callback sets within an authentication module will differ depending on the type of client being authenticated.

  • The RADIUS Server service logs only to the ForgeRock common audit logger introduced in OpenAM 13. It does not log to the classic audit logs that were available prior to OpenAM 13.

When building custom authentication modules, consider their suitability for handling the types of clients that might use them, and make adjustments to callbacks as needed.

RADIUS authentication module

The RADIUS authentication module lets AM act as a RADIUS client, delegating authentication to an external RADIUS server:

RADIUS authentication module: successful authentication flow
Figure 3. RADIUS authentication module: successful authentication flow

Use the RADIUS authentication module when you want AM to pass usernames and passwords through to an external RADIUS server, so that it can authenticate the users.

For information about configuring the RADIUS authentication module, refer to RADIUS authentication module properties.