Run Mode

BobHok bypassing

In BoB, the use of a bobHok is recommended. BobHok is a claim in the auth token (JWT) containing the fingerprint of the client certificate used in the request to the Authentication API that created the auth token. It prevents the auth token from being tampered with in a man-in-the-middle attack.

For STEVE to validate and proxy BoB requests and responses, the bobHok must be bypassed. There are three ways to run STEVE, so called Run Modes, to accomplish this.

NO_BOBHOK is the obvious choice if it’s possible.

CLIENT_CERT favours the use case where the target system is in production (or in test but cannot be reconfigured) and the client is under test including the Authentication API so that it is not a big deal to configure the client certificate private key in STEVE.

NEW_AUTH_TOKEN favours the use case where the target system is under test and the client is in a more production-ready state, including the Authentication API, so that it is not desirable to give access to the client certificate private key to STEVE.

Run Mode can be configured in the Steve UI Configuration view.

NO_BOBHOK - No bobHok

If both the client and the target system work without bobHok, STEVE will work as a proxy without the need for anything more.

CLIENT_CERT - Install client’s client certificate in STEVE

In the call to the target system, STEVE uses the same client certificate that was used when the client created the auth token.

Both the client certificate and the private key are configured into STEVE.

The target system can verify the bobHok since the TLS connection from STEVE to the target system uses the client’s client certificate and the bobHok contains the fingerprint of that certificate.

NEW_AUTH_TOKEN - STEVE creates a new auth token

A new auth token is created with almost the same content as the client’s auth token. The new auth token is signed using a configured auth token private key. It is required that the corresponding auth token public key can be used by the target system to verify the auth token signed by STEVE using the auth token private key. Normally, the way to achieve this is to publish the auth token public key in BoB Metadata and let the target system update the public key by retrieving it from BoB Metadata. For test, it is probably easiest to publish it in the BoB Metadata Test Environment. Use the POST​/participantMetadata​/{pid}​/authtokenPublicKey endpoint of the Participant Metadata API to add a new auth token public key.

Optionally a client certificate and private key can be configured. If these are not configured, STEVE will use its default built-in client certificate and private key.

The new auth token will create a new bobHok claim matching the client certificate only if bobHok is present in the original auth token.