mqsicredentials command

Use the mqsicredentials command to encrypt credentials and store them in an IBM® App Connect Enterprise vault. These credentials can then be used by an integration node and its managed integration servers, an individual integration server, or any number of integration servers, to access secured resources.

Supported platforms

Windows
Linux®
AIX®

Purpose

Use the mqsicredentials command to create, update, retrieve, or delete the security credentials for resources that can be used by an integration node and its managed integration servers, an individual integration server, or any number of integration servers. The credentials are stored in an encrypted form in an App Connect Enterprise vault.

For more information about configuring vaults and credentials, see the following topics:

The security credentials that you set are used for connections to resources that you can use with an integration node and its managed integration servers.

For more information about the security credentials, see Credential types.

Syntax

Create or update credentials

Report

Delete

Set as default

Export / Import

Parameters

--work-dir workpath

(Optional) This parameter specifies the path to the work directory that is used by an independent integration server (not an integration server that is managed by an integration node). If you do not specify the --work-dir parameter, you must specify either the --ext-vault-dir, integrationNodeName, or --integration-connection-file parameter, or the --admin-host and --admin-port parameters.

--ext-vault-dir externalDirectoryVaultPath

(Optional) This parameter specifies the path to the directory that contains the external directory vault, which can be shared by multiple integration servers. If you do not specify the --ext-vault-dir parameter, you must specify either the --work-dir, integrationNodeName, or --integration-connection-file parameter, or the --admin-host and --admin-port parameters.

You cannot set the --ext-vault-dir parameter in conjunction with the --set-as-default parameter.

integrationNodeName

(Optional) The name of the integration node that is associated with the resources for which the credentials are being created, updated, reported, or deleted. If you do not specify this parameter, you must specify either the --work-dir, --ext-vault-dir, or --integration-connection-file parameter, or the --admin-host and --admin-port parameters.

--integration-connection-file fileName

(Optional) This parameter specifies a file that contains connection information for an integration node or server. If you do not specify the --integration-connection-file parameter, you must specify either the integrationNodeName, --work-dir, or --ext-vault-dir parameter, or the --admin-host and --admin-port parameters.

--admin-host hostname

(Optional) This parameter specifies the hostname or IP address of the computer on which the integration node or integration server is running. If you do not specify the --admin-host and --admin-port parameters, you must specify either the integrationNodeName, --work-dir, --ext-vault-dir, or --integration-connection-file parameter.

--admin-port port

(Optional) This parameter specifies the port of the integration node or integration server. If you do not specify the --admin-host and --admin-port parameters, you must specify either the integrationNodeName, --work-dir, --ext-vault-dir, or --integration-connection-file parameter.

--integration-server IntegrationServerName

(Optional) Specify the name of the integration server that is associated with the resources for which the credentials are being created, updated, reported, or deleted. This parameter applies only to integration servers that are managed by an integration node. Alternatively, you can specify --all-integration-servers.

--all-integration-servers

(Optional) This parameter specifies that the command applies to all integration servers that are managed by the integration node. Alternatively, you can specify a named integration server (--integration-server IntegrationServerName). This parameter applies only to integration servers that are managed by an integration node.

--create

(Optional) Specify this parameter to create credentials in the vault, with the name and type specified by the --credential-name and --credential-type parameters.

If you do not specify this parameter, you must specify either --update, --report, --set-as-default, or --delete.

--update

(Optional) Specify this parameter to update the credentials that are specified by the --credential-name and --credential-type parameters.

If you do not specify this parameter, you must specify either --create, --report, --set-as-default, or --delete.

--report

(Optional) Specify this parameter to show the reportable details of an existing credential, as specified by the --credential-name and --credential-type parameters.

If you do not specify this parameter, you must specify either --create, --update, --set-as-default, oror --delete.

--delete

(Optional) Specify this parameter to delete the specified credentials from the vault.

If you do not specify this parameter, you must specify either --create, --update, --set-as-default, or --report.

--set-as-default

(Optional) Use this parameter to specify that the credential that is specified by the --credential-name parameter is to be used as the default for the credential type set by the --credential-type parameter. If you set this parameter, the default credentials section of the integration server's server.conf.yaml file is updated with the specified default; for example:

Defaults:
 Credentials:
   mq: 'mymqcredential'

This credential is then used by default for the specified credential type (in this case, mq) when no credential name was specified.

If you do not specify this parameter, you must specify either --create, --update, --delete, or --report.

You cannot set the --set-as-default parameter in conjunction with the --ext-vault-dir parameter.

--export / import

(Optional). Use --export to export the selected credential(s) from the vault into a zip archive file. Use --import to import the selected credential(s) from a zip archive file into the vault.

Credentials cannot be exported from the vault if the --vault-options no-export parameter was set when the vault containing the credentials was created (by the mqsivault command). For more information, see mqsivault command.

--credential-name credentialName

(Optional) The name of the credential.

--credential-type credentialType

(Optional) This parameter specifies the credential type, which relates to the type of resource that is connected to by the integration server:

For more information about credential types, see Credential types.

--archive-location archiveLocation

(Optional) The location of the zip archive file to be imported from or exported to.

--archive-key archiveKey

(Optional) The password required to access the --archive-location.

--vault-key vaultKey

(Optional) The vault key that is used to access the vault where the credential is stored. You can specify either the --vault-key, --ext-vault-key, or --vaultrc-location parameter, or you can set the MQSI_VAULT_KEY, MQSI_EXT_VAULT_KEY, or MQSI_VAULTRC_LOCATION environment variable. If you specify none of these, the .mqsivaultrc file is looked for in your HOME directory.

