Custom Drivers Authentication

This document will provide you with some details about the way the Humanitec Platform Orchestrator validates the requests for Driver execution coming from the Humanitec Operator and how you can replicate this validation mechanism in your Custom Drivers.

Humanitec Platform Orchestrator Driver Requests Validation

As stated in the Humanitec Operator installation guide, you need to perform some actions to enable the Humanitec Operator installed in your cluster to perform requests to Humanitec-hosted Drivers:

  1. You have to create a public/private key pair.
  2. Create a K8s Secret which holds the private key in the same namespace where the Operator runs.
  3. Share the public one with the Humanitec Platform Orchestrator.

The Operator signs all the requests to Drivers (except those it executes internally, which are the Echo and Template Drivers) building a JWT Token composed by:

  • A header which includes the type of the token, the signing algorithm being used, and a kid field holding the fingerprint of the public key created as part of the Operator installation.
{
 "type": "JWT",
 "typ": "RS256",
 "kid": "060981c2b3d50d847edecc0e695a4661090434d4612e328e64f996bbc2bf61c8"
}
  • A payload which contains the orgID specified in the Humanitec Operator installation.
{
 "orgID": "my-humanitec-organization-id"
}

The Operator signs the JWT with the private key in the K8s Secret and the algorithm specified in the JWT header, then it sends the token in the Authorization header of any request using the Bearer schema.

The Humanitec Platform Orchestrator validates the requests verifying the signature with the registered public key.

This check is performed in the central gateway which represents the entry point to Humanitec Drivers and forwards Operator requests only if the authentication check succeeds.

Custom Drivers Validate Humanitec Operator Requests

The same approach to validate requests can be replicated in any Custom Driver:

  • The Driver must be aware of which public key to use to validate the signed JWT.
  • The Driver should contain a logic to validate the received JWT. This can be implemented leveraging one of the several libraries available for the different programming languages.

In order to test the logic that validates signed JWT tokens, this JWT builder can be used.

Testing