Mapping credentials for a file server using exit classes

If you do not want to use the default credential mapping function of the protocol bridge agent, you can map user credentials in IBM® MQ Managed File Transfer to user credentials on the file server by writing your own user exit. IBM MQ Managed File Transfer provides a sample user exit that performs user credential mapping. If you configure credential mapping user exits, they take the place of the default credential mapping function.

Configuring protocol bridge credential user exits

About this task

A user exit for mapping protocol bridge credentials must implement one of the following interfaces:
  • com.ibm.wmqfte.exitroutine.api.ProtocolBridgeCredentialExit, which allows a protocol bridge agent to transfer files to and from one default protocol file server
  • com.ibm.wmqfte.exitroutine.api.ProtocolBridgeCredentialExit2, which allows you to transfer files to and from multiple endpoints.
The com.ibm.wmqfte.exitroutine.api.ProtocolBridgeCredentialExit2 interface contains the same function as com.ibm.wmqfte.exitroutine.api.ProtocolBridgeCredentialExit and also includes extended function. For more information, see ProtocolBridgeCredentialExit.java interface and ProtocolBridgeCredentialExit2.java interface.

The credential exits can be chained together in a similar manner to other user exits. The exits are called in the order that they are specified in using the protocolBridgeCredentialConfiguration property in the agent properties file. The initialize methods all return separately and if one or more returns a value of false, the agent does not start. The error is reported in the agent event log.

Only one overall result is returned for the mapMQUserId methods of all of the exits as follows:
  • If the method returns a value of USER_SUCCESSFULLY_MAPPED or USER_DENIED_ACCESS as the result code, this value is the returned result and the mapMQUserId methods of the subsequent exits are not called.
  • If the method returns a value of NO_MAPPING_FOUND as the result code, the mqMQUserId method of the next exit is called.
  • If there is no subsequent exit, the NO_MAPPING_FOUND result is returned.
  • An overall result code of USER_DENIED_ACCESS or NO_MAPPING_FOUND is considered as a transfer failure by the bridge agent.

To run your exit, complete the following steps:

Procedure

  1. Compile the protocol bridge credential user exit.
  2. Create a Java archive (JAR) file containing the compiled exit and its package structure.
  3. Place the JAR file containing the exit class in the exits directory of the bridge agent. This directory is in the MQ_DATA_PATH/mqft/config/coordination_queue_manager/agents/bridge_agent_name directory.
  4. Edit the property file of the protocol bridge agent to include the property protocolBridgeCredentialExitClasses. For the value of this property, specify a comma-separated list of classes that implement a protocol bridge credential exit routine. The exit classes are called in the order that they are specified in this list. For more information, see The agent.properties file.
  5. Edit the property file of the protocol bridge agent to include: 
    
exitClassPath=IBM MQ installation_directory\mqft\config\configuration_queue_manager\agents\protocol_bridge_agent_name\exits\SampleCredentialExit.jar

    The agent.properties file for an agent is in your MQ_DATA_PATH/mqft/config/coordination_qmgr_name/agents/agent_name directory.

    If you change the agent.properties file, you must restart the agent to pick up the changes.

  6. You can optionally specify the protocolBridgeCredentialConfiguration property. The value you specify for this property is passed in as a String object to the initialize() method of the exit classes specified by protocolBridgeCredentialExitClasses. For more information, see The agent.properties file.
  7. Start the protocol bridge agent with the fteStartAgent command.

Using the sample user exit

About this task

A sample protocol bridge credential exit is provided in the MQ_INSTALLATION_PATH/mqft/samples/protocolBridge directory and in the topic Sample protocol bridge credential user exit. This sample is based on the com.ibm.wmqfte.exitroutine.api.ProtocolBridgeCredentialExit interface.

The SampleCredentialExit.java exit reads a properties file that maps the MQMD user IDs associated with transfer requests to server user IDs and server passwords. The location of the properties file is taken from the protocol bridge agent property protocolBridgeCredentialConfiguration.

To run the sample user exit, complete the following steps:

Procedure

  1. Compile the SampleCredentialExit.java file.
  2. Create a JAR file containing the compiled exit and its package structure.
  3. Place the JAR file in the MQ_DATA_PATH/mqft/config/coordination_queue_manager/agents/bridge_agent_name/exits directory.
  4. Edit the MQ_DATA_PATH/mqft/config/coordination_queue_manager/agents/bridge_agent_name/agent.properties file to contain the line: 
    
protocolBridgeCredentialExitClasses=SampleCredentialExit
  5. Edit the property file of the protocol bridge agent to include: 
    
exitClassPath=IBM MQ installation_directory\mqft\config\configuration_queue_manager\agents\protocol_bridge_agent_name\exits\SampleCredentialExit.jar

    The agent.properties file for an agent is in your MQ_DATA_PATH/mqft/config/coordination_qmgr_name/agents/agent_name directory.

    If you change the agent.properties file, you must restart the agent to pick up the changes.

  6. Create a credential properties file (credentials.properties) in the directory MQ_DATA_PATH/mqft/config/coordination_queue_manager/agents/bridge_agent and edit it to include entries in the format: 
    
mqUserId=serverUserId,serverPassword
  7. Edit the MQ_DATA_PATH/mqft/config/coordination_queue_manager/agents/bridge_agent_name/agent.properties file to contain the line: 
    protocolBridgeCredentialConfiguration=MQ_DATA_PATH/mqft/
config/coordination_queue_manager/agents/bridge_agent_name/credentials.properties
    You must use the absolute path to the credentials.properties file.
  8. Start the protocol bridge agent by using the fteStartAgent command.