Cafienne Typescript Client

A Typescript based set of REST APIs to run against a Cafienne Engine, typically used for testing CMMN case models.

The framework is intended to provide an easy means of building test cases against the Cafienne engine.

The Cafienne engine has the following aspects

• Authentication can only be done through OpenID Connect protocol
• The multi-tenant environment requires user registration before you can start running cases.

Versions

• Version 0.8.* is tested against Cafienne Engine APIs 1.1.27.
• Version 0.7.* is tested against Cafienne Engine APIs 1.1.24.
• Version 0.6.* is tested against Cafienne Engine APIs 1.1.21.
• Version 0.5.* is tested against Cafienne Engine APIs 1.1.20.
• Version 0.4.* is tested against Cafienne Engine APIs 1.1.18.
• Version 0.3.2 is tested against Cafienne Engine APIs 1.1.17.

Setup environment

The client library uses a simple Token Generator to generate JWT tokens that the Cafienne Engine can trust. This "IDP" generates any JWT token that we ask it to generate, and in using that the client library circumvents the Open ID Connect protocol that a normal Cafienne deployment uses. In order to make Cafienne Engine "trust" these tokens, the config settings of the engine have to be changed.

Running the Token Generator

Some of the default engine test cases also need a mailcatcher docker image.

Below is a yaml snippet that you can use to create a docker environment with this image. You can use e.g. in combination with the docker compose files in the Cafienne Getting Started repository.

    Security Alert - do not run this in production

    The IDP generates any requested token without validation.
    Using it in a production environment of the Cafienne Engine
    will run the system without proper authentication

Contact us at [email protected] if you need further help on this.

services:
  # supporting container for testing
  oidc-test-token-service:
    image: spectare/oidc-token-test-service:latest
    labels:
      component: oidc-test-token-service
    networks: 
      - dev
    expose:
      - 2377
    ports:
      - "2377:2377"
    environment:
      BIND: 0.0.0.0
      PORT: 2377
    hostname: oidc-test-token-service
    container_name: oidc-test-token-service

networks:
  dev:
    driver: bridge    

This will start a token generator on port http://localhost:2377. The next step is to change the configuration of the Cafienne Engine.

Configure Cafienne Engine to trust this IDP

    Security Alert - do not run this in production

    The IDP generates any requested token without validation.
    Using it in a production environment of the Cafienne Engine
    will run the system without proper authentication

The Cafienne Engine OpenID Connect configuration settings must be modified to point to the test IDP. Open Cafienne's local.conf file. In there, search for oidc and change it in the below

    cafienne {
        # Platform has owners that are allowed to create/disable/enable tenants
        #  This property specifies the set of user-id's that are owners
        #  This array may not be empty.
        platform {
            owners = ["admin"]
        }

        api {
            security {
                # configuration settings for OpenID Connect
                oidc {
                    connect-url = "http://localhost:2377/.well-known/openid-configuration"
                    token-url = "http://localhost:2377/token"
                    key-url = "http://localhost:2377/keys"
                    authorization-url = "http://localhost:2377/auth"
                    issuer = "http://localhost:8080"
                }
            }
        }
    }

Custom configuration

The client library exposes a few configuration options. These are stored inside the file ./config.js.

By default all logging is enabled.

var Config = {
    CafienneService: {
        // URL of backend engine
        url: 'http://localhost:2027/',
        log: {
            // Whether or not to log HTTP call information (user, url, method type, headers)
            url: true, // URL includes call number, method type and user id
            request: {
                headers: true, // Shows request headers
                body: true, // Shows request body
            },
            response: {
                status: true, // Shows response statusCode and statusMessage, including call number 
                headers: true, // Shows response headers
                body: true // Shows response body
            }
        },
        // CQRS Wait Time is the time the engine needs to process events from commands (e.g. StartCase, CompleteTask, CreateTenant) into the server side query database
        cqrsWaitTime: 5000
    },
    TokenService: {
        // URL of token service
        url: 'http://localhost:2377/token',
        // Issuer can be configured. The issuer must equal what is configure inside the Cafienne Engine
        issuer: 'http://localhost:8080',
        // Whether or not to show the tokens requested and updated in the user
        log: true
    },
    PlatformService: {
        // Whether or not to show log messages on the console from the platform APIs (e.g., whether tenant already exists or not)
        log: true
    },
    RepositoryService: {
        // Whether or not to show log messages on the console from the repository APIs (e.g., list of case definitions returned from server)
        log: true
    },
    TestCase: {
        // Whether or not to show log messages on the console (e.g. wait time messages for server side processing)
        log: true
    }
};

It holds the end points of the token service and the case engine.

Here you can also modify the issuer field of the token. In case this is changed, make sure that the change is also reflected in the local.conf of the case engine.