Configure IBM MFA for IBM Security Verify Access

You must configure the IBM® MFA for IBM Security Verify Access settings.

Before you begin

  • If you have not already installed the IBM Security AppX Installer, navigate to https://exchange.xforce.ibmcloud.com/hub/extension/ad8f86525d3a9c1186c1bce524edc9c3 in a browser and download and install it. Log in with an IBM ID if you have not already done so.

    The IBM Security AppX Installer enables configuration of your IBM Security Verify Access appliance for use with partner applications published on the IBM Security App Exchange.

  • Navigate to IBM Security Verify Access Extension for Multi-factor Authentication API in a browser. Log in with an IBM ID if you have not already done so.

    Follow the provided links on the page to download the software and review the documentation.

    Pay close attention to the documented Oauth configuration parameters for running the installer script. These parameters begin with the prefix --oauth (for example --oauthproxy) and they define the back channel interface that is used by IBM MFA to perform OTP authentication.

  • Ensure that backchannelcomplete.json complies with the following syntax:
    {"username":"@USERNAME@","status":"success"}
    The following syntax is also valid. (The example is wrapped for format requirements.)
    {"username":"@USERNAME@","authenticationMechanismTypes":"@AUTHNMECHTYPES@",
    "status":"success"}
  • On the IBM MFA server, you must have already configured PKCS#11 tokens. You must have already configured an AT-TLS profile, as described in Configure an AT-TLS profile. This procedure builds upon that existing profile by defining an AT-TLS outbound rule in Step 7.

About this task

Configuration data for IBM Security Verify Access is stored in the RACF® database. The IBM Security Verify Access configuration data include settings related to the AZFISAM1 authentication load module.

Procedure

  1. Log in to the IBM Security Verify Access local management interface (LMI).
  2. Navigate to Secure Access Control > Global Settings > Template Files > C > authsvc > authenticator > apimfa > browser.html.
  3. Configure the authentication context in the browser.html file:
    <td>
    	  <select name="authnctx">
    	  <option value="server-authnctx">Arbitrary text 
               that describes your server</option>
    	  </select>
    	</td>
    where server-authnctx must match that of the Authentication Context on the IBM MFA server.
  4. A pending change message is displayed at the top of the main pane. Click Click here to review the changes or apply them to the system.
  5. In the Deploy Pending Changes page:
    1. To view the details of changes that are made to a particular module, click the link to that module.
    2. To deploy the changes, click Deploy.
    3. To abandon the changes, click Roll Back.
    4. To close the pop-up page without any actions against the changes, click Cancel.
  6. Add the root CA public certificate of the IBM Security Verify Access server as a CERTAUTH in the z/OS keyring you created in Configure an AT-TLS profile.
  7. Configure an AT-TLS outbound rule. The rule must allow the IBM MFA services AZF#IN00 started task to negotiate the client side of a server-authentication TLS connection with the IBM Security Verify Access server. The HandshakeRole role is Client.

    If the connection port for the IBM Security Verify Access server is not otherwise used by the IBM MFA services AZF#IN00 started task, you can scope the outbound rule to the port number.

    Note: The code fragment is for example purposes only and is not complete. See SYS1.SAZFSAMP(AZFTTLSX) for sample AT-TLS rule definitions for IBM MFA.
    TTLSRule AZFClientRule
    {
      Jobname                         AZF* a              
      LocalAddr                       ALL              
      RemoteAddr                      ALL              
      RemotePortRange                 ?outboundPort? b              
      Direction                       Outbound c          
      Priority                        255              
      TTLSEnvironmentActionRef        eActAZFClient   
      TTLSGroupActionRef              AZFGroupAction1
      TTLSConnectionActionRef         AZFConnAction1    
    }
    
    TTLSConnectionAction AZFConnAction1
    {
      TTLSCipherParmsRef AZFCipherParms
      TTLSConnectionAdvancedParmsRef AZFConnAdvParms1
      CtraceClearText Off
      Trace 255
    }
    :
    :
    Callout Notes:
    1. The Jobname directive indicates that the rule applies only to connections made from the started task.
    2. The RemotePortRange indicates the port on which IBM Security Verify Access server is listening.
    3. The Direction Outbound directive indicates that the rule applies to outgoing connections.
  8. Execute AZFEXEC and choose AZFISAM1.
  9. Provide the following:
    Table 1. AZFISAM1 Factor Attributes
    Setting Allowed Values Description
    PKCS#11 Token Name Actual PKCS#11 token name Enter the name of the PKCS#11 token to be used for cryptographic operations. You created this token in Configuring a PKCS#11 token.
    Key Label Actual PKCS#11 key label The name of the key label that is used to encrypt the client secret. The PKCS#11 key label has a limit of 32 characters. The value you specify for PKCS#11 key label is used if it already exists and is created if it does not exist.
    Client ID Actual client ID User ID that is used to obtain an access or bearer token.
    Client Secret Actual value Password for Client ID.
    Authentication Context Default application context Enables specific OTP generations per authentication context. This is typically a SYSPLEX name, and is only more granular than a SYSPLEX if the application context is included as a user tag. Must match that of the IBM Security Verify Access server unless the application context is included as a user tag.
    Access Token URL URL The URL to which to send the client ID and secret to obtain the access or bearer token.
    One-Time Passcode Validation URL URL URL to which to send user authentication requests.
    Timeout Number of seconds, from 1 through 30 The amount of time the connection can remain inactive before the session is timed out.
    Suspension Threshold 0 through 255 The Suspension Threshold limits the number of times a user consecutively fails to provide a valid token code. Valid values are 0 through 255.
    Note: The Suspension Threshold setting is separate and distinct from a RACF revoked status. The Suspension Threshold setting is most useful in IBM MFA Out-of-Band authentication to prevent brute force attacks. To prevent any conflict or user confusion with the RACF revoke count for in-band authentication, you should set the Suspension Threshold setting to a number significantly higher than the RACF revoke count.

    A value of 0 indicates that brute force protection is not enabled for the AZFISAM1 authentication method.

    Any numeric value greater than zero is treated as the number of times a user may consecutively fail to provide a valid token code. If a user fails exactly this number of times and then provides a valid token code:

    • Authentication succeeds.
    • Their failure count is reset to zero.
    If the user fails more than this number of times:
    • Authentication fails.
    • Their SUSPENDED tag is set to YES
    • Their failure count is reset to zero.
    Initial Trace Level 0 through 3 The trace level used for tracing events within the AZFISAM1 plug-in. Valid values are 0 through 3, where the higher number increases the level of verbosity. The default is zero.
  10. See Configure IBM MFA Compound In-Band for information about configuring IBM MFA Compound In-Band.
  11. Press F3 to save your changes and exit.
If you change the PKCS#11 token name or key label values, you must re-enter the client secret value.