Use Oracle RADIUS Agent with Oracle Advanced Authentication for Multi-Factor Authentication

Introduction

This tutorial shows you how to configure Oracle RADIUS Agent using an LDAP server as the primary authenticator and Oracle Advanced Authentication (OAA) for second factor authentication.

It also shows how to configure the following common usecases:

Objectives

In this tutorial you will perform the following tasks:

  1. Install the Oracle RADIUS Agent Postman collection
  2. Configure Oracle RADIUS Agent to use an LDAP Server for primary authentication and Oracle Advanced Authentication for second factor authentication
  3. Configure an Oracle Database to use RADIUS and Multi-Factor Authentication
  4. Configure an Oracle Database to use RADIUS authorization with LDAP groups
  5. Configure SSH with the RADIUS Pluggable Authentication Module and Multi-Factor Authentication

Oracle RADIUS Agent Prerequisites

Before following this tutorial you must have:

LDAP Server Prerequisites

Before following this tutorial you must have:

In this tutorial the following directory information tree is used:

Description of the illustration dit.jpg

If using an existing LDAP Server with your own directory information tree then modify the examples in this tutorial to fit your setup.

If you do not have an LDAP Server, or would like to create one with the above directory tree for testing, then follow Appendix A: Configure an Oracle Unified Directory Docker Container in this tutorial.

Oracle Advanced Authentication Prerequisites

Before following this tutorial you must have:

Step 1: Install the Oracle RADIUS Agent REST API Postman Collection

In this section you install and configure the Oracle RADIUS Agent REST API Postman collection.

Objectives

The Oracle RADIUS Agent REST APIs provide a way to integrate Oracle RADIUS Agent with REST clients. For this tutorial a Postman collection is provided that contains common REST API calls used to configure and administer Oracle RADIUS Agent.

For more information on the Oracle RADIUS REST API endpoints see Oracle RADIUS Agent REST API Documentation

Prerequisites

In order to complete this section, you will require the following:

Set the Environment Parameters in Postman

  1. Open Postman, and select File > Import.

  2. In the Import dialog box, in the File tab, select Upload Files. Choose the Oracle_Radius_Agent_Example_Environment.postman_environment.json , and then click Open.

  3. In the left hand menu click Environments Environments.

  4. In the environment list displayed, to the right of the Oracle RADIUS Agent Example Environment, click the elipsis and then Duplicate:

    Description of the illustration duplicate_env.jpg

  5. On Oracle RADIUS Agent Example Environment Copy, which appears above the original environment, click the elipsis and rename to Oracle RADIUS Agent Environment for REST APIs.

  6. To update the environment variables, enter the following values for Initial Value and Current Value, then click Save:

    • radius-host: Oracle RADIUS Agent hostname, for example https://radius.example.com
    • radius-port: Oracle RADIUS Agent administration port, for example 8000. The port should be set to the port that maps to 8080 in docker ps.
    • USERNAME: <username>: where <username> is the administrator username stored in LDAP e.g radadmin1
    • PASSWORD: <password>: where <password> is the administrator’s password

    For example:

    Description of the illustration environment.jpg

  7. Click the Environment drop-down list, and then select the updated environment from the list:

    Description of the illustration environment_selection.jpg

Import the Postman Collection

  1. To import the Oracle RADIUS Agent REST API Postman collection, on the Postman main page, select File > Import.

  2. In the Import dialog box, in the File tab, select Upload Files. Choose the file Oracle_Radius_Agent_REST_API.postman_collection.json, and then click Open and then Import.

  3. Click on Collections in the left hand menu. The collection should display as follows:

    Description of the illustration collections.jpg

    Note : To prevent SSL certificate verifcation errors, navigate to File > Settings, and in the General tab set SSL certificate verification to OFF.

Step 2: Configure Oracle RADIUS Agent

In this section you configure the Oracle RADIUS Agent.

Objectives

To configure Oracle RADIUS Agent to use an LDAP sever as a primary authenticator and OAA for Multi-Factor Authentication.

