Problem

How to use certificate authentication when working with SecureTransport's REST API?

Resolution

Applicable for API v2.0.

Follow the below steps to configure and use certificate authentication with the API.

Create a certificate

Create a login certificate for the account from Admin UI → Accounts → Choose the Acccount → Certificate → Login certificates → Generate. Make sure you save the private key when you create it.

You can also create a certificate outside of ST and just import the public part of it under Login Certificates.

Configure SecureTransport for certificate authentication

Once the certificate is in place, SecureTransport should be configured to accept certificate authentication. This is done by the below steps from the Admin UI:

Go to Authentication → Login Settings in the Admin UI

Enable the Certificate checkbox

Set the Client Certificate Settings option to Optional or Required for the HTTP protocol

Required: ST will accept only certificate as authentication method

Optional: ST will accept certificate or username/password for authentication

Restart the HTTP service from Operations → Server Control page

(optional) If there is an Edge server in use, repeat the above steps on the Edge as well

In a clustered setup, always import the keys and configure the key-authentication in the Primary node of the cluster.

Extract the private key

When you created the certificate in the first step, you were given the option to save the private key. The resulting file is a PKCS#12 capsule file, containing the provate key. You need to extract it from the capsule. With OpenSSL, run this command:

openssl pkcs12 -in /Path/to/certificate/auth-account.p12 -out key_account.pem

The key_account.pem file is the private key, which you will need to authenticate the API calls with.

Example with curl

The below command authenticates a user against the API, stores a cookie in /tmp/cookie and uploads a file named file.txt from the local directory to the ST user's home folder. It is important that curl is compiled with OpenSSL for the authentication to work. Once done, you can clear the session cookie using rm -rf /tmp/cookie.

curl -k -s -E ./key_account.pem:PEM_PASSWORD -c /tmp/cookie -X POST "https://10.232.24.173/api/v1.4/files"  -H  "accept: application/json" -H  "Content-Type: multipart/form-data" -F "file=@file.txt;type=text/plain" -v