1. Administering Oracle Radius Agent
  2. Installing and Configuring Oracle RADIUS Agent

2 Installing and Configuring Oracle RADIUS Agent

Topics

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 default uid:gid of 14304: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 to rwxr-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 override uid:gid value at the runtime and set the directory permission to rwxr-x--. The following is a sample command to override the uid: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)
Refer to the certification documentation on Oracle Technology Network (OTN) for information about the supported installation types, platforms, operating systems, databases, JDKs, and third-party products:
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.

  1. Ensure that all the prerequisites for installing Oracle RADIUS Agent are met.

  2. Obtain the container image for Oracle RADIUS Agent.

  3. Create and start the container and then verify its health status.

  4. If you intend to use Oracle RADIUS Agent for multi-factor authentication, then ensure that you have a running instance of Oracle Advanced Authentication .

  5. Set up and validate the day-0 or initial configuration.

  6. Create global or application-specific configurations as per your requirement.

  7. Register the RADIUS client and generate a shared secret.

  8. 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

Oracle RADIUS Agent supports the Vendor Specific Attributes (VSA). The RADIUS Vendor Specific Attributes are part of RADIUS Remote Function Call and allow vendors to support their own extended custom attributes. You can define and manage the Vendor Specific Attributes by using Oracle RADIUS Agent's Vendor Specific Attribute endpoint.

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.

You can pass the following parameters as environment variables while bringing up the Oracle RADIUS Agent container:

  • 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. This logging.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 the deployment.properties file.

    Note:

    It is recommended not to manually update deployment name or any other detail in the deployment.properties file.
    For example: 
    -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.

  1. You can obtain the Oracle RADIUS Agent image either by downloading the zip file from edelivery or by pulling the image from Oracle Container Registry. If downloaded from edelivery, download the Oracle RADIUS Agent zip file from edelivery to the required directory:
    1. Unzip the Oracle RADIUS Agent zip to a directory of your choice.
    2. Load the tar file into the container registry.
      $ docker load --input <tarfile-path>
    3. Check the image exists in the container registry.
      $ docker images

    Or if using the image from Oracle Container Registry, refer to the documentation there.

  2. Tag the image according to deployment environment. 
    docker tag <image name from downloaded image>:<tag> idm-radius-server:<tag>

    Note:

    Downloaded Image Name Example: container-registry.oracle.com/middleware/ora; Tag, Example: 12.2.1.4.210423
  3. Create and start the container for Oracle RADIUS Agent by running the following command:
    $ docker run -d --network [USER_CREATED_NETWORK_NAME] --name CONTAINER_NAME -v VOLUME_MAPPING [--user UID:GID] -p HOST_CONFIG_PORT:CONTAINER_CONFIG_PORT -p HOST_RADIUS_PORT:CONTAINER_RADIUS_PORT [-p <HOST_RADIUS_PORT2:CONTAINER_RADIUS_PORT2> . . .] -e <ENV_VAR> -e INSTANCE_NAME -e DEPLOYMENT_NAME IMAGE
    In this command:

    • USER_CREATED_NETWORK_NAME is the name of the network bridge and this is only required if you want your Oracle RADIUS Agent container to communicate with other component containers on the same network bridge.

    • CONTAINER_NAME is the name of the container for Oracle RADIUS Agent.

    • VOLUME_MAPPING is the volume mapping to map a local directory to a container volume.

    • UID:GID is the overridden value of the user that will be used by the Oracle RADIUS Agent deployment. This is optional and when this is not provided, Oracle RADIUS Agent will run using default uid:gid of 14304:14304.

    • HOST_CONFIG_PORT is the port on the host to be mapped to the Oracle RADIUS Agent container configuration port. This port will be used in the endpoint URLs for all REST API calls.

    • CONTAINER_CONFIG_PORT is the Oracle RADIUS Agent container configuration port. By default, this is 8080.

    • HOST_RADIUS_PORT is the port on the host to be mapped to the RADIUS container listener port.

    • CONTAINER_RADIUS_PORT is the Oracle RADIUS Agent container listener port.

    • ENV_VAR is any general environment variable to be passed to the JVM that is running Oracle RADIUS Agent. For example, you can use this to set memory limits or language.

    • INSTANCE_NAME is the name of the Oracle RADIUS Agent instance.

    • DEPLOYMENT_NAME is the name of the Oracle RADIUS Agent deployment.

    • IMAGE is the location of the Oracle RADIUS Agent container image in your local image repository.

    The following is a sample command to override uid: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
  4. Verify the health status of the container by running the docker ps command. Ensure that the status is shown as healthy. The output for this command will be similar to the following:
    CONTAINER ID        IMAGE                                               COMMAND                  CREATED             STATUS              PORTS                                                                                                                                             NAMES
ef8be733a132        container-registry.oracle.com/middleware/ora:latest   "entrypoint.sh"          3 weeks ago         Up 3 weeks (healthy)   0.0.0.0:1812-1813->1812-1813/udp, 1814-1830/udp, 0.0.0.0:1814->1814/tcp, 0.0.0.0:8000->8080/tcp radius1

    Note:

    For more information on upgrading Oracle RADIUS Agent, see Upgrading Oracle RADIUS Agent to April 2022 Release or Later.

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 authenticationand 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.

Topics

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

authentication

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 authentication configuration type section.

mfa

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.

preferences

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.

radiusListener

Use this to specify the configuration for your Oracle RADIUS Agent listener port.

logging

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.

server

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:

For Day-0, the 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.

To configure log level for logging, make a POST request to the following REST API endpoint:
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 parameters java.util.logging.FileHandler.limit and java.util.logging.FileHandler.count will take effect only if they are specified in custom logging.properties passed using the OVERRIDDEN_INSTANCE_CONFIG variable.

  • oracle.idm.radius.level

    Use this property to control the server logs.

  • oracle.idm.radius.access.log.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.audit.log

    Represents the logger name for audit logs. Change the level of this to "SERVERE" to turn off audit logs.
  • You can use the FileHandler with the LogManager 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 in OVERRIDDEN_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.