Z MFA Parameters for Z MFA OIDC Credential Mapper Plug-in

Required zMFA parameters: Some combination of the following parameters is required to allow the credential mapper plug-in to connect to the Z MFA OIDC service securely:

CMPI_zMFA_JWT2CTC_ENDPOINT

The URL of the service within the IBM Z MFA framework that receives JWT tokens and initiates RACF authentication (Express Logon) to generate a short-lived Cache Token Credential (CTC). E.g. https://zMFAHost:port/jwt2ctc

More information on IBM zMFA configurations:https://www.ibm.com/docs/en/zma/2.4.0?topic=customization-configuring-oidc

CMPI_zMFA_TRUSTSTORE: This parameter contains the name of the keystore file to be used to look up the ZIETrans Z client certificate and the Z MFA server certificate.

CMPI_zMFA_TRUSTSTORE_PASSWORD: This parameter contains the password of the keystore file specified by CMPI_DCAS_TRUSTSTORE.

CMPI_zMFA_TRUSTSTORE_TYPE: This parameter contains the type of the keystore file specified by CMPI_DCAS_TRUSTSTORE. Valid values are pkcs12 and jks.

CMPI_zMFA_CLAIMID_AS_HOSTUID

This parameter contains the claim that would appear as a key-value pair inside the JWT payload, e.g., preferred_username or email, etc. If specified, the value from this key is considered the RACF ID. To use this parameter, ensure that CMPI_zMFA_USE_NETID_AS_HOSTID is set to false.

E.g., JWT Payload:

{
  ……….
  "sub": "1234567890",
  "preferred_username": "johndoe",
  "email": "john.doe@example.com",
  "email_verified": true,
  ………
}

Note:

If you are using ZIETrans OIDC configurations, then the JWT payload is accessible to this plugin. If any claim ID available in the payload represents the host user ID, then provide the claim ID name here. If no mainframe host user ID is available, you can use the parameter CMPI_zMFA_USE_NETID_AS_HOSTID.

Optional zMFA parameters: The following zMFA credential mapper parameters are optional:

CMPI_zMFA_USE_NETID_AS_HOSTID

If set to true, the network ID is considered the RACF ID. The default is true.

E.g., create a Custom Network Plugin and return the CMResponse object with Network ID as a Host User ID:

public class CustomNetworkPlugin implements CMInterface {
……….

public CMResponse CMSGetUserCredentials(CMRequest req) {
  //Write logic to retrieve Network ID and store in a string variable networkID
  //E.g. if the id is available in the session attribute as network_id.
  HttpServletRequest httpReq = cmReq.getHttpRequestObject();
  HttpSession sess = httpReq.getSession(false);
  String networkID = (String) sess.getAttribute("network_id"); 
  //Perform any validation required as per your business logic
   ……….
  CMResponse resp = new CMResponse(networkID, null, SSOConstants.SSO_SUCCESS);
  return( resp );
}
………..
} //CustomNetworkPlugin

More information on creating the custom plugin: Sample Web Express™ Logon plug-in

CMPI_zMFA_HOST_ADDRESS: The default Z MFA host address is determined based on the host specified in the CMPI_zMFA_JWT2CTC_ENDPOINT. Specify the Host address to override this default value.

CMPI_DCAS_HOST_PORT: The default Z MFA host port is determined based on the port specified in the CMPI_zMFA_JWT2CTC_ENDPOINT. Specify the Host port to override this default value.

CMPI_DCAS_NO_FIPS: If set to true, this parameter indicates that the FIPS security provider should not be used. The default security provider will be used instead. The default is false.

CMPI_DCAS_TRACE_LEVEL

This parameter specifies the trace level for the Z MFA plug-in. The trace messages are logged to the ZIETrans trace file. Trace level values include the following settings:

0 = None: No tracing. This is the default.
1 = Minimum: Trace APIs and parameters, return values, and errors.
2 = Normal: Trace Minimum plus internal APIs and parameters and informational messages.
3 = Maximum: Trace Normal plus Java™ exceptions.