Installing and configuring

The installation and configuration process consists of the following steps:

  1. Specifying configuration settings
  2. Verifying the configuration settings
  3. Enabling configuration settings

Task 1: Specifying configuration settings

EC for Okta is available in a z/OSMF consumable portable software instance (PSI) format. If you are using z/OS 2.5 or a later version, you can install and configure the EC for Okta product by using z/OSMF.

To review the requirements and workflow steps for installing your PSI, see the following topics in the Installation using z/OSMF documentation portal:

Task 2: Verifying the configuration settings

Verify that your configuration settings meet your requirements without implementing any sign-on authentication requirements or without allowing or denying access to any resources. This procedure tests the following objects:

  • Subsystem initialization parameters
  • EC for Okta runtime parameters
  • Universal authentication parameters
  • Individual authentication parameters
  • Okta server connectivity
  • Okta server authentication workflow

Ultimately, an authentication request is sent to your mobile device, and the response is noted. No access is granted to any resource.

To perform the verification procedure, follow these steps:

  1. As a system administrator or a security administrator with access to RACF, define the following BMC custom data fields to RACF in the ecoktahlq.RSOSAMP(DEFCFLD) job:
    • BMCMFAID—Specifies the multifactor authentication (MFA) identifier used by the Okta Gateway to locate the mobile device for the authentication challenge.
    • BMCPWFB—Specifies the authorization action that EC for Okta should take when communication with the Okta Gateway is not possible. A password fallback of YES indicates that the RACF user ID and password validation are sufficient to allow access to the resource. A password fallback of NO indicates that MFA is required and access to the resource is denied.
    • BMCMFASS—Specifies the alternate target EC for Okta servers. Specify the EC for Okta server subsystem ID (ssid) to force a user authentication request to be processed by a specific subsystem. To select any active EC for Okta servers, specify an asterisk (*), or leave the default. 
       
  2. Dynamically initialize the EC for Okta subsystem by customizing the ecoktahlq.RSOSAMP(RSOSSINI) member to your default parameter settings and submit. The following messages are displayed in the JES message log:

    RSO0050I BMC AMI Enterprise Connector for Okta initialized. 
    ssid: xxxx
    SMF Number: xxx
    RSO0055I Successfully created general purpose 64bit cell pool
     
  3. Start the EC for Okta server. Messages similar to the following ones are displayed in the JES message log:

    RSO1002I BMC AMI Enterprise Connector for Okta 01.02.00 Z405417
    RSO1003I BMC AMI Enterprise Connector for Okta ssid(xxxx)
    + initialization complete.    
           
  4. Add the EC for Okta authentication exit routine (RSORIXEX) to the ICHRIX02 dynamic exit table and issue the following command in the z/OS operator console:

    SETPROG EXIT,ADD,EX=BMCICHRIX02DYNEX,MOD=RSORIXEX,STATE=ACTIVE,
    DELETEFORCE=YES,DSN=ecoktahlq.RSOLINK

    The following response is displayed:

    CSV420I MODULE RSORIXEX HAS BEEN ADDED TO EXIT BMCICHRIX02DYNEX
     
  5. Customize and run the installation verification batch job by customizing the ecoktahlq.RSOSAMP(RSOECIVP) job and submitting it.
    The mobile device associated with the user ID that is specified in the IVP batch job receives an authentication request. The user can allow or deny the request. The batch job and EC for Okta log reflect the response.
    A positive response is reflected in the EC for Okta log as follows:

    RSO0990I Processing authentication request for
    ?userid
    ?user name
    JOBNAME(?jobname) JOBID(J0454596) ASIDX(0319)

    RSO0999I USER ?userid access allowed by user on
    03/23/2025 at 12:50:58
    ?user name
    JOBNAME(?jobname) JOBID(J0454596) ASIDX(0319)
           
    A positive response is reflected in the batch IVP job as follows:

    RACF Status
    RETURN CODE:  0000 (Continue)
    RESPONSE CODE: 0000 (Allow)
    ABEND CODE:  x'0000'    
    A negative response will be reflected in the BMC AMI Enterprise Connector for
    Okta log as:

    RSO0990I Processing authentication request for
    ?userid
    ?user name
    JOBNAME(?jobname) JOBID(J0454596) ASIDX(0319)

    RSO0998I USER ?userid access denied by user on
    03/23/2025 at 12:50:58
    ?user name
    JOBNAME(?jobname) JOBID(J0454596) ASIDX(0319)
           
    A negative response is reflected in the batch IVP job as follows:

    RACF Status
    RETURN CODE:  0000 (Continue)
    RESPONSE CODE: 0008 (Deny)
    ABEND CODE:  x'0000'  
     
  6. To completely remove the EC for Okta test environment by using the cleanup job, follow these steps:
    1. Terminate the EC for Okta server address by using the P ssid command. For more information, see Console commands. The P ssid command issued in the z/OS operator console terminates the address space.
    2. Customize the sample JCL found in ecoktahlq.RSOSAMP(RSOSSCLN) and submit it.
      If there are any active EC for Okta servers, the cleanup job fails with an RC=8, but it disables the EC for Okta exit. The following messages are displayed in the cleanup job’s JES message log:
      RSO0033I Module RSORIXEX removed from exit list.
      RSO0036E Active Servers Found
      Jobname SSID ASIDX
      -------- ---- -----
      xxxxxxxx xxxx X0164
       

  7. Rerun the cleanup job. Messages similar to the following ones are displayed:
    RSO0033I Module RSORIXEX removed from exit list.                      
    RSO0032I Named Token Deleted                                
    RSO0031I BMC AMI Enterprise Connector for Okta beginning cleanup of defined
    subsystem ssid
    RSO0038I 64bit General Purpose Cell Pool Deleted                      
    RSO0034I ECSA Storage freed      

    Important

    The cleanup job deletes all of the defined EC for Okta subsystems and deletes the ICHRIX02 exit table (BMCICHRIX02DYNEX). The EC for Okta server no longer starts, and no authentication requests are processed.

Task 3: Enabling configuration settings

You can permanently enable the configuration by making the following system changes:

  1. Modify the following parameters in SYS1.PARMLIB:
    1. IEFSSNxx—Add the EC for Okta subsystem initialization parameter to your universal authentication defaults. For examples of the SUBSYS command, see ecoktahlq.RSOSAMP(IEFSSNxx).

    2. IEALPAxx—Add the EC for Okta load modules to the modifiable link pack area (MLPA). For examples of the INCLUDE command, see ecoktahlq.RSOSAMP(IEALPAxx).

      Important

      Do not copy the entire product library to the LPA. Copy only the modules that are listed. The VOLUME parameter is required because the Catalog Address Space (CAS) is not started when the LPA is built.

    3. PROGxx—Add the EC for Okta exit to the ICHRIX02 dynamic exit table
      For examples of the EXIT ADD command, see ecoktahlq.RSOSAMP(EXITADD). You can add this command to a PROGxx member in SYS1.PARMLIB and run it as part of your IPL process.
    4. SMFPRMxx—(Optional) Include your SMF number and subtypes for SMF to capture.

      For examples of the SYS (TYPE command, see ecoktahlq.RSOSAMP(SMFPRMxx).

  2. Modify your IPL process to start the EC for Okta server after JES is started. EC for Okta cannot run SUB=MSTR.
    Important

    An IPL is required to enable the RACF ICHRIX02 exit. The BMC ICHRIX02 exit routine must be in (M)LPA before you start RACF.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*