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.

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

1. Edit the server.conf.yaml configuration file for your integration server by using a YAML editor.

   You can edit the file by using the built-in YAML editor that is provided in the IBM® App Connect Enterprise Toolkit, either by double-clicking the file in the Application Development view or by right-clicking the file and selecting Open with > YAML editor. If you choose to edit the file by using a plain text editor, ensure that you do not include any tab characters (which are not valid in YAML) and use a YAML validation tool to validate the contents of your file.

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 source. 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.