Package co.ankatech.ankasecure.keymanagement

Class WorkloadCredential

java.lang.Object
co.ankatech.ankasecure.keymanagement.WorkloadCredential
public final class WorkloadCredential extends Object
How an administrative workload proves its identity to the platform's token endpoint.

An administrative workload is a non-human principal of the administration API (a pipeline, an operator tool, an integration) registered in a tenant or in the platform. It authenticates in one of two ways, both presented as an OAuth 2.0 client_assertion with the workload id as client_id, and never with a shared secret:

  • private_key_jwt (RFC 7523) — the SDK signs a short-lived assertion (iss = sub = the workload id, one minute of lifetime, a fresh jti) with a private key whose public half is registered on the workload. The key is read from a file (privateKeyJwt(UUID, Path), re-read at every token request) or supplied as a JCA key (privateKeyJwt(UUID, PrivateKey)); the SDK never copies it anywhere.
  • federated — an external issuer the platform trusts (a CI system, a cloud workload identity) mints a token for the workload, and the SDK presents it as is. The token is obtained anew for every token request, from a supplier (federated(UUID, Supplier)), a file the external system rotates (federatedTokenFile(UUID, Path)) or a command (federatedTokenCommand(UUID, List)).

Pass the credential to AnkaSecureKeyManagementSdk.authenticateWorkload(WorkloadCredential):


 UUID workloadId = UUID.fromString("9b2f6c1e-3d4a-4c8b-a1e7-5f0d2c9b8a71");
 try (AuthenticatedKeyManagementSdk sdk = factory.authenticateWorkload(
         WorkloadCredential.privateKeyJwt(workloadId, Path.of("/etc/acme/workload-key.jwk")))) {
     sdk.keys().get("payments-signing-key");
 }

Instances are immutable and never render key or token material in toString().

  • Method Details

    • privateKeyJwt

      public static WorkloadCredential privateKeyJwt(UUID workloadId, Path privateJwkFile)
      A workload that signs its assertions with the private key held in a file.

      The file holds either a private JWK (an RSA key, or an EC key on P-256, P-384 or P-521) or a PEM-encoded PKCS#8 private key (RFC 7468 label PRIVATE KEY). It is read when AnkaSecureKeyManagementSdk.authenticateWorkload(WorkloadCredential) is called and again at every token request, so a rotated file is picked up, and the key is held only for the time it takes to sign. On POSIX systems a file readable by its group or by others is refused before any request is sent; on Windows an access list granting read to a principal other than the owner, SYSTEM or Administrators produces a warning.

      
 WorkloadCredential credential = WorkloadCredential.privateKeyJwt(
         UUID.fromString("9b2f6c1e-3d4a-4c8b-a1e7-5f0d2c9b8a71"),
         Path.of("/etc/acme/workload-key.jwk"));
      Parameters:
      workloadId - the workload id; must not be null
      privateJwkFile - the file holding the private key; must not be null
      Returns:
      the credential; never null
      Throws:
      NullPointerException - if an argument is null

    • privateKeyJwt

      public static WorkloadCredential privateKeyJwt(UUID workloadId, PrivateKey privateKey)
      A workload that signs its assertions with a private key the caller holds as a JCA key, for example one kept in a hardware-backed KeyStore.

      An RSAPrivateKey signs with RS256; an ECPrivateKey with ES256, ES384 or ES512 according to its curve. The SDK keeps a reference to the key for the life of the authenticated instance and never exports it.

      
 PrivateKey key = (PrivateKey) keyStore.getKey("acme-workload", keyPassword);
 WorkloadCredential credential = WorkloadCredential.privateKeyJwt(
         UUID.fromString("9b2f6c1e-3d4a-4c8b-a1e7-5f0d2c9b8a71"), key);
      Parameters:
      workloadId - the workload id; must not be null
      privateKey - the private key whose public half is registered on the workload; must not be null
      Returns:
      the credential; never null
      Throws:
      NullPointerException - if an argument is null

    • federated

      public static WorkloadCredential federated(UUID workloadId, Supplier<String> externalToken)
      A federated workload: an external issuer the platform trusts mints a token for it, and the SDK presents that token as its client_assertion.

      The supplier is called at every token request (the first one and every renewal), so it should return a token that is valid at that moment; the SDK never caches its value. A null or blank value fails the token request without sending it.

      
 WorkloadCredential credential = WorkloadCredential.federated(
         UUID.fromString("9b2f6c1e-3d4a-4c8b-a1e7-5f0d2c9b8a71"),
         () -> ciEnvironment.requestIdToken("https://dev.ankatech.co/api"));
      Parameters:
      workloadId - the workload id; must not be null
      externalToken - the source of the external token; must not be null
      Returns:
      the credential; never null
      Throws:
      NullPointerException - if an argument is null

    • federatedTokenFile

      public static WorkloadCredential federatedTokenFile(UUID workloadId, Path tokenFile)
      A federated workload whose external token is written to a file by the system that mints it (a Kubernetes projected service-account token, a CI runner's identity token file).

      The file is read again at every token request, so a token the external system rotated is picked up. Surrounding whitespace is ignored; an empty file fails the token request without sending it.

      
 WorkloadCredential credential = WorkloadCredential.federatedTokenFile(
         UUID.fromString("9b2f6c1e-3d4a-4c8b-a1e7-5f0d2c9b8a71"),
         Path.of("/var/run/secrets/tokens/ankasecure"));
      Parameters:
      workloadId - the workload id; must not be null
      tokenFile - the file holding the external token; must not be null
      Returns:
      the credential; never null
      Throws:
      NullPointerException - if an argument is null

    • federatedTokenCommand

      public static WorkloadCredential federatedTokenCommand(UUID workloadId, List<String> command)
      A federated workload whose external token is printed by a command (a cloud CLI, a credential helper).

      The command is run at every token request, directly through ProcessBuilder with the given arguments and never through a shell, so no argument is interpreted. Its standard output, trimmed, is the token; its standard error is discarded. A command that exits with a non-zero status, prints nothing, or has not exited within 30 seconds (whether or not it closed its output) fails the token request without sending it; a command still running at that deadline is killed, with the processes it started that are still its descendants. A process it started and left running after it exited is not tracked.

      
 WorkloadCredential credential = WorkloadCredential.federatedTokenCommand(
         UUID.fromString("9b2f6c1e-3d4a-4c8b-a1e7-5f0d2c9b8a71"),
         List.of("gcloud", "auth", "print-identity-token", "--audiences=https://dev.ankatech.co/api"));
      Parameters:
      workloadId - the workload id; must not be null
      command - the program and its arguments, one element each; must not be null or empty
      Returns:
      the credential; never null
      Throws:
      NullPointerException - if an argument or a command element is null
      IllegalArgumentException - if command is empty

    • workloadId

      public UUID workloadId()
      Returns:
      the workload id this credential authenticates; never null

    • toString

      public String toString()
      Names the workload and the kind of credential, never key or token material.
      Overrides:
      toString in class Object
      Returns:
      a log-safe description