Configuring an integration server to use security credentials from an external source

You can configure an independent or managed integration server to access secured resources by using credentials that are retrieved from an external file or key vault.

About this task

You configure the integration server to use an external credential provider by setting properties in the ExternalCredentialsProviders section of the integration server's server.conf.yaml file. Use these properties to specify the command that is invoked to retrieve the security credentials from an external source (such as an external file or key vault), and to specify the code page and format of the output to be returned by the command (XML, JSON, or YAML). The credentials are then passed to the integration server in the specified format and loaded for use when the integration server starts.

Procedure

Configure the integration server to retrieve credentials from an external vault, by completing the following steps:

  1. Edit the server.conf.yaml configuration file for your integration server by using a YAML editor.
    If you do not have access to a YAML editor, you can edit the file by using a plain text editor, but ensure that you use a YAML validation tool to validate the content of your file. Do not include any tab characters, which are not valid in YAML and will cause your integration server configuration to fail.
  2. Create a copy of the ExternalProviderTemplate section for each external credential provider that you want to invoke, and rename the title of each one from ExternalProviderTemplate to the name of the external credential provider. Each name must be unique.
    For example:
    
    ExternalCredentialsProviders:
      MyExternalCredentialProvider1:
          loadAllCredentialsCommand: '/home/aceuser1/ace-server1/read-external-credentials.sh'
          loadAllCredentialsFormat: 'xml'  
          loadAllCredentialsCodepage: 1208  
          loadAllCredentialsDirectErrorToCommandOutput: true  
          loadAllCredentialsIncludeCommandOutputInLogs: false 
    
    
  3. Set the loadAllCredentialsCommand property to specify the command, including arguments, that will be run to retrieve the credentials to be loaded.
    For example:
    loadAllCredentialsCommand: '/home/aceuser1/ace-server1/read-external-credentials.sh'
    In this example, the loadAllCredentialsCommand property specifies a shell script called read-external-credentials.sh, which is located in the integration server's work directory:
    
    #!/bin/bash
    printf '<?xml version="1.0" encoding="UTF-8"?>
    <credentials>
      <credential credentialType="jdbc" credentialName="DB2JDBCCred1">
        <username>db2user2</username>
        <password>apass</password>
      </credential>
    </credentials>'

    When the integration server starts, it runs the script, which retrieves the credentials from the external key vault. In this example, the integration server is running in a container, which is configured to retrieve credentials from an external vault.

    The command can include environment variables and keywords, which are replaced before it runs to provide context-specific configuration, such as ${MQSI_MY_ENVVAR}, [iib.system-work-dir], [iib.system-server-label]. Environment variables are replaced before keywords.

    The command must output a stream of bytes (to stdout) that represent the credentials to be loaded in the configured format (xml, json, or yaml), and in the configured code page. The command must return 0 when executing successfully, as any other return value results in an error being reported and the returned output not being processed.

  4. Set the loadAllCredentialsFormat property to specify the required format of the output to be returned by the command.
    You can specify xml, json, or yaml. The default value is json.
    • When the format is set to XML, the returned credentials must have the following format:
      
      <?xml version="1.0" encoding="UTF-8"?>
      <credentials>
        <credential credentialType="jdbc" credentialName="DB2JDBC">
          <username>db2user2</username>
          <password>apass</password>
        </credential>
        <credential credentialType="rest" credentialName="aRestCred">
          <username>restuser1</username>
          <password>restpassword1</password>
          <apiKey>restapikey</apiKey>
        </credential>
        <credential credentialType="salesforce" credentialName="aSFCred">
          <username>sfuser1</username>
          <password>sfpassword1</password>
          <clientId>clientI</clientId>
          <clientSecret>clientS</clientSecret>
        </credential>
        <credential credentialType="sftp" credentialName="sshInfo">
          <username>sshuser1</username>
          <sshIdentityFile>clientI</sshIdentityFile>
          <passphrase>clientS</passphrase>
          <authType>sshPublicKey</authType>
        </credential>
      </credentials>
    • When the format is set to JSON, the returned credentials must have the following format:
      
      [
        {
          "type":"jdbc",
          "name":"DB2JDBC",
          "properties": {
            "username": "db2user2",
            "password": "apass"
          }
        },
        {
          "type":"rest",
          "name":"aRestCred",
          "properties": {
            "username": "restuser1",
            "password": "restpassword1",
            "apiKey": "restapikey",
          }
        },
        {
          "type":"salesforce",
          "name":"aSFCred",
          "properties": {
            "username": "sfuser1",
            "password": "sfpassword1",
            "clientId": "clientI",
            "clientSecret": "clientS"
          }
        }, 
        {
          "type":"sftp",
          "name":"sshInfo",
          "properties": {
            "username": "sshuser1",
            "sshIdentityFile": "clientI",
            "passphrase": "clientS",
            "authType": "sshPublicKey"
          }
        }
      ]
    • When the format is set to YAML, the returned credentials must have the following format:
      
      Credentials:
        jdbc:
          DB2JDBC:
            username: "db2user2"
            password: "apass"
        something:
          something::else:
            username: "restuser1"
            password: "restpassword1"
            apiKey: "restapikey"
            clientId: "clientI"
            clientSecret: "clientS"
        sftp:
          sshInfo:
            username: "sshuser1"
            sshIdentityFile: "clientI"
            passphrase: "clientS"
            authType: "sshPublicKey"

    The properties for a credential vary according to the credential type. The authType property is optional, but when it is set the type must match the properties supplied and must be a valid authType for the credential. For information about the properties that are valid for each credential type, see mqsicredentials command.

  5. Set the loadAllCredentialsCodepage property to specify the code page of the output to be returned by the command. To use the local code page, set this property to 0. The default value is 1208.
  6. Use the loadAllCredentialsIncludeCommandOutputInLogs and loadAllCredentialsDirectErrorToCommandOutput properties for debugging purposes only:
    • To avoid credentials being leaked into logs, ensure that the loadAllCredentialsIncludeCommandOutputInLogs property is not set in a production environment.
    • When set to true, the loadAllCredentialsDirectErrorToCommandOutput property results in " 2>&1" being appended to the command before it runs, so that stderr output is redirected to the stdout stream. When set to false, stderr output is directed to the integration server stderr stream.
  7. When you have saved the changes to the server.conf.yaml file, restart the integration server for the changes to take effect.

What to do next

For more information about configuring an integration server, see Configuring an integration server by modifying the server.conf.yaml file.