Configuring bulk provisioning users for IBM MFA

IBM® MFA provides programs and UNIX shell scripts that you can use to provision users with policies and factors. Although you can use the RACF® commands for this purpose, the bulk provisioning feature is more efficient if you have a large number of users.

Before you begin

Important:
  • You need to have UPDATE access to the system security manager FACILITY class profile IRR.RFACTOR.USER to update the user factor data. Use the PERMIT command to grant UPDATE access to the profile. If the FACILITY class has been RACLISTed, refresh the class for the change to become effective.
  • If the authentication factor you are provisioning requires a PKCS#11 token, ensure that you have CONTROL access to the SO.token_name profile that protects the token and UPDATE access to the USER.token_name profile that protects the token, as described in Configuring a PKCS#11 token.
  • If provisioning AZFCERT1, the user running azfbulk needs read access to the CSFSERV profiles CSFOWH and CSF1TRD.

About this task

IBM MFA includes the azfbulk program that reads from a user-created text file to provision users. The azfbulk program reads the contents of the text file, and produces two shell scripts that you then run to provision the users.
The azfbulk parameters are shown in Table 1.
The parameter usage is as follows:
azfbulk input-file (COMMIT)
Table 1. azfbulk Parameters
Parameter Description
input-file A user-created text file of user names, policies, authentication methods, and authentication method-specific parameters. The format of this file must be as follows:
  • Each entry starts on a new line.
  • Each field is separated by a space.
  • The only validation done is on the authentication method name, and case is sensitive. All other entries are assumed to be valid.
  • The fields are as follows:
    • userID. This is required.
    • policy name. This is required. The policy name field must be a policy name of an existing policy, or *NONE* to not specify a policy.
    • authentication method, including multiple instance factor names. This is required.
    • Zero or more authentication method-specific parameters. This is optional. The parameters are described in Table 2.
COMMIT Commits the changes. You can run the azfbulk program with or without the COMMIT parameter. It is recommended that you run it the first time without COMMIT and then examine the output shell scripts. If the output shell scripts are correct, run the azfbulk program a second time and specify the COMMIT parameter. COMMIT must be in uppercase.
Table 2 describes the authentication method parameters. The parameters are positional and you can omit trailing parameters. However, you must specify all preceding parameters.
Table 2. Input File Authentication-Method-Specific Parameters
Authentication Method Parameters
AZFCERT1 The file specification of the user certificate. The .cer (DER) and PEM formats are supported. The azfbulk program performs the certificate enrollment and approval process described in Approve user certificates on your behalf.
AZFSIDP1, AZFSIDP3, and AZFSIDR1 The associated RSA user ID.
AZFRADP1 and AZFSFNP1 The RADIUS user ID.
AZFPTKT1 The setting for MFAFIRST (Y or N), and the number of seconds for WINDOW.
AZFTOTP1 Does not accept any parameters. The user is set to REGSTATE:OPEN.
AZFISAM1
  • The IBM Security Verify Access user ID.
  • The authentication context.
AZFLDAP1 The user DN.
AZFPASS1 Does not accept any parameters.
AZFYUBI1 The complete string from the .csv file.
AZFCKCTC The user name on the CTC source system.
Note: The AZFCKCTC authentication factor supports in-band authentication only. If you activate a user for AZFCKCTC, the user cannot be associated with a policy name or have any other active authentication factors.
A sample input file is as follows:
USERA CERTONLY AZFCERT1 /u/usersa/certificates/usera.cer
USERB *NONE* AZFTOTP1
USERC *NONE* AZFRADP1  raduserc
USERD *NONE* AZFSFNP1  raduserd
USERE SIDPONLY AZFSIDP1
USERF *NONE* AZFPTKT1 Y 600
USERG *NONE* AZFSIDR1  rsauserg
USERH *NONE* AZFPASS1
USERI *NONE* AZFCKCTC USERI
USERJ *NONE* AZFCKCTC USERX
The azfbulk program creates two shell scripts, azfprov1.sh and azfprov2.sh from the input file:
  • azfprov1.sh associates the users with the policies and factors. The factors are not active. azfprov1.sh invokes azfbulkcmd.sh, which allows you to make any needed customizations if you are using an ESM other than RACF. No changes to azfbulkcmd.sh are required if you are using RACF.
  • azfprov2.sh calls factor-specific utility programs to set the user factor data. azfaprov2.sh commits the changes.

Procedure

  1. Create your z/OS UNIX input file.

    There are many ways to accomplish this step, depending on your environment. For example, you can edit z/OS UNIX files by using the TSO/E OEDIT command to invoke ISPF File Edit or by selecting File Edit on the ISPF menu, if it is installed. In a shell, you can use the ed and sed editors for editing z/OS UNIX files. You can use the oedit shell command to invoke ISPF File Edit.

  2. Add the /usr/lpp/IBM/azfv2r2/bin/ directory to your PATH.
    export PATH=/usr/lpp/IBM/azfv2r2/bin:${PATH}
  3. Run the azfbulk program without the COMMIT parameter.
    azfbulk input-file
  4. Check the resulting azfprov1.sh and azfprov2.sh files.
  5. Correct any errors in your input file and re-run azfbulk. Repeat as needed.
  6. When you are satisfied with the azfprov1.sh and azfprov2.sh scripts, run the azfbulk program with the COMMIT parameter. COMMIT must be in uppercase.
    azfbulk input-file COMMIT
  7. Run the azfprov1.sh shell script.
    sh azfprov1.sh
  8. Verify sample provisioned users in RACF with the LU command.
    LU [Login ID] MFA
    MULTIFACTOR AUTHENTICATION INFORMATION:     
    ---------------------------------------     
      PASSWORD FALLBACK IS NOT ALLOWED          
      AUTHENTICATION POLICIES =                 
        TOTPONLY                                
      FACTOR = AZFTOTP1                         
      STATUS = INACTIVE   
      FACTOR TAGS =       
         REGSTATE:OPEN
  9. Run the azfprov2.sh shell script.
    sh azfprov2.sh
  10. Verify sample user factor data with the LU command.
    LU [Login ID] MFA
    FACTOR = AZFCERT1                                                            
      STATUS = ACTIVE                                                            
      FACTOR TAGS =                                                              
        REGSTATE:APPROVED                                                        
        SUBJECT:CN=Test Cardholder VII,C=US,O=Test Government,OU=Test Departm    
          ent                                                                    
        ISSUER:CN=Test RSA 2048-bit CA for Test PIV Cards,C=US,O=Test Certifi    
          cates 2010,OU=Test CA                                                  
        CERTHASH:B7BF09C7039A43713DFD676237ACC73C699CC7C6                        
        SERIAL:02BF                                                              N