Skip to main content

Authenticating against Witboost Computational Governance endpoints

Witboost Computational Governance endpoints are secured using Bearer authentication with valid JSON Web Tokens (JWTs). In order to contact endpoints from external services, the caller must have or construct a valid token. This feature is introduced starting from Witboost version 2.6.0, or when the Computational Governance is present as a standalone service.

Service Account JWT​

Service account JWTs are short-lived tokens generated for a specific Service Account using a provided access token. This is the preferred method for authentication as they are fully created and managed by Witboost; they don't require additional configuration of the Governance Platform in order for them to work; and since they're short-lived, they are more secure as they are not meant to be re-used on a long term.

In order for this authentication method to work, the configuration computational-governance-platform.platform-services.base-url must be correctly set pointing to the Witboost base url.

To configure a Service Account follow the steps present on this page. Then, using the created Access Token your external service can call the Witboost endpoint to generate a JWT including the GOVERNANCE_PLATFORM claim that you can then forward to the Computational Governance endpoint under the Authentication header. Tokens without the correct claim will be rejected.

The Computational Governance only accepts Service Account JWTs signed with ECDSA P-256, or RSA with SHA-512. Other algorithms are currently not supported and will be rejected.

Technical JWT​

Technical tokens are a deprecated way of authenticating against Witboost endpoints, which consist of generating a JWT signed with a secret defined under the backend.auth.keys configuration of Witboost. This was the main way to authenticate requests on versions older than Witboost 2.6, but now has been replaced with Service Account JWTs. We strongly recommend using the Service Account JWT authentication method and only reading this section if you're coming from an old Witboost version.

In order to use Technical tokens, you must first define and store a backend secret under Witboost core configuration backend.auth.keys, and store the same secret on the Witboost Computational Governance configuration computational-governance-platform.platform-services.auth.backend-secrets. This value must be at least 24 bytes long and generated in a secure way (see Witboost configuration for more information). You can define more than one secret this way, as long as it's stored on both service configurations.

After configuring this secret, for each request you perform to the Witboost Computational Governance, you can define a JWT with the following considerations:

  • We recommend defining short-lived JWTs with expiration exp no longer than 1 hour.
  • We strongly recommend adding the claim "scopes": ["GOVERNANCE_PLATFORM"] on the JWT, but the Computational Governance will accept a technical JWT even if the claim is not present.
  • The Computational Governance only accepts Technical JWTs signed with HMAC with SHA-256. Unsigned JWTs or signed JWTs with other algorithms are currently not supported and will be rejected.