--ext-vault-key externalDirectoryVaultKey

(Optional) The vault key that is used to access the external directory vault where the credential is stored. You can specify either the --ext-vault-key, --vault-key, or --vaultrc-location parameter, or you can set the MQSI_EXT_VAULT_KEY, MQSI_VAULT_KEY, or MQSI_VAULTRC_LOCATION environment variable. If you specify none of these, the .mqsivaultrc file is looked for in your HOME directory.

--vaultrc-location mqsivaultrc_file_location

(Optional) The location of the .mqsivaultrc file that contains the vault key. You can specify either the --vaultrc-location, --vault-key, or --ext-vault-key parameter, or you can set the MQSI_VAULTRC_LOCATION, MQSI_VAULT_KEY, or MQSI_EXT_VAULT_KEY environment variable. If you specify none of these, the .mqsivaultrc file is looked for in your HOME directory.

--username userId

(Optional) The user ID to be associated with this resource.

--password password

(Optional) The password to be associated with this resource.

If you specify a password by using the --password parameter and the password includes characters that have special meaning to the command shell, you must use quotation marks around the password or escape the characters. Use single quotation marks on Linux and AIX systems. Use double quotation marks on Windows systems. For a full list of reserved characters, and the rules that are associated with those characters when you use quotation marks and escape characters, see the documentation that is supplied with the shell.

However, you can avoid the need to use quotation marks or to escape special characters if you omit to specify a password with the --password parameter. If you specify the parameter with no password, you are prompted to enter a password during the invocation of the command. The password that you specify after being prompted can include characters that have special meaning to the command shell with no need for you to use quotation marks or to escape these characters.

--client-id clientIdentity

This parameter specifies either of the following values:

(Optional) The name of the consumer key of your Salesforce Connected App to be used for authentication with Salesforce systems
(Optional) The name of the client ID of your connected LoopBack® application to be used for authentication with LoopBack connectors

--client-secret clientSecret

This parameter specifies either of the following values:

(Optional) The consumer secret of your Salesforce Connected App to be used for authentication with Salesforce systems.
(Optional) The client secret of your connected LoopBack application to be used for authentication with LoopBack connectors.

--api-key apiKey

(Optional) The API key to be used for authentication with REST APIs. You can specify only a REST API key to be used for authentication, or you can specify a REST API key together with a user ID and password.

--ssh-identity-file identityFile

(Optional) The name of an identity file, in PEM format, to be used for authentication with SFTP in place of a password. You must specify either a password or an identity file, but not both. If you specify an identity file, you can also specify a passphrase with the --passphrase parameter.

--passphrase passphrase

(Optional) The passphrase that is used for authentication with SFTP. This parameter is valid only when the --ssh-identity-file parameter is also specified. The passphrase is used during decryption of the identity file.

--trace traceFileName

(Optional) This parameter writes debug trace information about the command to the specified output file.

Authorization

For more information about platform-specific authorizations, see the following topics:

If you enable administration security, you must also set up the authority that is detailed in Tasks and authorizations for administration security.

Ensure that the registry is secured to prevent unauthorized access.

Examples

The following examples show the setting of security credentials by using the mqsicredentials command:

ODBC Data source names

The following examples show the use of the mqsicredentials command to associate credentials for ODBC connections:

Create ODBC credentials on integration server myIntegrationServer1, which is managed by integration node myIntegrationNode1, when the integration node and server are running:

mqsicredentials myIntegrationNode1 --create --integration-server myIntegrationServer1 
--credential-type odbc --credential-name myDSN1 --username user1 --password myPassword1

Create ODBC credentials on integration server myIntegrationServer1, which is managed by integration node myIntegrationNode1, when the integration node or server is stopped:

mqsicredentials myIntegrationNode1 --create --integration-server myIntegrationServer1 --vault-key
AAIAmAVaultKey 
--credential-type odbc --credential-name myDSN1 --username user1 --password myPassword1

Delete ODBC credentials on integration server myIntegrationServer1, which is managed by integration node myIntegrationNode1:

mqsicredentials myIntegrationNode1 --delete --integration-server myIntegrationServer1 
--vault-key myVaultKey --credential-type odbc --credential-name myDSN1

You can delete the credentials only when the integration node is stopped, and you must specify a vault key.

LDAP servers

Create credentials on integration node myIntegrationNode1 to access LDAP:

mqsicredentials myIntegrationNode1 --create --credential-type ldap --credential-name adminAuthentication 
--password myPassword1

Salesforce servers

Create credentials for all integration servers managed by the specified integration node to access Salesforce:

mqsicredentials -i localHost -p 4416 --all-integration-servers --create  --credential-type salesforce 
--credential-name mySF --username sfuser1 --password mysfpassword --client-id myclientid --client-secret myclientsecret

Authenticating incoming requests

You can use the security profile when you use an authentication type of 'Local' to authenticate incoming requests. For example:

Create a credential of type 'local' on the independent integration server work directory c:\mywrk\myaceworkdir to authenticate against when used with a security profile that has an authentication type of 'Local' and authenticationConfig of 'LocalCredentialsAlias':

mqsicredentials --work-dir c:\mywrk\myaceworkdir --create --vault-key abcd1234 --credential-type local 
--credential-name LocalCredentialsAlias --username SecUserName --password SecPwd

For more information about authenticating incoming requests, see Authenticating incoming requests by using credentials stored in the vault.