Credentials

Not all services support SPIFFE-based mutual TLS. External APIs, cloud provider services, and legacy systems typically require bearer tokens, API keys, or signed requests. Riptides bridges this gap with a credential pipeline that binds secrets to attested workload identities and delivers them without exposing credentials to application code.

How Credentials Work

Credential management in Riptides is built around two ideas:

• Where a credential comes from. You describe the integration with an external credential provider — how to authenticate to it and how to retrieve or generate a credential. Each provider type handles its own specifics.

• Which workloads receive it, and how. You connect a credential to one or more workloads and choose how it should be delivered to each.

Keeping these separate means a single credential definition can be reused across many workloads with different delivery mechanisms, and provider configuration is managed independently from workload policy.

JWT-SVID Credential Federation

Riptides issues JWT-SVIDs for attested workloads — signed JWTs containing the workload’s SPIFFE ID and other claims. Cloud providers support workload identity federation, allowing Riptides to exchange a workload’s JWT-SVID for temporary cloud credentials without any long-lived keys:

1. The control plane presents the workload’s JWT-SVID to the cloud provider’s STS endpoint.
2. The cloud provider validates the JWT-SVID and issues temporary, scoped credentials.
3. The control plane pushes those credentials to the daemon, which loads them into the kernel for injection.

This is the mechanism behind the AWS, GCP, and Azure provider types.

For step-by-step setup, see the Secretless AWS Access and Secretless GCP Access guides.

Provider Types

Type	Description
AWS	Exchanges the workload’s JWT-SVID with AWS STS via AssumeRoleWithWebIdentity to obtain temporary IAM credentials.
GCP	Exchanges a workload identity token for GCP access credentials via Workload Identity Federation.
Azure	Exchanges a workload identity token for Azure access credentials via federated identity credentials.
Vault/OpenBao	Authenticates to HashiCorp Vault or OpenBao and retrieves a secret or dynamic credential.
Static	Stores a static, pre-provisioned secret such as a long-lived API key or token.
JWT	Issues a signed JWT with custom claims, useful for authenticating to APIs that accept JWT bearer tokens.
OAuth2	Performs an OAuth2 client credentials or authorization code flow to obtain an access token.
OCI	Retrieves credentials for OCI-compliant container registries.

Delivery Mechanisms

Once a credential is obtained, Riptides delivers it to the workload through one of two mechanisms:

Injection (On-the-Wire Header Rewriting)

The kernel module intercepts outbound HTTP requests and adds or rewrites headers before the packets leave the machine. The application makes a plain HTTP request; by the time it reaches the destination, the kernel has injected the required credentials.

Examples of injected credentials:

• Bearer tokens — The kernel adds an Authorization: Bearer <token> header to outgoing requests.
• AWS SigV4 — The kernel computes the AWS Signature Version 4 signing process and adds the Authorization, X-Amz-Date, X-Amz-Security-Token, and other required headers.
• Custom headers — Arbitrary header injection for APIs that expect credentials in non-standard headers.

This is the recommended delivery mechanism. The credential exists only in kernel memory and is written directly into the network buffer. It is never exposed to user-space processes, environment variables, or the filesystem.

Sysfs (Secure File-Based Delivery)

For applications that read credentials from the filesystem (such as SDK-based credential providers or legacy applications), Riptides exposes credential files through the kernel module’s sysfs interface:

/sys/module/riptides/credentials/<credential-name>/token

The kernel module owns these files and controls access. Credentials are refreshed automatically as they rotate. Applications that watch the filesystem or re-read on each use will always get a current credential.

Credential Lifecycle

Credentials managed by Riptides are short-lived and automatically refreshed:

1. Initial fetch — When a credential is bound to a workload, the control plane obtains it from the configured provider and pushes it to the daemon.
2. Delivery — The daemon loads the credential into the kernel module for injection, or exposes it via sysfs.
3. Rotation — Before the credential expires, the control plane fetches a new one and pushes it to the daemon, which updates the kernel module. For injection, the kernel immediately uses the new credential on subsequent requests. For sysfs, the file contents are updated atomically.
4. Revocation — When a binding is removed or the workload no longer matches its identity selectors, the credential is deleted from the kernel module. Injection stops, and sysfs files are removed.

The entire lifecycle is automatic. Operators define where credentials come from and which workloads receive them; the platform handles retrieval, delivery, rotation, and cleanup.

Example

An application that needs to access an AWS S3 bucket:

apiVersion: core.riptides.io/v1alpha1
kind: CredentialSource
metadata:
  name: s3-access
  namespace: riptides-system
spec:
  aws:
    roleARN: "arn:aws:iam::<account-id>:role/<role-name>"
    region: "us-east-1"
---
apiVersion: core.riptides.io/v1alpha1
kind: CredentialBinding
metadata:
  name: frontend-s3
  namespace: riptides-system
spec:
  workloadID: frontend/workload
  credentialSource: s3-access
  propagation:
    injection:
      selectors:
        - app: frontend
          service: s3

With this configuration:

1. The control plane issues an OIDC token for the frontend workload.
2. AWS STS exchanges the token for temporary credentials scoped to the specified IAM role.
3. The kernel module signs outbound S3 requests with SigV4 headers.
4. The frontend application calls S3 using plain HTTP. It never sees or handles AWS credentials.