2 Installing and Configuring Oracle RADIUS Agent
2.1 Prerequisites for Installing Oracle RADIUS Agent
These are the tasks that you must complete before you install Oracle RADIUS Agent.
-
The latest container engine is installed and the container service is started. Ensure that an external container volume is mounted in the container for persistent storage of configuration, data, and logs.
-
Create a directory on the file system to store the Oracle RADIUS Agent configuration and logs data. The
uid:gid
of the directory must match the user who will start the container. Starting April 2022 release, Oracle RADIUS Agent uses a defaultuid:gid
of14304:14304
for the oracle user running in the container that performs all container operations. The read and write permissions on the directory must be set torwxr-x---
. This directory will be mapped to the container volume when you start the container. If you want to use a different user in your deployment, use an overrideuid:gid
value at the runtime and set the directory permission torwxr-x--
. The following is a sample command to override theuid:gid
.docker run -d --network rad --name radius1 --user 10001:5001 -v /scratch/radius:/u01/oracle/user_projects -p 8000:8080 -p 1812:1812/udp -p 1813:1813/udp -p 1814:1814 -e INSTANCE_NAME=inst1 container-registry.oracle.com/middleware/radius:latest
- This directory must be backed up for disaster recovery.
-
A running instance of the LDAP server against which you want Oracle RADIUS Agent to authenticate and authorize access.
-
The LDAP server should contain a user (or users) that acts as a RADIUS Administrator. The administrator user (or users) need to have the necessary ACL configured on the LDAP server to be able to search users and groups.
-
If Oracle RADIUS Agent connects to the LDAP server over SSL, then ensure that you have the trusted CA certificate that signed the LDAP server certificate, in PEM format.
-
If you intend to use Oracle RADIUS Agent with Oracle Advanced Authentication for multi-factor authentication, then ensure you have a running instance of Oracle Advanced Authentication. See Use Oracle Radius Agent with LDAP as the Primary Authenticator Oracle Advanced Authentication Administrating guide for information about installing Oracle Advanced Authentication.
2.2 System Requirements and Certification
These are system requirements and certification for installing Oracle RADIUS Agent.
Ensure that your environment meets the system requirements such as hardware and software, minimum disk space, memory, required system libraries, packages, or patches before performing any installation.
The minimum system requirements for installing Oracle RADIUS Agent (ORA) is:
- For installing ORA on a standalone host:
- 4 GB of RAM
- Disk Space of 10 GB
- 2 CPU
- For installing ORA on a server:
- 8 GB of RAM
- Disk Space of 50 GB
- 2 CPU (with virtualization support, for example Intel VT)
http://www.oracle.com/technetwork/middleware/ias/downloads/fusion-certification-100350.html
2.3 Summary of Steps to Install and Configure Oracle RADIUS Agent
This is a high-level list of steps involved in installing and configuring Oracle RADIUS Agent.
-
Ensure that all the prerequisites for installing Oracle RADIUS Agent are met.
-
Obtain the container image for Oracle RADIUS Agent.
-
Create and start the container and then verify its health status.
-
If you intend to use Oracle RADIUS Agent for multi-factor authentication, then ensure that you have a running instance of Oracle Advanced Authentication .
-
Set up and validate the day-0 or initial configuration.
-
Create global or application-specific configurations as per your requirement.
-
Register the RADIUS client and generate a shared secret.
-
Configure the RADIUS client with the generated shared secret and Oracle RADIUS Agent details.
2.4 Understanding Oracle RADIUS Agent Files and Directories
Learn about the files and directories that Oracle RADIUS Agent stores in the mounted persistent volume of the container.
-
All configuration and data is stored in the
/u01/oracle/user_projects
location. -
Instance-specific files (such as instance logs) are stored in the
/u01/oracle/instances
location. If this is not mounted, then instance-specific files will default to the/u01/oracle/user_projects
location.
To externalize these files and directories, you can mount container volumes (using -v) for the above two paths as required, so that they are persisted outside the container. The details for creating the volume and the permissions required are outlined in the Prerequisites for Installing Oracle RADIUS Agent section.
2.5 RADIUS Vendor Specific Attributes
Note:
Oracle DB authorizations based on roles requires you to define ORACLE_ROLE VSA, which is included in Oracle RADIUS Agent.2.6 Understanding Instance-Specific Parameters
Learn about the instance-specific parameters that you can set and configure while starting the container for Oracle RADIUS Agent.
-
INSTANCE_NAME
This is a mandatory parameter for Oracle RADIUS Agent. Within the location that contains all the Oracle RADIUS Agent files, a directory named INSTANCE_NAME is created for each Oracle RADIUS Agent instance. All logs will be present within this INSTANCE_NAME directory.
-
java_args
JVM Options can be provided. For example:-e java_args='-server -XX:+UnlockExperimentalVMOptions -XX:+UseZGC -Xmx1g'
-
DISABLE_HTTPS
If this value is true, then by default REST endpoints will not be https enabled. -
OVERRIDDEN_INSTANCE_CONFIG
This is an optional parameter for specifying instance-specific logging configuration (such as logging levels) that will be overridden during container startup.
If a particular instance must be started with desired levels of logging, then you can pass a
logging.properties
file as part of this environment variable. Thislogging.properties
file should be stored in the volume mapped to the/u01/oracle/user_projects
location.The contents of the
logging.properties
file must be similar to the following entry:oracle.idm.radius.level=FINEST
-
DEPLOYMENT_NAME
This represents name of the Oracle RADIUS Agent deployment. This value is internally used to identify the deployment and its configurations. When multiple Oracle RADIUS Agent instances are running in a cluster sharing the same configuration, the deployment name must be the same for all the instances in the cluster.
It is recommended to pass deployment name. When it is not passed, a random deployment name is generated and stored in thedeployment.properties
file.Note:
It is recommended not to manually update deployment name or any other detail in thedeployment.properties
file.-e DEPLOYMENT_NAME=oraprod1
2.7 Installing Oracle RADIUS Agent
Oracle RADIUS Agent is available as a container image. Installing Oracle RADIUS Agent involves pulling the container image, starting the Oracle RADIUS Agent container, and selecting the storage for the configuration files.
2.8 Initial or Day-0 Configuration
The initial or day-0 configuration involves setting up a minimum required configuration for Oracle RADIUS Agent container to start.
The information contained in this chapter is explained in detail in the following tutorials: Use Oracle Radius Agent with LDAP as the Primary Authenticator and Use Oracle Radius Agent with Oracle Advanced Authentication for Multi-Factor Authentication .
By default, the container for Oracle RADIUS Agent does not contain any configuration. You must seed in an initial configuration to initialize Oracle RADIUS Agent with your configuration payload.
Seeding in the initial configuration for Oracle RADIUS Agent involves, at a minimum, defining administrator users or groups along with any other configuration required for authentication. These administrator users and groups must preexist in your primary authenticator (LDAP server).
Note:
At least one admin user must be able to bind to your LDAP server otherwise the Oracle RADIUS Agent REST APIs will not be functional.If you intend to use Oracle RADIUS Agent with Oracle Advanced Authentication for multi-factor authentication, then you must additionally define the required configuration.
You can seed the initial configuration by invoking the following unprotected REST endpoint using the POST method:
https://<hostname.domain>:PORT/radius-config/v1/init
To validate the initial configuration before saving it, invoke the following unprotected REST endpoint using the POST method:
https://<hostname.domain>:PORT/radius-config/v1/validate
In both the endpoints, PORT is the host configuration port number (HOST_CONFIG_PORT) specified in the docker run
command. The same port is used in the endpoint URLs for all the REST calls.
After the initial configuration is complete, Oracle RADIUS Agent configuration and administration APIs perform HTTP Basic Authentication as the RADIUS admin user stored in the LDAP server.
The following is the payload that you must pass by using the unprotected REST endpoint for seeding the initial configuration. If you are not using multi-factor authentication with Oracle Advanced Authentication, or you wish to configure at a later time, you may skip the mfa
section.
{
"radiusAdminGroup": [
“ADMIN_GRP1”,”ADMIN_GRP2”,”ADMIN_GRPn”
],
"radiusAdminUser": [
“USERID1 or USER1_DN”,”USERID2 or USER2_DN”,”USERIDn or USERn_DN”
],
"authentication": {
"provider": "LDAP",
"ldap": {
"name": "LDAP_SERVER_NAME",
"dn": "LDAP_SERVER_ADMIN",
"password": "LDAP_SERVER_ADMIN_PASSWORD",
"ldapUrl": "LDAPS_URL",
"baseDN": "LDAP_SERVER_BASE_DN",
"trustedCertificate": "BASE64_TRUSTED_CA_CERT"
}
},
"mfa": {
"provider": "OAA",
"oaa": {
"oaaUrl": "OAA_RUNTIME_URL",
"oaaPolicyUrl": "OAA_POLICY_URL",
"policyUserName": "POLICY_USERNAME_FROM_OAA_IN_THE_FORMAT_OF_RELEASENAME-oaa-policy",
"policyUserPassword": "POLICYKEY_FROM_OAA"
}
},
"preferences": {
"mfaOptions": {
"defaultGroup": "GROUP_NAME",
"factorChoices": [
"OAA_FACTORS_TO_USE"
]
}
}
}
Note:
The parameters "oaaUrl", "oaaPolicyUrl", "policyUserName", and "policyUserPassword" must be obtained from Oracle Advanced Authentication).The configuration types such as authentication
and mfa
are described in Table 2-1.
In the above example, trustedCertificate
is used to point to a base64 PEM encoded trusted CA certificate. Alternatively, you can specify the location of the Java keystore (JKS) that contains the certificate. See Configuration Properties for the parameters you need to set when you are using a JKS.
In the mfa
section above a new Oracle Advanced Authentication (OAA)
Agent for RADIUS is created along with an Assurance Level and Policy in one operation.
The names assigned to the Agent, Assurance Level and Policy are assigned by OAA
directly. If you have previously created your own OAA Agent for RADIUS, along with your
own Assurance Level and Policy, then the parameters to pass will change. Refer to the
mfa
parameters in the Configuration Properties section.
The response for this payload will be the initial configuration details that you specified and the port on which Oracle RADIUS Agent listens.
The following is an example cURL command and the payload:
curl --header "Content-Type: application/json" --request POST --data-binary @- https: //localhost:8000/radius-config/v1/init
{
"radiusAdminGroup": [
"cn=radiusAdmin1,ou=groups,dc=example,dc=com",
"cn=radiusAdmin2,ou=groups,dc=example,dc=com"
],
"radiusAdminUser": [
"uid=user1,ou=people,dc=example,dc=com",
"uid=user2,ou=people,dc=example,dc=com"
],
"authentication": {
"provider": "LDAP",
"ldap": {
"name": "Corporate LDAP",
"dn": "cn=Directory Manager",
"password": "<password>",
"ldapUrl": "ldaps://ldap.example.com:1636",
"baseDN": "dc=example,dc=com",
"trustedCertificate": "-----BEGIN CERTIFICATE-----\nMIICwzCCAaugAwIBAgIEGfd1kTANBgkqhkiG9w0BAQsFADASMRAwDgYDVQQDEwdteW91ZGRzMB4XDTIxMDIwODE0MDYyNFoXDTIyMDIwODE0MDYyNFowEjEQMA4GA1UEAxMHbXlvdWRkczCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKyx3l/E4Bt5CLsHSU2UbhPAcSzlsTaOJRZ0V7qAVm6SMlBslokzQthZTuXtlIDlIUcWdCTmMOsk9rZ36E8lfEkz/gf5HvXXIaV416Z5O5g4OVQ3MZuPgGvFE17eZRND9NnRdAIv3RWBLjnOGFoD8z7US1i8h7f3fZyZ/GaQ0VcP4B1ooUTzcQ7MFVymRHMXhlGFVm6cxES5b6EI2R9Wv/BgPY1/Vypq2kJGJdCoNO8IfXLq1FoGsY2QEbe8tQYJp+cU+WYqAC7cDkNiJ8cxeJ+/HQ3FFM7BmgzANOrekhNvjCZni9P2PMFXIpO12vEgmtiY4NePoPuyensIznkFySMCAwEAAaMhMB8wHQYDVR0OBBYEFPJglmgVMkO6FP1ESs32a8HlbO4ZMA0GCSqGSIb3DQEBCwUAA4IBAQAq2whjOzvMaFTD1m7JK2kzLEtBllJmZ72pwUIz8x0Ju3Kcr4jQeDAq3mOfxR6udWQsJ7+Ovjuvf/i06HHOxzAbOXOXAyzzS8jbkUX8VjGQueNFdZ7KxumT85gFNkBpe3sDdDmRxgY1pOFIUESFkcie7rLwCGo1q1z0KvwbqodeZnBprTSFHbePGNAndujVODo4xdH7fIlTrzx6L36BtJKYEKewmrDu9XbhGM1c8va100WRAHf3IIg8fnrf9Yf3c5+oYdxJoDAr0Y9N8J8ew2Fpdab+I5foQ7kVOCI4OZ23FOLDtGJEy5mArhTV95EOpqp6+GnE3FnATzUf5ecRChRB\n-----END CERTIFICATE-----",
}
},
"mfa": {
"provider": "OAA",
"oaa": {
"oaaUrl": "https://oaa.example.com:32461/oaa/runtime",
"oaaPolicyUrl": "https://oaa.example.com:32004/oaa-policy",
"policyUserName": "oaainstall-oaa-policy",
"policyUserPassword": "eb3188094918b1bc8e4fd584e8c27f8e7f3fe338"
}
},
"preferences": {
"mfaOptions": {
"defaultGroup": "Default",
"factorChoices": [
"ChallengeEmail",
"ChallengeOMATOTP",
"ChallengeSMS"
]
}
}
}
And the following is the corresponding response:
{
"radiusListener": {
"port": 1812
},
"authentication": {
"provider": "LDAP",
"ldap": {
"name": "Corporate LDAP",
"dn": "cn=Directory Manager",
"password": "{AES-GCM}yx8i83DxHhVAKzJ7QE85/z78ohhFUxmUu6HcGdhxQvkTGaMw",
"ldapUrl": "ldaps://ldap.example.com:1636",
"baseDN": "dc=example,dc=com",
"trustedCertificate": "-----BEGIN CERTIFICATE-----\nMIICwzCCAaugAwIBAgIEGfd1kTANBgkqhkiG9w0BAQsFADASMRAwDgYDVQQDEwdteW91ZGRzMB4XDTIxMDIwODE0MDYyNFoXDTIyMDIwODE0MDYyNFowEjEQMA4GA1UEAxMHbXlvdWRkczCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKyx3l/E4Bt5CLsHSU2UbhPAcSzlsTaOJRZ0V7qAVm6SMlBslokzQthZTuXtlIDlIUcWdCTmMOsk9rZ36E8lfEkz/gf5HvXXIaV416Z5O5g4OVQ3MZuPgGvFE17eZRND9NnRdAIv3RWBLjnOGFoD8z7US1i8h7f3fZyZ/GaQ0VcP4B1ooUTzcQ7MFVymRHMXhlGFVm6cxES5b6EI2R9Wv/BgPY1/Vypq2kJGJdCoNO8IfXLq1FoGsY2QEbe8tQYJp+cU+WYqAC7cDkNiJ8cxeJ+/HQ3FFM7BmgzANOrekhNvjCZni9P2PMFXIpO12vEgmtiY4NePoPuyensIznkFySMCAwEAAaMhMB8wHQYDVR0OBBYEFPJglmgVMkO6FP1ESs32a8HlbO4ZMA0GCSqGSIb3DQEBCwUAA4IBAQAq2whjOzvMaFTD1m7JK2kzLEtBllJmZ72pwUIz8x0Ju3Kcr4jQeDAq3mOfxR6udWQsJ7+Ovjuvf/i06HHOxzAbOXOXAyzzS8jbkUX8VjGQueNFdZ7KxumT85gFNkBpe3sDdDmRxgY1pOFIUESFkcie7rLwCGo1q1z0KvwbqodeZnBprTSFHbePGNAndujVODo4xdH7fIlTrzx6L36BtJKYEKewmrDu9XbhGM1c8va100WRAHf3IIg8fnrf9Yf3c5+oYdxJoDAr0Y9N8J8ew2Fpdab+I5foQ7kVOCI4OZ23FOLDtGJEy5mArhTV95EOpqp6+GnE3FnATzUf5ecRChRB\n-----END CERTIFICATE-----"
}
},
"mfa": {
"provider": "OAA",
"oaa": {
"name": "Global OAA",
"oaaUrl": "https://oaa.example.com:32461/oaa/runtime",
"clientSecret": "9e179ba1-125e-49a4-a0af-a67589031cca",
"clientId": "f530eea9-c9de-493e-9a39-6fea3b155214",
"agentgid": "5ff186f1-c291-4940-be38-df58033ab1b4"
}
},
"preferences": {
"mfaOptions": {
"defaultGroup": "Default",
"factorChoices": [
"ChallengeEmail",
"ChallengeOMATOTP",
"ChallengeSMS"
],
"assuranceLevel": "AssuranceLevel-b5f2cca3"
}
}
}
This completes the initial configuration for Oracle RADIUS Agent and all REST API endpoints are now protected. Any subsequent configuration requires the Oracle RADIUS Agent administrator credentials to perform HTTP Basic Authentication.
2.9 Setting Up Global and Application Configurations
A global configuration is a set of configurations that is shared by all RADIUS clients in your Oracle RADIUS Agent instance. In actual deployment environments, different applications can have different configuration requirements. In such scenarios, you can define an application-scoped configuration that will override the global configuration for the RADIUS client. Settings not defined in the application configuration are inherited from global configuration.
2.9.1 Understanding Global and Application Configurations
If you intend to set distinct configurations for various RADIUS clients, then you can override specific global configuration settings by using an application configuration with settings that are specific to a given RADIUS client.
For example, suppose your environment consists of two RADIUS clients namely Oracle Database and a VPN client. Both these clients use the same primary and secondary authenticators, but different set of authentication factors for multifactor authentication. In such a scenario, you can define an application configuration for each of the clients to set the respective factors.
Similarly, when you need a dedicated listener for a VPN client that requires higher load and a shared listener for the rest of RADIUS clients in your environments, you can define an application configuration with the dedicated listener port configuration just for the VPN client.
Any other configuration that is not explicitly defined as part of application configuration is inherited from global configuration if it exists. Although you can set different sets of configuration for different RADIUS clients by using application-scoped configuration, admin users or groups set as part of the initial configuration will apply to both global and application-scoped configurations.
2.9.2 Creating Global and Application Configurations
You can create or define a global or an application configuration by making a POST request to the following REST API endpoint:
https://<host.domain>:PORT/radius-config/v1/configurations
Table 2-1 lists the possible values for CONFIG_TYPE
.
Table 2-1 Configuration Types
Configuration Type | Description |
---|---|
|
Use this configuration type to specify details about the primary authenticator. For example, if you are using an LDAP server as the primary authenticator, then you specify its name, URL, admin user and password, its base DN, and SSL configuration in the |
|
Use this configuration type to specify details about Oracle Advanced Authentication to use for multi-factor authentication. For example, you specify details such as the OAA run-time URL, client ID, and client secret in this section. |
|
Use this configuration type to set various preferences based on the deployment requirements. For example, you can specify whether groups must be returned during authentication, specify the type of authentication mode for multi-factor authentication, specify mappings for users and groups in this section. |
|
Use this to specify the configuration for your Oracle RADIUS Agent listener port. |
|
Use this configuration type to enable or disable logging and also set the log levels. For information on how to set the logging properties refer to Configuring Logging section. |
|
Use this configuration type for setting configurations related to Oracle RADIUS Agent. For example, you can enable or disable Oracle RADIUS Agent metrics, specify whether dynamic RADIUS clients based on CIDR notation are allowed in this section. |
For information about the attributes that you can set and use in each of the configuration types listed above, see REST API documentation.
The following is an example payload to add a new global configuration for the server
configuration type:
{
"server": {
"enableMetrics": false,
"heartBeatInterval": "100000"
}
}
The following is the corresponding response:
{
"server": {
"enableMetrics": false,
"heartBeatInterval": 100000
}
}
An application configuration payload is the same as global configuration payload, except that the configuration is enclosed within the application {}
configuration type and contains 2 additional properties named "RADIUS_CLIENT_NAME"
and "radiusClientHost"
.
To define an application configuration, use the following format for your payload:
{
"application": {
"RADIUS_CLIENT_NAME": {
"radiusClientHost": "HOST_NAME_OR_IP_ADDRESS_OF_THE_COMPUTER_HOSTING_THE_RADIUS_CLIENT",
"CONFIG_TYPE": {
"PROP1_KEY": "PROP1_VALUE",
"PROP2_KEY": "PROP2_VALUE",
"PROPn_KEY": "PROPn_VALUE"
}
}
}
}
In this format:
-
CONFIG_TYPE is the type of configuration that you want to set.
-
PROPn_KEY and PROPn_VALUE are the properties key-value pairs that you can set for each configuration type.
-
"RADIUS_CLIENT_NAME"
is any name that you specify to identify the RADIUS client for which you are setting the application configuration. "radiusClientHost"
is a key whose value must be set to the IP address or hostname of the computer hosting the RADIUS client for which you are setting the application configuration.
The following example illustrates the scenario in which you can set an application configuration:
Suppose you have two RADIUS clients namely a database server and a VPN client. Now suppose you want both these clients to use a different set of factors for multi-factor authentication. In such a scenario, you can define an application configuration for each of the clients to define the respective factors.
The following is a sample payload of an application configuration for setting authentication factors for the database RADIUS client. An agent and assurance level for Oracle RADIUS Agent must have been pre-created in Oracle Advanced Authentication.
{
"applicationConfig": {
"dbRadiusClient": {
"radiusClientHost": "192.0.2.25",
"mfa": {
"provider": "OAA",
"oaa": {
"oaaUrl": "https://oaa.example.com:32461/oaa/runtime",
"clientId": "f530eea9-c9de-493e-9a39-6fea3b15521",
"clientSecret": "9e179ba1-125e-49a4-a0af-a67589031cca",
"agentgid": "5ff186f1-c291-4940-be38-df58033ab1b4"
}
},
"preferences": {
"mfaOptions": {
"assuranceLevel": "AssuranceLevel1"
}
}
}
}
}
The following is a sample payload of an application configuration for setting factors for the VPN RADIUS client:
{
"applicationConfig": {
"vpnRadiusClient": {
"radiusClientHost": "192.0.2.50",
"mfa": {
"provider": "OAA",
"oaa": {
"oaaUrl": "https://oaa.example.com:32461/oaa/runtime",
"clientId": "f530eea9-c9de-493e-9a39-6fea3b15521",
"clientSecret": "9e179ba1-125e-49a4-a0af-a67589031cca",
"agentgid": "5ff186f1-c291-4940-be38-df58033ab1b4"
}
},
"preferences": {
"mfaOptions": {
"assuranceLevel": "AssuranceLevel1"
}
}
}
}
}
2.10 Registering a RADIUS Client and Generating the Shared Secret
Whenever you add a new application or service to your network, you must register it as a RADIUS client with Oracle RADIUS Agent and then generate a shared secret for the client to communicate with Oracle RADIUS Agent.
To register a client and generate shared secret, make a POST request to the following REST API endpoint:
https://radius.example.com:PORT/radius-admin/v1/clients
When making the request, enter the Oracle RADIUS Agent admin credentials, configured as part of the initial configuration, for HTTP basic authentication.
The following is the payload that you must pass to the preceding REST API endpoint:
{
"applicationName": "NAME_OF_THE_RADIUS_CLIENT",
"hostName": "HOSTNAME_OR_IP_ADDRESS_OF_THE_COMPUTER_HOSTING_THE_RADIUS_CLIENT",
"applicationType": "TYPE_OF_RADIUS_CLIENT",
"description": "RADIUS_CLIENT_DESCRIPTION"
}
The client details that you specified and the client ID and the shared secret for the registered client is returned in the response. Ensure to note down the shared secret as you must specify this value while configuring your RADIUS client. For example, if you intend to use Oracle Database as your RADIUS client, then you specify the generated shared secret in the database radius.key file.
The following is a sample payload that makes a POST request to the https://<host.domain>:PORT/radius-admin/v1/clients
REST API endpoint:
{
"applicationName": "MyDatabaseClient",
"hostName": "198.51.100.1",
"applicationType": "Oracle",
"description": "Oracle Database"
}
And the following is the corresponding sample response:
{
"applicationName": "MyDatabaseClient",
"applicationType": "Oracle",
"hostName": "198.51.100.1",
"id": 2,
"sharedSecret": "NWNphF-mBec"
}
Registering a Dynamic Client
Dynamic client registration allows IP address of the RADIUS client to be specified using CIDR notation.
You can register a dynamic client only if the dynamic client is allowed. To allow a dynamic client, enable the enableDynamicClients
field in Server Configuration.
The following are the examples for dynamic clients with IP address in CIDR format:
enableDynamicClients
flag can be passed in Day-0
init as mentioned in the following
example:"server": {
"enableDynamicClients":true
}
For Day-N, if the server configuration is missing, then you can use a POST request to add server configuration as mentioned in the following example:
"server": {
"enableDynamicClients":true
}
If server configuration is present, then you can use a PATCH request to update the value of the flag as mentioned in the following example:
"server": {
"enableDynamicClients":true
}
If dynamic clients is not enabled, dynamic client registration is not possible and an error is thrown as mentioned in the following example:
{
"errorCode": "IRA-00042",
"message": "IRA-00042: Dynamic clients not allowed in the server.",
"timestamp": "2021-04-28T06:46:05.068Z[UTC]"
}
To register a dynamic client, the hostName should be given as a range in CIDR notation as mentioned in the following example:
{
"hostName": "192.168.29.244/30",
"applicationType": "radius",
"applicationName": "Radius"
}
In above example, the CIDR mentioned in the hostName (192.168.29.244/30) includes the IP address range from 192.168.29.244 to 192.168.29.247. The shared secret generated for the CIDR notation will be the shared secret for all these machines and you can use any of these machines to make a RADIUS call.
Any machine which has the IP address in the given CIDR notation range along with the generated shared secret can be used to make a RADIUS call.
2.11 Configuring Logging
Oracle RADIUS Agent logging can be configured during container start up or post Day 0 configuration.
Oracle RADIUS Agent makes use of the java.util.logging file. The log files location is configurable and is configured as part of the initial container setup. For more information, see Installing and Configuring Oracle RADIUS Agent section. The Oracle RADIUS Agent also supports setting certain custom logging properties. Log levels can be configured dynamically by calling Oracle RADIUS Agent REST APIs.
Log files are created under INSTANCE_NAME/logs
directory.
The default log names are as follows:
- ora-server0.log - contains the server logs
- ora-access0.log - contains the access logs
- ora-audit0.log - contains the audit logs
Server logs are controlled by setting the oracle.idm.radius.level
. This can be set to levels defined by java.util.logging
. The default log level is WARNING.
Access logs are controlled by setting the oracle.idm.radius.access.log.level
. Access log levels can be ON or OFF. To turn ON, set to INFO
. To turn OFF, set to any other higher logging level. Access logs are enabled by default.
Audit logs are controlled by setting the oracle.idm.radius.audit.log.level
. Audit log levels can be ON or OFF. To turn ON, set to INFO
. To turn OFF, set to any other higher logging level. Audit logs are enabled by default.
POST https://<hostname.domain>:PORT/radius-config/v1/configurations
The following is an example payload that you must pass to the preceding REST API endpoint.
{
"logging": {
"oracle.idm.radius.level": "FINEST",
"oracle.idm.radius.access.log.level": "INFO"
}
}
And the following is the corresponding response:
{
"message": "Configuration is successfully updated.",
"timestamp": "2021-03-24T15:54:57.502Z[UTC]"
}
Using External Logging Properties
You can use the external logging properties for setting additional logging related properties:
-
java.util.logging.FileHandler.limit
Logging file handler limits are controlled by setting the
java.util.logging.FileHandler.limit
. This specifies an approximate maximum amount to write (in bytes) to any one file. If this is zero then there is no limit, which is the default.
-
java.util.logging.FileHandler.count
Logging file handler count is controlled by setting the
java.util.logging.FileHandler.count
. This specifies how many output files to cycle through. The default value is 1.Note:
The parametersjava.util.logging.FileHandler.limit
andjava.util.logging.FileHandler.count
will take effect only if they are specified in customlogging.properties
passed using theOVERRIDDEN_INSTANCE_CONFIG
variable. -
Use this property to control the server logs.oracle.idm.radius.level
-
Represents the logger name for access logs and it is enabled by default. Change level of this to "SERVERE" to turn off access logging.oracle.idm.radius.access.log.level
-
Represents the logger name for audit logs. Change the level of this to "SERVERE" to turn off audit logs.oracle.idm.radius.audit.log
- You can use the
FileHandler
with theLogManager
configuration properties to control the size and count of the server log file. -
The container can be brought up with external
overriden_logging_config.properties
file by specifying it inOVERRIDDEN_INSTANCE_CONFIG
.docker run -d --network rad --name radius1 -v /home/opc/Radius:/u01/oracle/user_projects -p 8000:8080 -p 1812:1812/udp -p 1813:1813/udp -p 1814:1814 -e INSTANCE_NAME=inst1 [-e OVERRIDDEN_INSTANCE_CONFIG=/u01/oracle/user_projects/overriden_logging_config.properties] idm-imcs-sandbox.dockerhub-phx.oci.oraclecorp.com/idm-radius-server:latest
2.12 Configuration Properties
The tables below outline the possible configuration properties for Oracle RADIUS Agent.
The table below outlines the Oracle RADIUS Agent configuration properties for the
Server Configuration type: "server:"
Configuration Parameter | Description | Default Value |
---|---|---|
stateCacheEntryTimeout | State Attribute Cache's Entry Timeout | 120000 |
stateCacheConcurrencyLevel | State Attribute Cache's concurrency level | 6 |
validatedTokenCacheEntryTimeout | Validated MFA Token Cache's Entry Timeout | 60 |
validatedTokenCacheConcurrencyLevel | Validated MFA Token Cache's concurrency level | 6 |
customDictionary | Custom RADIUS dictionary file that contain definitions for vendor specific attributes | None |
customDictionaryAsStream | Custom dictionary file as stream | None |
enableDynamicClients | Indicates if dynamic clients are allowed or not. | None |
enableMetrics | Indicates if metrics is enabled. | true |
heartBeatInterval | Configured heartbeat thread invocation interval in ms to check availability of authenticator like LDAP. | 120000 |
The table below outlines the Oracle RADIUS Listener configuration properties for the
configuration type: "radiusListener:"
Configuration Parameters | Description | Default Value |
---|---|---|
channelSelectTimeout | UDP NIO channel selection timeout in ms | 120000 |
socketSOTimeout | The underlying socket SO timeout in ms. | 1800000 |
numberOfWorkerThreads | The maximum number of worker threads allowed, this maps to maximum PoolSize value for the underlying ThreadPoolExecutor of the worker threads. | 20 |
coreThreadPoolSize | CorePoolSize value for the underlying ThreadPoolExecutor of the worker threads. It is the minimum number of worker threads the underlying ThreadPoolExecutor maintains. | 10 |
threadPoolKeepAliveTime | Thread Pool Keep Alive Time in ms for the underlying ThreadPoolExecutor of the worker threads. When the thread pool more than minimum number of threads configured (coreThreadPoolSize), excess threads will be terminated if they have been idle for more than this threadPoolKeepAliveTime. This provides a means of reducing resource consumption when the thread pool is not being actively used. If the pool becomes more active later, new threads will be constructed. Value 0 means excess threads created will never be cleaned up, so it's recommended to not use 0. | 10000 |
requestCacheEntryTimeout | Request cache's entry timeout value in milliseconds | 30000 |
requestCacheConcurrencyLevel | Request Cache's concurrency level. | 6 |
requestCacheCleanupInitialDelay | Request Cache Cleanup Thread's initial delay. | 0 |
requestCacheCleanupInterval | Request cache cleanup thread's interval. | 60000 |
requestCacheCleanupPoolSize | Request Cache Cleanup Thread Pool Size. | 0 |
The table below outlines the Base Authentication configuration properties. These are applicable to the configuration type: "authentication:"
and "mfa:"
Configuration Parameter | Description | Default Value |
---|---|---|
name | Name of the configuration | Global Oracle Advanced Authentication for MFAConfig, Global Ldap for LdapConfig, Global Oracle Access Management for OAMConfig |
enabled | Flag to indicate if it is enabled | true |
retryCount |
If configured and a value > 0 indicates that the Operation will be retried for the configured number of times in case of a Connection Failure. Retry can be turned off if value = 0 |
1 |
retryInterval | When number of retries is > 1, retry interval between two retries in ms. | 0 |
The table below outlines the Primary Authenticator configuration properties for the configuration type: "authentication:"
Configuration Parameter | Description | Default Value |
---|---|---|
provider | Configured authentication provider type | LDAP |
userCacheEntryTimeout | User cache entry timeout value in ms | 300000 |
userCacheConcurrencyLevel | User cache concurrency level | 4 |
userCacheCleanupInterval | User cache cleanup interval | 300000 |
userCacheCleanupPoolSize | User cache cleanup thread pool size | 1 |
userCacheCleanupInitialDelay | UserCache clean up initial delay after which the cleanup thread will start | 0 |
ldap | LDAP configuration details | None |
The table below outlines the LDAP Authenticator configuration properties for the configuration type: "ldap:"
Configuration Parameter | Description | Default Value |
---|---|---|
ldapUrl | URL of the LDAP server. It has to be in format ldap://hostname:port(for non-SSL) or ldaps://hostname:port(for SSL) | None |
dn | The DN of user which RADIUS agent uses to connect to LDAP server | "" (anonymous bind) |
password | The password of user which RADIUS agent uses to connect to LDAP server | "" (anonymous bind) |
baseDN | The base DN of the LDAP domain that is used by RADIUS Agent for searching users and groups | "" |
loginAttr | The login attribute name in LDAP for user. This is used to construct filter to lookup user during login | uid |
userFilteringCriteria | Additional filtering criteria for looking up user, this filter when present is ANDed with filter based on loginAttr | None |
authWithoutMFACriteria | Based on this filter, matching users are allowed to login using primary factor only when user footprint is not present in MFA. | None |
trustedCertificate | Trusted certificate in Base 64 format | None |
truststore | Truststore file location in case a JKS file is used for certificates. | None |
truststorePassword | Truststore password. This is optional and needs to be provided if truststore is used instead of a trustedCertificate. | None |
trustedCertificateAliasName | Alias name to be used for referring to trusted certificate in JKS | ldap-server-trusted-cert |
keystore | Keystore file location to be used for SSL mutual authentication | None |
keystoreCertificateAliasName | Alias name used for referring to the certificate in keystore JKS | None |
keystorePassword | Password to the keystore file. | None |
keystoreTruststoreType | File type (JKS/PKCS12) when file based truststore/keystore is used. If null, it means certificate itself has been provided. | None |
keyFactorAlgorithm | Algorithm with which certificate has been signed | RSA |
sslProtocol | The cryptographic protocol RADIUS agent would use for connecting to LDAP server for secure connections. Multiple protocols can be given separated by comma. | None (Uses JVM defaults) |
cipherSuites | Default cipher suites supported out of the box | None (Uses JVM defaults) |
searchUserBeforeBind | Lookup user in LDAP server to get their DN before initiating user login. This can be disabled if LDAP server supports bind using a mapped ID directly (for example: ID mapper in OUD, UPN bind in Active Directory etc.) | true |
connectTimeout | Time limit in milliseconds within which LDAP connection has to be made | 5000 |
readTimeout | Time limit in milliseconds for which RADIUS agent will wait for LDAP server to respond back. | 30000 |
searchTimeout | Time limit in milliseconds for LDAP searches. | 30000 |
referral | Specifies the behavior when a referral is returned by LDAP server. Check JNDI java.naming.referral for possible values. | follow |
The table below outlines the LDAP Authenticator - Connection Pool configuration properties for the configuration type: "ldap:"
Configuration Parameter | Description | Default Value |
---|---|---|
initSize | This property indicates the number of connections that are created when connection pool is initialized | 5 |
minSize | The minimum number of connections the pool maintains. If initSize is less than minSize then connection pool is initialized with minSize connections. | 5 |
maxSize | The maximum number of connections the pool maintains. If minSize is greater than maxSize then minSize is set to maxSize. | 100 |
poolMaxWaitTime | Time limit in milliseconds for which client will wait for a LDAP connection to be made available | 20000 |
poolIncrementSize | Number of connections to be made at a time when all existing connections are in use and number of connections are less than maxSize | 5 |
poolMaxConnectionIdleTime | Time in milliseconds after which an idle connection is expired | 1500000 |
poolMaxConnectionReuseTime | Time in milliseconds after which a connection is expired | -1 (No time limit) |
poolMaintenanceInterval | Time interval in milliseconds when maintenance thread would run which would enforce above two properties. | 600000 |
The table below outlines the LDAP Authenticator - Connection Socket configuration properties for the configuration type: "ldap:"
Configuration Parameter | Description | Default Value |
---|---|---|
soTimeout | Defines the socket timeout in milliseconds while waiting for data. A value of 0 indicates no timeout | 0 |
soKeepAlive | Enable keep alive probes for socket connection. | true |
tcpNoDelay | Data is sent as soon as available | false |
reuseAddress | Reuse ports even when it is in TIME_WAIT state | true |
The table below outlines the LDAP Authenticator - Group Membership configuration properties for the configuration type: "ldap:"
Configuration Parameter | Description | Default Value |
---|---|---|
memberAttr | LDAP attribute name to be used for group related queries. If not specified then uniquemember and member are used. For AD we need to provide 'member' as its value for nested group searches to work. | None |
memberFilteringCriteria | Additional filtering criteria for group searches. This condition when present is ANDed with the group membership query filter. Eg: For AD we need to provide (objectclass=group) for nested group search to work. | None |
groupNamingAttribute | Naming attribute for groups in LDAP | cn |
maxNestedLevels | Maximum depth search should happen for finding out groups a given user is member of in case if nested groups are configured. (Note: this only applies to the case when group membership query constructed by Oracle RADIUS Agent, and this does not apply to memberof query) | 10 |
enableMemberOfQuery | Enable memberof searches which relies on group membership to be resolved by the backend LDAP server. OID/OUD returns nested group/dynamic groups along with direct membership while AD returns only direct membership of the user. | false |
memberOfAttribute | The attribute which returns groups a user is member of. OUD works with ismemberof, AD works with memberof while OID supports both memberof and ismemberof | memberof |
maxGroupsToFetch | Sets the maximum number of entries to be returned as a result of the search. A value of 0 indicates no limit. (Note: this only applies to the case when group membership query constructed by Oracle RADIUS Agent, and this does not apply to memberof query) | 0 |
The table below outlines the MFA - Oracle Advanced Authentication configuration properties for the configuration type: "mfa:"
Configuration Parameter | Description | Default Value |
---|---|---|
oaaUrl | Oracle Advanced Authentication Service Base URI | None |
timeToLiveInMs | Factor Token's Time To Live in MilliSecs | 300000 |
clientType | Client Type used in Oracle Advanced Authentication for RADIUS Agent | radius |
clientSecret | Client Secret in Oracle Advanced Authentication for registered agent for RADIUS Agent | None |
clientId | Client ID in Oracle Advanced Authentication for registered agent for RADIUS Agent | None |
agentgid | Agent Id in Oracle Advanced Authentication for registered RADIUS Agent | None |
connectTimeout | Oracle Advanced Authentication API Connection Timeout in Millisecs | 2000 |
readTimeout | Oracle Advanced Authentication API Read Timeout in Millisecs | 10000 |
oaaPolicyUrl | Oracle Advanced Authentication policy URL | None |
policyUserName | Oracle Advanced Authentication policy username | None |
policyUserPassword | Oracle Advanced Authentication policy password | None |
The table below outlines the Preferences configuration properties for the configuration type: "preferences:"
Configuration Parameter | Description | Default Value |
---|---|---|
returnGroups | Indicates if groups need to be returned during authentication. | false |
groupAttrID | RADIUS attribute ID for the group mapping. Groups are returned as part of this RADIUS attribute. | 1 (for Oracle) |
groupAttrVendorID | RADIUS vendor ID for the group mapping. Groups are returned as part of this RADIUS attribute. | 111 (for ORACLE_ROLE attribute) |
groupAsSingleString | Returns group details as a single string in response separated by a delimiter that is configured if it's true. | false |
groupAsSingleStringDelimiter | Delimiter used when groups are returned as single string. | , |
allowTokenInPassword | Indicates if synchronous login mode (Password, delimiter,token concatenation) is enabled/disabled. | true |
defaultTokenLength | Length of the token for synchronous login mode. This represents the token length of the DefaultSecondFactor configured. | 6 |
appendDelimiter | Delimiter used for synchronous mode ( Password+delimiter+token), for example: password;123456 | ; |
defaultSecondFactor | Default Second Factor. This Factor will be used when no preferred factor is available for the user from the User Preferences of Oracle Advanced Authentication and synchronous mode is used in the RADIUS Request. | ChallengeOMATOTP |
mfaOptions | Additional Oracle Advanced Authentication Provider specific options like "assuranceLevel", "factorChoices" (for auto-wiring of Oracle RADIUS Agent and Oracle Advanced Authentication), "defaultGroup" for setting default group name that is passed to Oracle Advanced Authentication. | {"defaultGroup" : "Default"} |
allowSpecificFactorInPassword | Indicates if directly invoking Specific Factor by enduser is enabled or not. | false |
radiusFactorToMFAFactorMap | RADIUSAgent's Factor to MFA Provider's Factor mapping. These keywords can be used to invoke a specific factor for MFA. | {"totp": "ChallengeOMATOTP", "yubikey": "ChallengeYubicoOTP", "sms": "ChallengeSMS", "mail": "ChallengeEmail"} |
userAttrMap | Represents mapping for user attributes from primary authenticator to specified RADIUS Attributes which are to be returned during authentication. | None |
groupNameMapping | Mappings to map group names in primary authenticator to different values. | None |
factorToTokenLengthMap | RADIUS Factor to factor token length mapping. | {"ChallengeOMATOTP": 6, "ChallengeYubicoOTP": 44} |
The table below outlines the Preferences - UserAttrMapping configuration properties for the configuration type: "userAttrMap:"
Configuration Parameter | Description | Default Value |
---|---|---|
vendorId | Vendor ID associated of the mapped RADIUS user attribute | None |
attrName | User attribute name in primary authenticator | None |
attrId | Attribute id of the mapped RADIUS user attribute | None |
2.13 Setting Up Load Balancing
As the Oracle RADIUS Agent Container instance is stateless, you can set up load balancing and high availability by deploying multiple Oracle RADIUS Agent instances behind a load balancer. You can start a new Oracle RADIUS Agent Container instance easily by pointing to the persisted configurations on the volume. This allows easy horizontal scaling.
Session Persistence
When deploying Oracle RADIUS Agent with a load balancer, you need to configure in the load balancer the session persistence based on the IP address of the end user. This is specifically needed since RADIUS is based on User Datagram Protocol and Multi-factor Authentication requests in RADIUS use RADIUS challenge response flow, which uses different RADIUS packets.