Configuring security credentials for connecting to a REST API

Create a security identity by using the mqsicredentials command, and configure a REST request node in a message flow to use that identity for connecting to a secured REST API. Alternatively, you can use the mqsisetdbparms command.

About this task

Follow these steps to configure a connection to a secured REST API:

Procedure

Use the mqsicredentials command to associate a user name, password, and API key with a connection to an external REST API. Alternatively, you can use the mqsisetdbparms command.
You can specify these values in any one of the following combinations:
- User ID, password, and API key
- User ID and password
- API key only
- Use the mqsicredentials command to specify a user ID, password, and API key for a stopped integration server, as in the following example:
```
mqsicredentials --work-dir workDir --vault-key vaultKey --create --credential-type rest --credential-name myRESTSecurityIdentity --username myRESTUserID --password myRESTPassword --api-key myRESTAPIKey 
```
  Use the following example to specify only the API key for a running integration server:
```
mqsicredentials --work-dir workDir --create --credential-type rest --credential-name myRESTSecurityIdentity --api-key myRESTAPIKey
```
- Alternatively, you can use the mqsisetdbparms command.
  You can specify the security credentials by setting the following parameters:
  
  -n rest::securityIdentity
  
  The name of the security identity that is used to authenticate a connection to a REST API, where securityIdentity is the value of the Security Identity property in the RESTRequest or RESTAsyncRequest node.
  
  -u UserId
  
  The user ID to be used for connecting to the REST API.
  
  -p Password
  
  The password to be used for connecting to the REST API.
  
  -k API key
  
  The API key to be used for connecting to the REST API.
  The following example shows how to specify a user ID, password, and API key:
```
mqsisetdbparms -w workDir -n rest::myRESTSecurityIdentity -u myRESTUserID -p myRESTPassword -k myRESTAPIKey 
```
  Alternatively, you might choose to specify only the API key, as shown in the following example:
```
mqsisetdbparms -w workDir -n rest::myRESTSecurityIdentity -k myRESTAPIKey 
```
For more information about associating security credentials with resources, see mqsicredentials command or mqsisetdbparms command.
In your message flow, specify the name of the security identity that you configured in step 1 (in this example, myRESTSecurityIdentity) as the value in the Security identity property in the RESTRequest or RESTAsyncRequest node.
This security identity will be used when you connect to the REST API from IBM App Connect Enterprise.
In order for the REST request nodes to authenticate to a REST API using a security identity created with the mqsicredentials or mqsisetdbparms command, the REST request nodes require additional information about how to apply that security identity to the REST API. The REST request nodes use the specified security identity only if the operation or API being invoked specifies one or more security requirements in the Swagger document.

Security requirements can be specified at the API level, or for a specific operation, by adding Security Requirement Objects to the security property of the Swagger Object or the relevant Operation Object. Each Security Requirement Object must refer to a Security Scheme Object in the Security Definitions Object, which is defined through the securityDefinitions property of the Swagger object. IBM App Connect Enterprise supports only Security Scheme Objects that have a type of basic or apiKey. Security Scheme Objects with a type of oauth2 are not supported. For more information on Swagger, and defining security requirements in a Swagger document, review the Swagger specification.

What to do next

You can use the mqsicredentials and mqsivault commands to show information about the security identities that are being used for connecting to a REST API. Alternatively, you can use the mqsireportdbparms command. For example:

Use the mqsicredentials command to show the security identity for HTTP Basic Authentication and the API key for a stopped integration server, for use with a REST request node:

mqsicredentials --work-dir workDir --vault-key vaultKey --report --credential-type rest --credential-name myRESTSecurityIdentity

The command returns output similar to the following example:

$ mqsicredentials --work-dir workDir --vault-key vaultKey --report --credential-type rest --credential-name myRESTSecurityIdentity
BIP15118I: The Integration Server/Integration Node is not running. Only credentials from the 'vault' provider will be shown. 
BIP15110I: The credential name 'myRESTSecurityIdentity' of type 'rest' contains user name 'myRESTUserID' from provider 'vault' and has the following properties defined: 'authType, password, apiKey'

Alternatively, you can use the mqsireportdbparms command to show the security identity for HTTP Basic Authentication and the API key, for use with a REST request node:

mqsireportdbparms -w c:\workdir\ACEServ1 -n rest::myBasicAuthAndApiKey

This command returns output similar to the following example:

$ mqsireportdbparms -w c:\workdir\ACEServ1 -n rest::myBasicAuthAndApiKey
BIP8180I: The resource name 'rest::myBasicAuthAndApiKey' has userID 'myUserID'.
BIP8214I: The resource name 'rest::myBasicAuthAndApiKey' has API key 'C664C588-885A-4F07-9390-9CD7A4F8A89F'.

Use the mqsivault command to display the credentials, including the password, associated with a resource:

mqsivault --work-dir /tmp/ACEServ1 --vault-key vaultKey --decode credentials/rest/myRESTSecurityIdentity

The command returns output similar to the following example:

Namespace: credentials
Record: rest/myRESTSecurityIdentity
{"name":"myRESTSecurityIdentity","type":"rest","properties":{"apiKey":"myRESTAPIKey","authType":"basicApiKey","password":"myRESTPassword","username":"myRESTUserID"}}

Alternatively, use the mqsireportdbparms command to validate the password. In the following example, the command is validating the password for a single security identity for HTTP Basic Authentication, for use with a REST request node:

mqsireportdbparms -w c:\workdir\ACEServ1 -n rest::myBasicAuth -u myUserID -p password

This command returns output similar to the following example:

$ mqsireportdbparms -w c:\workdir\ACEServ1 -n rest::myBasicAuth -u myUserID -p password
BIP8180I: The resource name 'rest::myBasicAuth' has userID 'myUserID'.
BIP8201I: The password you entered, 'password' for resource 'rest::myBasicAuth' and userId 'myUserID' is correct.


BIP8071I: Successful command completion.

For more information about the security credentials that have been set on the integration server, see mqsicredentials command or mqsireportdbparms command.