Run the Day0 Configuration

  1. In the Oracle RADIUS Agent REST API Postman collection navigate to RADIUS Configuration > Create Day 0 Config with OAA

  2. Click on the Body tab. Edit the following parameters and set values that correspond to your LDAP and OAA servers:

    • radiusAdminGroup: The DN of the radiusAdminGroup(s) configured in the LDAP Server e.g: cn=radiusAdmin,ou=groups,dc=example,dc=com
    • radiusAdminUser: The DN of the radiusAdminUser(s) configured in the LDAP Server e.g: uid=radadmin1,ou=people,dc=example,dc=com
    • dn: The LDAP Server Administrator e.g: cn=Directory Manager
    • password: The password for the LDAP Server Administrator
    • ldapUrl: The URL of the LDAP Server e.g: ldaps://myoudds:1636
    • baseDN : The base DN for the LDAP Server e.g: dc=example,dc=com
    • trustedCertificate: The base64 trusted CA certificate of the LDAP Server (or SSL certificate if self-signed). Paste the contents of your certificate in between -----BEGIN CERTIFICATE-----\n and \n-----END CERTIFICATE-----
    • oaaURL: The OAA runtime URL e.g: https://oaa.example.com/oaa/runtime
    • oaaPolicyUrl: The OAA policy URL e.g: https://oaa.example.com/oaa-policy
    • policyUserName: The policy username from OAA in the format of RELEASENAME-oaa-policy e.g: oaa-release-87cdd4cb-oaa-policy
    • policyUserPassword: The oaapolicyapikey from OAA e.g: eb3188094918b1bc8e4fd584e8c27f8e7f3fe338
    • factorChoices: Specify the factors you want to allow for the OAA policy created. Factors available include ChallengeEmail, ChallengeOMATOTP, ChallengeSMS, ChallengeYubicoOTP e.g: factorChoices: ["ChallengeEmail","ChallengeOMATOTP","ChallengeSMS"]
    • defaultGroup: The value of the group where the users exist in OAA e.g Default

    Note: Prior to copying the certificate contents, copy the certificate into Notepad and turn Word Wrap off. Edit the contents so the main part of the certificate is on one line as follows. This will prevent SSL communication problems between Oracle RADIUS Agent and the LDAP server.

    ``` —–BEGIN CERTIFICATE—– MIICwzCCAaugAwIBAgIEGRs6/DANBgkqhkiG9w0BAQsFADASMRAwDgYDVQQDEwdteW91ZGRzMB4XDTIxMDMxOTExMDgzN1oXDTIyMDMxOTExMDgzN1owEjEQMA4GA1UEAxMHbXlvdWRkczCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKReXdli0MQDP8LAVqiNynp6rKfkXD1iToJb2kvUG90JL10+1wim1K1B5ejQZnbSb3c5t+sCl6teee2yM5y9X5Sx2g2V+gSvcgi509WvdB4IrexlE0f0lt0uc9RKwj7e7KK2eKRnmd6MqGRmsST0tS5LKRzAWQFN8hr27tMSDTPiYQW5qiSfGtEje5Yse8llL9Nsz/MRKZByx5OJSLoMx3hhh8vA2vP+bAWMqAtjndc/0i0Ax0JPu1DHn79m69sxHzhMHHEdFnIJD9iVZmXfgW1kOdK4MUa6AiGuZwA5NhiQzhGoONztExh23nTFhjVK7f8RlVv2okHeS+gtg8KW7wsCAwEAAaMhMB8wHQYDVR0OBBYEFKGBx/YKBK5AMyYLj3c68caGHjm2MA0GCSqGSIb3DQEBCwUAA4IBAQAcbAq95EM25WYqBm5qg6b6L2VM/g10SEAtD6nFiNdmwKvv9UzDmytDETHUZ/pD3mv92wpARUX1+6w9rD12Pz3ZZD9j4c9pllt1cc6camISbX//y359d/fanHO2hUBQ3u9SHaBOBmJzYdvGIQYNHHoqSKpLSoQ4StPIy+t+fLBfvvTVmJEpdehSSTvnbbVXULGn8nRrbl/i8LxTHiMbYpO7+Co/YPFpxQZofbKr5ToiIdnYSqRgPnRC74JF9OslXhBd+hyxKPqbE9787nXf3ACl3jMNJ6TWhX9NSSN1XwcdBi6ZfzKkxUWyT4jvtQXks8GHmmn4Yy5jGGMpSET3bEgW —–END CERTIFICATE—–

    Note: As an alternative to passing the base64 certificate with trustedCertificate you can specify the location of a Java Key Store (JKS) that contains this certificate. The JKS file must be located in the directory that maps to /u01/oracle/user_projects when the container was started (e.g: -v /scratch/radius/user_projects:/u01/oracle/user_projects). If you prefer to use a JKS file then pass the following parameters instead of trustedCertificate:

    • "truststore": "<path>" The path to the JKS e.g /u01/oracle/user_projects/keystore
    • "keystoreTruststoreType": "JKS",
    • "trustedCertificateAliasName": "<alias>" where <alias> is the name of assigned to the certificate in the JKS
    • "truststorePassword": "<password>" where <password> is the truststore password for the JKS

    In the example below trustedCertificate is used. If not connecting to the LDAP server via SSL, certificate related parameters can be removed.

    Description of the illustration day0mfaconfig.jpg

    Note: The above registers the Oracle RADIUS Agent as an Agent in OAA and creates an associated Assurance Level and Policy in one operation. The names assigned to the Agent, Assurance Level and Policy are assigned by OAA. If you prefer to register to create your own named Agent, Assurance Level and Policy individually, then refer to Configuring Oracle Advanced Authentication. If you do choose to do this then remove oaaPolicyUrl, policyUserName and policyUserPassword parameters above and pass oaaURL, and the clientId and clientSecret for the RADIUS Agent created. Refer to the mfa parameters in Configuration Properties for more details.

  3. Click Send

  4. If successful you will see a 200 OK response and results similar to the following:

    Description of the illustration day0configsuccess.jpg

Test a RADIUS Client Connection

  1. Install a RADIUS Test client utility of your choice and note the IP address where this client is installed. Note: The RADIUS Test client must support Multi-Factor Authentication.

    Note: If you do not have a test client utility, see Doc ID 2787492.1 on My Oracle Support

  2. In the Oracle RADIUS Agent REST API Postman collection, navigate to RADIUS Client Administration > Register RADIUS Client.

  3. In the Body tab change the parameters as follows and click Send:

    • applicationName: MyRadiusTestClient
    • hostName: <ipaddress> or hostname where the RADIUS test client is installed
    • applicationType: RadiusClient
    • description: MyRadiusTestClient

    Description of the illustration registerclient.jpg

  4. If successful you will see a 200 OK response. The sharedSecret for the registered client is returned in the response. Make a note of the sharedSecret as this is required to configure the RADIUS Test Client utility:

    Description of the illustration registerclientresponse.jpg

    Note: If you lose the sharedSecret there is no way to retrieve this later. If the sharedSecret is lost then a PATCH operation can be used to generate a new secret for the client. See Reset Client Shared Secret in the Postman collection.

  5. Configure your RADIUS Test Client utility and test a connection. To use the RADIUS Test Client you will need the sharedSecret returned above, the Oracle RADIUS Agent hostname and the Authentication port e.g 1812. Once the RADIUS Test Client utility is configured, enter a username and password for a user stored in the LDAP server. When asked for a challenge choice enter an option of your choice (e.g Email Challenge) and enter the One Time Passcode (OTP) sent in the email. If the connection is successful the Oracle RADIUS Agent is configured successfully.

Usecase 1: Configure an Oracle Database for use with Oracle RADIUS Agent and Oracle Advanced Authentication

In this section you configure an Oracle Database to perform multi-factor authentication with the Oracle RADIUS Agent and Oracle Advanced Authentication (OAA).

Objectives

To configure an Oracle Database as a RADIUS client to enable an Oracle client to login with multi-factor authentication via RADIUS. In this tutorial the Challenge-Response Authentication mode is used.

Description of the illustration dbradiusoaa.jpg

Prerequisites

In order to complete this section, you will require the following:

For the purposes of this tutorial an Oracle 19.3 Database is used on Oracle Enterprise Linux. The database and listener are started with the listener on 1521.

Register the Oracle Database as a RADIUS Client

  1. In the Oracle RADIUS Agent REST API Postman collection, navigate to RADIUS Client Administration > Register RADIUS Client.

  2. In the Body tab change the parameters as follows and click Send:

    • applicationName: MyDatabase19cClient
    • hostName: <ipaddress> or hostname where the Oracle Database is installed
    • applicationType: Oracle
    • description: MyDatabase19cClient

    For example:

    Description of the illustration registerdbclient.jpg

  3. If successful you will see a 200 OK response. The sharedSecret for the registered database client is returned in the response. Make a note of the sharedSecret as this is required to configure the Oracle Database:

    Description of the illustration registerdbclientresponse.jpg

    Note: If you lose the sharedSecret there is no way to retrieve this later. If the sharedSecret is lost then a PATCH operation can be used to generate a new secret for the client. See Reset Client Shared Secret in the Postman collection.

Set LD_LIBRARY_PATH

  1. On the database server set the LD_LIBRARY_PATH as follows:

    export LD_LIBRARY_PATH=$ORACLE_HOME/jdk/jre/lib/amd64/server:/usr/lib:$ORACLE_HOME/rdbms/lib:$ORACLE_HOME/jdbc/lib:$LD_LIBRARY_PATH

Configure the Oracle Database

  1. On the Database server create a $ORACLE_HOME/network/security directory. In this directory create a radius.key file and add the sharedSecret returned in the previous step. For example:

    $ cat $ORACLE_HOME/network/security/radius.key
YeKa04z8y_U

  2. For security purposes change the file permission of radius.key to read only, accessible by the Oracle owner.

  3. Edit the $ORACLE_HOME/network/admin/sqlnet.ora and set the parameters as follows:

    NAMES.DIRECTORY_PATH= (TNSNAMES, EZCONNECT)
SQLNET.AUTHENTICATION_SERVICES=(BEQ,TCPS,RADIUS)
SQLNET.RADIUS_CHALLENGE_RESPONSE = ON
SQLNET.RADIUS_AUTHENTICATION=radius.example.com
SQLNET.RADIUS_AUTHENTICATION_PORT=1812
SQLNET.RADIUS_SECRET=/u01/oracle/product/db/19.3/network/security/radius.key
SQLNET.RADIUS_AUTHENTICATION_TIMEOUT = 60
SQLNET.RADIUS_AUTHENTICATION_RETRIES = 3
SQLNET.RADIUS_AUTHENTICATION_INTERFACE = oracle/net/radius/DefaultRadiusInterface
SQLNET.RADIUS_CLASSPATH=/u01/oracle/product/db/19.3/network/jlib/netradius8.jar:/u01/oracle/product/db/19.3/jdk/jre/lib:/u01/oracle/product/db/19.3/lib:/u01/oracle/product/db/19.3/jdk/jre/lib/amd64:/u01/oracle/product/db/19.3/jdk/jre/lib/amd64/server

    where:

    • SQLNET.RADIUS_AUTHENTICATION : is the hostname of the Oracle RADIUS Agent
    • SQLNET.RADIUS_AUTHENTICATION_PORT : is the authentication port of the Oracle RADIUS Agent e.g: 1812
    • SQLNET.RADIUS_SECRET: is the PATH to the $ORACLE_HOME/network/security/radius.key
    • SQLNET.RADIUS_CLASSPATH: is the CLASSPATH to the files required for RADIUS. In the above example change /u01/oracle/product/db/19.3 to the $ORACLE_HOME path for your database.

  4. Connect in sqlplus as SYSDBA and set os_authent_prefix='':

    $ sqlplus sys/<password> as sysdba
SQL> alter system set os_authent_prefix='' scope=spfile;

System altered

  5. Restart the database and listener to pick up the changes:

    SQL> shutdown immediate
SQL> exit
$
$ lsnrctl stop
$ lsnrctl start
$ sqlplus sys/<password> as sysdba
SQL> startup

  6. Create users in the database for whom you wish to authenticate via RADIUS. The users created must exist in the LDAP server. For example:

    SQL> create user user1 identified externally;
SQL> create user user2 identified externally;
SQL> create user user3 identified externally;
SQL> grant create session to user1;
SQL> grant create session to user2;
SQL> grant create session to user3;
SQL> exit

  7. Test a connection to the database via RADIUS:

    $ sqlplus /@<tnsalias>

  8. When the Oracle - Login window appears enter the Username and Password for the user and click OK. Note: The window may appear behind the active terminal window:

    Description of the illustration dblogin.jpg

  9. If first factor authentication is successful you should be prompted with an Oracle - Challenge window where you select your preferred second factor option. In this example the user chooses 1. Email Challenge, enters 1 in the Response field and clicks OK.

    Description of the illustration challenge.jpg

  10. In the Oracle - Challenge window you will be asked to Enter OTP from Device. Enter the OTP code received in the email in the Response field and click OK.

    Description of the illustration otp.jpg

    The login should be successful:

    Description of the illustration dbloginsuccess.jpg

  11. Exit SQL*Plus and repeat steps 7-10 with user2 and user3 if required.

Usecase 2: Configure an Oracle Database for RADIUS Authorization with Oracle RADIUS Agent

In this section you configure an Oracle Database to perform authorization by mapping Oracle Database roles to LDAP Groups in Oracle RADIUS Agent.

Objectives

In this tutorial you configure the sample HR schema and then grant:

Prerequisites

In order to complete this section, you will require the following:

Create Database Users and Roles

  1. Connect in SQL*Plus as SYSDBA and set OS_ROLES=TRUE:

    sqlplus sys/<password> as sysdba
SQL> alter system set OS_ROLES=TRUE scope=spfile;
   
System altered

  2. Create the employees_role as follows:

    SQL> create role employees_role;
   
Role created.

  3. Grant select on the hr.employees table to employees_role:

    SQL> grant select on hr.employees to employees_role;
   
Grant succeeded.

  4. Create the employees_admin_role as follows:

    SQL> create role employees_admin_role;

Role created.

  5. Grant full access on the hr.employees table to employees_admin_role:

    SQL> grant select, insert, update, delete on hr.employees to employees_admin_role;
   
Grant succeeded.

  6. Grant full access on the hr.jobs table to employees_admin_role:

    SQL> grant select, insert, update, delete on hr.jobs to employees_admin_role;

Grant succeeded.

  7. Restart the database.

Update Oracle RADIUS Agent Configuration to map roles to LDAP groups.

  1. In the Oracle RADIUS Agent REST API Postman collection navigate to RADIUS Configuration > Update Global Configuration.

  2. Click on the Body tab. Set the mfaOptions to the same as the Create Day0 Config with OAA. Set the following parameters and values as follows:

    • "returnGroups" : true - this tells Oracle RADIUS Agent to return groups for a user
    • "employees_group" : "ORA_<DB_SERVICENAME>_employees_role_D" - Change <DB_SERVICENAME> to the Service Name of your database e.g: “ORA_db19c.example.com_employees_role_D”
    • "admins_group" : "ORA_<DB_SERVICENAME>_employees_admin_role_D" - Change <DB_SERVICENAME> to the Service Name of your database e.g: “ORA_db19c.example.com_employees_admin_role_D”

    The "groupNameMapping" section tells Oracle RADIUS Agent to map the "employees_group" from LDAP to the employees_role in the database via "ORA_db19c.example.com_employees_role_D". This follows the format: ORA_<DB_SERVICENAME_rolename[_[A]|[D]] required by the database.

    Description of the illustration updateconfig.jpg

  3. Click Send.

  4. If successful you will see a 200 OK response and results similar to the following:

    Description of the illustration updateconfigsuccess.jpg

    Note: As explained previously, the configuration in this section is based on mapping existing LDAP groups cn=employees,ou=groups,dc=example,dc=com and cn=admin,ou=groups,dc=example,dc=com to the database roles. If you would rather create new LDAP groups instead of mapping to existing ones, then create groups in LDAP in the following format: cn=ORA_<DB_SERVICENAME>_employees_role_D,ou=Groups,dc=example,dc=com and cn=ORA_<DB_SERVICENAME>_employees_admin_role_D,ou=Groups,dc=example,dc=com. In the postman request Create Global Configuration remove the "groupNameMapping" section as the mapping is not required.

Test the Configuration

  1. Test a connection to the database via RADIUS:

    $ sqlplus /@<tnsalias>

  2. When the Oracle - Login window appears enter the Username and Password for the user and click OK. Note: The window may appear behind the active terminal window:

    Description of the illustration dblogin.jpg

  3. If first factor authentication is successful you should be prompted with an Oracle - Challenge window where you select your preferred second factor option. In this example the user chooses 1. Email Challenge, enters 1 in the Response field and clicks OK.

    Description of the illustration challenge.jpg

  4. In the Oracle - Challenge window you will be asked to Enter OTP from Device. Enter the OTP code received in the email in the Response field and click OK.

    Description of the illustration otp.jpg

    The login should be successful:

    Description of the illustration dbloginsuccess.jpg

  5. Run the following command to show that user1, which is a member of the LDAP group cn=employees_group,ou=Groups,dc=example,dc=com, has access to the employees_role only:

    SQL> select * from user_role_privs;
   
USERNAME	               GRANTED_ROLE		      ADM DEL DEF OS_ COM INH
------------------------------ ------------------------------ --- --- --- --- --- ---
USER1			       EMPLOYEES_ROLE		      NO  YES YES NO  NO

  6. Run the following to show that user1 can select from the hr.employees table as defined by the employees_role:

    SQL> select * from hr.employees;

EMPLOYEE_ID FIRST_NAME		 LAST_NAME		   EMAIL		     PHONE_NUMBER	  HIRE_DATE JOB_ID     SALARY     COMMISSION_PCT MANAGER_ID DEPARTMENT_ID
----------- -------------------- ------------------------- ------------------------- -------------------- --------- ---------- ---------- -------------- ---------- -------------
        100 Steven		 King			   SKING		     515.123.4567	  17-JUN-03 AD_PRES	    24000				       90
        101 Neena		 Kochhar		   NKOCHHAR		     515.123.4568	  21-SEP-05 AD_VP	    17000		        100	       90
        102 Lex 		 De Haan		   LDEHAAN                   515.123.4569	  13-JAN-01 AD_VP	    17000		        100	       90
        103 Alexander	         Hunold 		   AHUNOLD		     590.423.4567	  03-JAN-06 IT_PROG	     9000		        102	       60
        104 Bruce		 Ernst			   BERNST		     590.423.4568	  21-MAY-07 IT_PROG	     6000		        103	       60
etc....

  7. Run the following to show that user1 cannot select from the hr.jobs table as they do not have the employees_admin_role assigned:

    SQL> select * from hr.jobs;
select * from hr.jobs
                 *
ERROR at line 1:
ORA-00942: table or view does not exist

  8. Exit SQL*Plus.

  9. Connect again via SQL*Plus but this time connect with user3. Once connected, run the following command to show that user3, which is a member of the LDAP group cn=employees_group,ou=Groups,dc=example,dc=com, has access to the employees_admin_role only.

    SQL> select * from user_role_privs;

USERNAME	               GRANTED_ROLE		      ADM DEL DEF OS_ COM INH
------------------------------ ------------------------------ --- --- --- --- --- ---
USER3			       EMPLOYEES_ADMIN_ROLE           NO  YES YES NO  NO

  10. Run the following to show that user3 can select from the hr.employees table as defined by the employees_admin_role:

    SQL> select * from hr.employees;

EMPLOYEE_ID FIRST_NAME		 LAST_NAME		   EMAIL		     PHONE_NUMBER	  HIRE_DATE JOB_ID     SALARY     COMMISSION_PCT MANAGER_ID DEPARTMENT_ID
----------- -------------------- ------------------------- ------------------------- -------------------- --------- ---------- ---------- -------------- ---------- -------------
        100 Steven		 King			   SKING		     515.123.4567	  17-JUN-03 AD_PRES	    24000				       90
        101 Neena		 Kochhar		   NKOCHHAR		     515.123.4568	  21-SEP-05 AD_VP	    17000		        100	       90
        102 Lex 		 De Haan		   LDEHAAN                   515.123.4569	  13-JAN-01 AD_VP	    17000		        100	       90
        103 Alexander	         Hunold 		   AHUNOLD		     590.423.4567	  03-JAN-06 IT_PROG	     9000		        102	       60
        104 Bruce		 Ernst			   BERNST		     590.423.4568	  21-MAY-07 IT_PROG	     6000		        103	       60
etc....

  11. Run the following to show that user3 can select from the hr.jobs table as defined by the employees_admin_role:

    SQL> select * from hr.jobs;

JOB_ID	   JOB_TITLE			       MIN_SALARY MAX_SALARY
---------- ----------------------------------- ---------- ----------
AD_PRES    President				    20080      40000
AD_VP	   Administration Vice President	    15000      30000
AD_ASST    Administration Assistant		     3000	6000
FI_MGR	   Finance Manager			     8200      16000
FI_ACCOUNT Accountant				     4200	9000
AC_MGR	   Accounting Manager			     8200      16000
AC_ACCOUNT Public Accountant			     4200	9000
SA_MAN	   Sales Manager			    10000      20080
etc..

Usecase 3: Configure SSH integration with Oracle RADIUS Agent and Oracle Advanced Authentication

In this section you configure the RADIUS Pluggable Authentication Module (PAM) to allow SSH integration with Oracle RADIUS Agent and multi-factor authentication via Oracle Advanced Authentication (OAA).

Objectives

An organization may have large numbers of Linux servers, making management of users, for example creating, modifying, or deleting users, a time intensive and costly activity. With the RADIUS PAM you can manage Linux users centrally in your LDAP Server and authenticate via the Oracle RADIUS Agent, providing cost and time savings.

Linux administrators can utilize Oracle RADIUS Agent to authenticate end users. End users can log in to a Linux server, for example with SSH, and authenticate with their LDAP user credentials. With Oracle RADIUS Agent integrated with OAA, Linux users can login with multi-factor authentication.

Description of the illustration pamradiusoaa.jpg

Prerequisites

In order to complete this section, you will require the following:

For the purposes of this tutorial an Oracle Linux 7 64bit server is used.

Register the Linux server as a RADIUS Client

  1. In the Oracle RADIUS Agent Postman collection, navigate to Register Client Shared Secret.

  2. In the Body tab change the parameters as follows and click Send:

    • applicationName: MySSHClient
    • hostName: <ipaddress> or hostname of the Linux Server where PAM is to be installed
    • applicationType: SSH
    • description: MySSHClient

    For example:

    Description of the illustration registerlinuxclient.jpg

  3. If successful you will see a 200 OK response. The sharedSecret for the registered Linux client is returned in the response. Make a note of the sharedSecret as this is required to configure the RADIUS PAM:

    Description of the illustration registerlinuxclientresponse.jpg

    Note: If you lose the sharedSecret there is no way to retrieve this later. If the sharedSecret is lost then a PATCH operation can be used to generate a new secret for the client. See Reset Client Shared Secret in the Postman collection.

Install PAM

  1. On the Linux server where PAM is to be installed, clone PAM RADIUS from the GitHub repository into a directory of your choice:

    $ cd <work_directory>
$ git clone https://github.com/FreeRADIUS/pam_radius

  2. As the root user, install the dependant libraries:

    $ yum install gcc pam pam-devel make -y

  3. As the root user, install pam_radius:

    $ cd <work_directory>/pam_radius
$ ./configure
$ make
$ cp pam_radius_auth.so /lib64/security/

Configure PAM

All the commands below should be executed as the root user.

  1. Edit the /etc/ssh/sshd_config, set the following parameters and save the file:

    ChallengeResponseAuthentication yes
#ChallengeResponseAuthentication no
   
#UsePAM no
UsePAM yes

  2. For any user whom you wish to authenticate via RADIUS, the corresponding user must have a user $HOME directory on the OS. If the user already exists on the OS then the user $HOME dir will already exist. For users who do not exist in the OS, create the user using the following command:

    $ useradd -m <username>

    For example:

    $ useradd -m user1

  3. Edit the /etc/pam.d/sshd as follows and save the file:

    #%PAM-1.0
auth required pam_sepermit.so
auth sufficient pam_radius_auth.so debug
#auth substack password-auth
password include password-auth
auth include postlogin
# Used with polkit to reauthorize users in remote sessions
-auth optional pam_reauthorize.so prepare
account required pam_nologin.so
account include password-auth
#password include password-auth
# pam_selinux.so close should be the first session rule
session required pam_selinux.so close
session required pam_loginuid.so
# pam_selinux.so open should only be followed by sessions to be executed in the user context
session required pam_selinux.so open env_params
session required pam_namespace.so
session optional pam_keyinit.so force revoke
session include password-auth
session include postlogin
# Used with polkit to reauthorize users in remote sessions
-session optional pam_reauthorize.so prepare

  4. Create the following directory if it doesn’t exist:

    mkdir /etc/raddb

  5. Create the file /etc/raddb/server and define the Oracle RADIUS Agent connection details and shared secret generated when registering the SSH client earlier.

    # pam_radius_auth configuration file. Copy to: /etc/pam_radius.conf
#
# For proper security, this file SHOULD have permissions 0600,
# that is readable by root, and NO ONE else. If anyone other than
# root can read this file, then they can spoof responses from the server!
#
# There are 3 fields per line in this file. There may be multiple
# lines. Blank lines or lines beginning with '#' are treated as
# comments, and are ignored. The fields are:
#
# server[:port] secret [timeout]
#
# the port name or number is optional. The default port name is
# "radius", and is looked up from /etc/services The timeout field is
# optional. The default timeout is 3 seconds.
#
# If multiple RADIUS server lines exist, they are tried in order. The
# first server to return success or failure causes the module to return
# success or failure. Only if a server fails to response is it skipped,
# and the next server in turn is used.
#
# The timeout field controls how many seconds the module waits before
# deciding that the server has failed to respond.
#
# server[:port] shared_secret timeout (s)
#127.0.0.1 secret 1
#
#<Oracle_RADIUS_Agent>:<Authentication_port>  <sharedSecret>  <timeout>
radius.example.com:9023 mRvzEtEd01 60

    Where:

    • <Oracle_RADIUS_Agent>: is the hostname or IP address of the Oracle RADIUS Agent e.g radius.example.com
    • <Authentication_port>: is the authentication port of the Oracle RADIUS Agent e.g 9023 (where 9023 -> 1812 in docker ps)
    • <sharedSecret>: is the sharedSecret returned when registering the Linux client earlier e.g mRvzEtEd01
    • <timeout> is the timeout in seconds

  6. Restart sshd to pick up the changes:

    $ systemctl restart sshd

Test a Login via SSH

  1. From any Linux server make an SSH connection to the Linux server where PAM RADIUS is configured. Enter the password when prompted:

    $ ssh user1@<linux_pam_radius_hostname>

    For example:

    Description of the illustration sshlogin.jpg

  2. If password authentication with the Oracle RADIUS Agent is successful, you will be asked to enter your challenge choice for second factor authentication. In this example we choose 1. Email Challenge by entering the value 1 at the prompt:

    Description of the illustration sshchallenge.jpg

  3. When challenged to Enter OTP sent to…, enter the one time passcode received in the email:

    Description of the illustration sshotp.jpg

    The login should be successful:

    Description of the illustration sshloginsuccess.jpg

Appendix A: Configure an Oracle Unified Directory Docker Container

In this appendix you create and configure an Oracle Unified Directory (OUD) Docker container with a sample LDIF file that replicates the directory tree used in this tutorial. Create this container on the same server where the Oracle RADIUS Agent container is running.

Install the Oracle Unified Directory Docker image

  1. Access the Oracle Container Registry and navigate to Middleware -> oud.

  2. Install the Oracle Unified Directory Docker image by following the Installing the OUD Pre-built Docker Image section only.

  3. Create a directory for the container to map to a local drive. For example:

    $ mkdir -p /scratch/OUD/user_projects
$ chmod 777 /scratch/OUD/user_projects

Generate a self-signed certificate

  1. Run the following command to generate a keystore with a self-signed certificate for use with OUD. Change <password> to a value of your choice:

    $ keytool -genkey -alias selfsigned -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -dname "CN=myoudds" -keypass <password> -keystore /scratch/OUD/user_projects/keystore -storepass <password> -validity 365

    Ignore the following message if it appears:

    Warning:
The JKS keystore uses a proprietary format. It is recommended to migrate to PKCS12 which is an industry standard format using "keytool -importkeystore -srckeystore /scratch/OUD/user_projects/keystore -destkeystore /scratch/OUD/user_projects/keystore -deststoretype pkcs12".

  2. Create a keystore.pwd file as follows. Change <password> to the value entered in the last step:

    $ echo -e <password> > /scratch/OUD/user_projects/keystore.pwd

  3. Export the certificate from the keystore:

    $ keytool -export -alias selfsigned -file /scratch/OUD/user_projects/oudserver.cer -keystore /scratch/OUD/user_projects/keystore -storepass <password>

    The output will look similar to the following:

    Certificate stored in file </scratch/OUD/user_projects/oudserver.cer>

  4. Convert the certificate from DER to PEM format.

    $ openssl x509 -inform der -in /scratch/OUD/user_projects/oudserver.cer -out /scratch/OUD/user_projects/oudserverb64.cer

    The oudserverb64.cer certificate is required when configuring Oracle RADIUS Agent.

    Note: Edit the oudserverb64.cer and change it so the certificate is in the following format with no carriage returns. This is so you can copy it into the Oracle RADIUS Agent Day0 Config later and prevent SSL communication problems between Oracle RADIUS Agent and the LDAP server.

    -----BEGIN CERTIFICATE-----
MIICwzCCAaugAwIBAgIEGRs6/DANBgkqhkiG9w0BAQsFADASMRAwDgYDVQQDEwdteW91ZGRzMB4XDTIxMDMxOTExMDgzN1oXDTIyMDMxOTExMDgzN1owEjEQMA4GA1UEAxMHbXlvdWRkczCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKReXdli0MQDP8LAVqiNynp6rKfkXD1iToJb2kvUG90JL10+1wim1K1B5ejQZnbSb3c5t+sCl6teee2yM5y9X5Sx2g2V+gSvcgi509WvdB4IrexlE0f0lt0uc9RKwj7e7KK2eKRnmd6MqGRmsST0tS5LKRzAWQFN8hr27tMSDTPiYQW5qiSfGtEje5Yse8llL9Nsz/MRKZByx5OJSLoMx3hhh8vA2vP+bAWMqAtjndc/0i0Ax0JPu1DHn79m69sxHzhMHHEdFnIJD9iVZmXfgW1kOdK4MUa6AiGuZwA5NhiQzhGoONztExh23nTFhjVK7f8RlVv2okHeS+gtg8KW7wsCAwEAAaMhMB8wHQYDVR0OBBYEFKGBx/YKBK5AMyYLj3c68caGHjm2MA0GCSqGSIb3DQEBCwUAA4IBAQAcbAq95EM25WYqBm5qg6b6L2VM/g10SEAtD6nFiNdmwKvv9UzDmytDETHUZ/pD3mv92wpARUX1+6w9rD12Pz3ZZD9j4c9pllt1cc6camISbX//y359d/fanHO2hUBQ3u9SHaBOBmJzYdvGIQYNHHoqSKpLSoQ4StPIy+t+fLBfvvTVmJEpdehSSTvnbbVXULGn8nRrbl/i8LxTHiMbYpO7+Co/YPFpxQZofbKr5ToiIdnYSqRgPnRC74JF9OslXhBd+hyxKPqbE9787nXf3ACl3jMNJ6TWhX9NSSN1XwcdBi6ZfzKkxUWyT4jvtQXks8GHmmn4Yy5jGGMpSET3bEgW
-----END CERTIFICATE-----

Create the Oracle Unified Directory Docker Container

  1. Download the dit.ldif and copy to the /scratch/OUD/user_projects directory.

  2. Edit the dit.ldif and change all instances of pwd in the attributes userPassword: pwd to a password of your choice. Take care not add extra space characters to the end of the password when editing it.

  3. If a network bridge does not already exist, create one with the following command:

    docker network create -d bridge <name>

    For example:

    docker network create -d bridge rad

    Note: The name of the network must be the same one used when starting Oracle RADIUS Agent

  4. Run the following command to create the container:

    docker run -d --network=rad \
--name=myoudds \
--volume /scratch/OUD/user_projects:/u01/oracle/user_projects \
--env OUD_INSTANCE_NAME=myoudds \
--env hostname=myoudds \
--env baseDN="dc=example,dc=com" \
--env rootUserDN="cn=Directory Manager" \
--env rootUserPassword="<pwd>" \
--env useJavaKeystore="/u01/oracle/user_projects/keystore" \
--env keyStorePasswordFile="/u01/oracle/user_projects/keystore.pwd" \
--env generateSelfSignedCertificate="false" \
--env ldifFile_1="/u01/oracle/user_projects/dit.ldif" \
container-registry.oracle.com/middleware/oud:12.2.1.4.0

    In the above example:

    • -d starts the container detached as a background process
    • --name is the name given to the docker container once started
    • --network should be the same network that was used when creating the Oracle RADIUS Agent container. Remove this parameter if --network was not used to create the Oracle RADIUS Agent container.
    • --volume maps the /scratch/OUD/user_projects directory on the host environment to the /u01/oracle/user_projects directory in the container.
    • --env OUD_INSTANCE_NAME is the name of the OUD instance name to create
    • --env hostname is the hostname to assign the OUD instance (Note: it is best to make this value the same as the one passed in the --name parameter for easier communication between containers)
    • --env baseDN="dc=example,dc=com" is the base DN you want to create in the OUD Directory Server.
    • --env rootUserDN="cn=Directory Manager" is manadatory otherwise the container will fail to start
    • --env rootUserPassword="<pwd>" is the password to set. Change to a value of your choice.
    • --env useJavaKeystore="/u01/oracle/user_projects/keystore" is the path to the keystore you created earlier
    • --env keyStorePasswordFile="/u01/oracle/user_projects/keystore.pwd is the path to the keystore.pwd file created earlier
    • --env generateSelfSignedCertificate="false" needs to be set to false as you are using your own self-signed certificate
    • --env ldifFile_1="/u01/oracle/user_projects/dit.ldif" lists the path to the ldif file to import.

    Note for any file referenced above, the path is set to /u01/oracle/user_projects/ because of the --volume mapping i.e. /u01/oracle/user_projects maps to /scratch/OUD/user_projects.

  5. After a minute run the following command and make sure the container shows healthy:

    $ docker ps
CONTAINER ID IMAGE                                                     COMMAND                  CREATED               STATUS                       PORTS   NAMES
9402bbe46d85  container-registry.oracle.com/middleware/oud:12.2.1.4.0  "sh -c ${SCRIPT_DIR}…"   About a minute ago    Up About a minute (healthy)          myoudds

    Note: The docker container started is running on hostname myoudds with ldap port 1389 and ldaps port 1636. This information will be required when setting up Oracle RADIUS Agent.

  6. Run the following ldapsearch command to make sure the users and groups in the directory information tree were created:

    $ docker run -it --rm --network=rad --name=myoudclient --volume /scratch/OUD/user_projects:/u01/oracle/user_projects container-registry.oracle.com/middleware/oud:12.2.1.4.0 /u01/oracle/oud/bin/ldapsearch -h myoudds -p 1636 --useSSL -D "cn=Directory Manager" -w "<password>" -b "dc=example,dc=com" "(objectClass=*)"

    The output should look similar to the following output.txt.

    The OUD container is now ready to be used with Oracle RADIUS Agent.

Learn More

Feedback

To provide feedback on this tutorial, please contact idm_user_assistance_ww_grp@oracle.com

More Learning Resources

Explore other labs on docs.oracle.com/learn or access more free learning content on the Oracle Learning YouTube channel. Additionally, visit education.oracle.com/learning-explorer to become an Oracle Learning Explorer.

For product documentation, visit Oracle Help Center.