Secrets Vault API

Secrets Vault API enables credentials management.

warning

When building automations with Java Native Workers (JNWs), instead of the Secrets Vault API, it is recommended to use jave-native-worker-module-secrets. For details, see the Secrets Module for JNW section.

Description

The password parameter requires a Bcrypt-encoded value with the strength measure of 10.

tip

To manage credentials in Business Processes, you can use Secrets Vault plugins.

Configuration

The service is published at /api/v1/secrets-vault. See a URL example below:

https://custom-name.workfusion.com/workfusion/api/v1/secrets-vault

Authentication

For authentication details, see WorkFusion REST API | API security.

Endpoints

Get secure entry

Resource path: v1/secrets-vault/entry

Method: POST

Description: retrieves a secure entry from Secrets Vault.

Parameter	Description	Required	Parameter type	Data type
alias	Alias of the secured entry	Yes	x-www-form-urlencoded	String

Successful output:

{
    "responseStatus": "SUCCESS",
    "body": {
        "alias": "333",
        "key": "0000000",
        "value": "0000000000",
        "lastUpdateDate": 1449814392229
    },
    "errors": []
}

Error output: invalid UUID

{
    "responseStatus": "FAILURE",
    "body": null,
    "errors": [
        {
            "code": 22,
            "message": "Invalid password"
        }
    ]
}

Save secure entry

Resource path: v1/secrets-vault/entry/put

Method: POST

Description: saves the provided entry to Secrets Vault.

Parameter	Description	Required	Parameter type	Data type
alias	Alias of the secured entry	Yes	x-www-form-urlencoded	String
key	Entry key, usually a username	Yes	x-www-form-urlencoded	String
value	Entry value, usually a password	Yes	x-www-form-urlencoded	String

Successful output:

{
    "responseStatus": "SUCCESS",
    "body": true,
    "errors": []
}

Error output: invalid UUID

{
    "responseStatus": "FAILURE",
    "body": null,
    "errors": [
        {
            "code": 20,
            "message": "Secure Entry 1211 already exists"
        }
    ]
}

Delete secure entry

Resource path: v1/secrets-vault/entry/delete

Method: POST

Description: deletes the specified entry from Secrets Vault.

Parameter	Description	Required	Parameter type	Data type
alias	Alias of the secured entry	Yes	x-www-form-urlencoded	String

Successful output:

{
    "responseStatus": "SUCCESS",
    "body": true,
    "errors": []
}

Error output: invalid UUID

{
    "responseStatus": "FAILURE",
    "body": null,
    "errors": [
        {
            "code": 22,
            "message": "Invalid password"
        }
    ]
}

Update secure entry

Resource path: v1/secrets-vault/entry/update

Method: POST

Description: updates the specified entry (key, value) by alias to Secrets Vault.

Parameter	Description	Required	Param type	Data type
alias	Alias of the secured entry	Yes	x-www-form-urlencoded	String
key	Entry key, usually a username	Yes	x-www-form-urlencoded	String
value	Entry value, usually a password	Yes	x-www-form-urlencoded	String

Successful output:

{
    "responseStatus": "SUCCESS",
    "body": true,
    "errors": []
}

Error output: invalid UUID

{
  "message": "Validation Failed",
  "code": "com.workfusion.api.error.missing.request.parameter",
  "errors": [
    {
      "message": "Required String parameter 'key' is not present",
      "field": "key"
    }
  ]
}

Reset secure entry

Resource path: v1/secrets-vault/entry/reset

Method: POST

Description: resets the value for the specified entry from Secrets Vault. The new value is generated randomly. The length is 20 symbols.

Parameter	Description	Required	Parameter type	Data type
alias	Alias of the secured entry	Yes	x-www-form-urlencoded	String

Successful output:

{
    "responseStatus": "SUCCESS",
    "body": true,
    "errors": []
}

Error output: invalid UUID

{
  "message": "Secure Entry with alias '12342222' does not exist",
  "code": "com.workfusion.api.error.http.not.found"
}

Secrets Module for JNW

Secrets Module defines all necessary classes and API enpoints for getting secrets from the vault (hashicorp). It can be used only for Java Native Workers.

To utilize the module with your JNW, follow the steps below:

1. Add or uncomment required dependency inside your JNW:

   <dependencies>
       <!--uncomment the following dependency if the module that works with client secrets is needed-->
       <dependency>
   
   <groupId>com.workfusion.spa.java.native.worker</groupId>
           <artifactId>module-secrets</artifactId>
       </dependency>
   </dependencies>

2. Check that the secure.storage.safe.customer.default property is defined in the context (ZooKeeper). The value configured during installation must be the same as configured for Control Tower.

Sample code for using Secrets Module

import java.util.Optional;

import org.slf4j.Logger;
import org.springframework.beans.factory.annotation.Autowired;

import com.workfusion.spa.jnative.worker.core.api.TaskInputData;
import com.workfusion.spa.jnative.worker.core.api.TaskOutputData;
import com.workfusion.spa.jnative.worker.core.api.TaskOutputRow;
import com.workfusion.spa.jnative.worker.core.task.ITaskProcessor;
import com.workfusion.spa.jnative.worker.core.task.TaskProcessor;
import com.workfusion.spa.jnative.worker.core.task.TaskProcessorException;
import com.workfusion.spa.jnative.worker.module.event.EventLogger;
import com.workfusion.spa.jnative.worker.module.secret.SecretService;
import com.workfusion.spa.jnative.worker.module.secret.entity.SecretDto;

@TaskProcessor(id = "secret-task")
public class SecretTaskProcessor implements ITaskProcessor {

    //Java Native Worker logger, all messages will be sent into CT as event.
    private final Logger logger;

    //Java native worker client secret service.
    private final SecretService secretService;

    @Autowired
    public SecretTaskProcessor(EventLogger workerLogger, SecretService secretService) {
        this.logger = workerLogger.getEventLogger();
        this.secretService = secretService;
    }

    @Override
    public TaskOutputData process(TaskInputData input) throws TaskProcessorException {
        try {
            // create client secret with provided data.
            secretService.createSecret("my-custom-identifier", "secret-name", "secret-value");
            // update client secret which will be created above.
            secretService.updateSecret("my-custom-identifier", "updated-name", "updated-value");
            // reset secret value for provided alias.
            secretService.resetSecret("my-custom-identifier");
            // get client secret with provided alias.
            Optional<SecretDto> optionalSecret = secretService.getSecret("my-custom-identifier");
            // delete client secret for provided alias
            secretService.deleteSecret("my-custom-identifier");

            //task processing logic

            //build output
            return new TaskOutputData()
                    .addRow(new TaskOutputRow()
                            //.put("some_field", "some_value")
                            //.put("other_field", "other_value")
                    )
                    //add more result row if required
            ;
        } catch (Exception e) {
            logger.error(e.getMessage(), e);
            throw e;
        }
    }

}

Sample code for using mock connection to vault

class SampleTaskProcessorTest extends BaseProcessorTest {

    @Autowired
    TaskProcessingRouter router;

    //It's mock for connection to vault.
    @Autowired
    SecretService secretService;

    @DisplayName("Simple Task Processor generated test case")
    @Test
    void simpleTaskProcessorTest() {
        when(secretService.getSecret("my-alias")).thenReturn(Optional.of(new SecretDto("alias", "key", "secret", new Date())));
        ....
    }
}