Prego clients

Open source · MIT or Apache-2.0

cargo-credential-prego

The Cargo credential provider for Prego registries. It finds the machine identity of your build, exchanges it at the Prego STS, and gives Cargo a registry token that is valid for 15 minutes. No long-lived secret goes into Cargo.

Install Source on GitHub

Cargo 1.74 or later. Linux and macOS binaries on every release.

shell
$ cargo install cargo-credential-prego
# CI: GitLab id_tokens, GitHub OIDC, SPIFFE or an API key
$ cargo build --locked
    Updating `acme` index
  Downloaded acme-core v1.4.2 (registry `acme`)

How it works

  1. 01

    Cargo asks

    Cargo starts the provider when it needs a token for your Prego registry.

  2. 02

    Find an identity

    The provider finds a subject token: a JWT-SVID, a CI OIDC token, a token file or an API key.

  3. 03

    Exchange at the STS

    It sends the subject token to the Prego STS (RFC 8693). Your tenant's trust config decides.

  4. 04

    Short-lived token

    Cargo gets a registry token and caches it until 60 seconds before it expires.

Install

From crates.io:

$ cargo install cargo-credential-prego

Or download a prebuilt binary from the release page. Each archive has a .sha256 file: 

$ sha256sum -c cargo-credential-prego-x86_64-unknown-linux-musl.tar.gz.sha256
TargetNotes
x86_64-unknown-linux-muslStatic. No OpenSSL.
aarch64-unknown-linux-muslStatic. No OpenSSL.
x86_64-apple-darwinIntel Mac.
aarch64-apple-darwinApple silicon.

TLS uses rustls with the Mozilla root set. --version prints the version and the git commit.

Configure Cargo

Replace acme with your tenant slug, and default with your namespace.

.cargo/config.toml
[registries.acme]
index = "sparse+https://cargo.prego.k8skill.com/t/acme/default/index/"
credential-provider = ["cargo-credential-prego", "--tenant", "acme"]
ArgumentEnvironmentDefault
--tenant <slug>PREGO_TENANTrequired
--sts-url <url> PREGO_STS_URL https://sts.prego.k8skill.com/v1/sts/token
--audience <aud>PREGO_AUDIENCEprego.k8skill.com
--source <name>PREGO_SOURCEauto
nonePREGO_CA_FILEnone (extra PEM CA bundle)

Identity sources

In auto mode the provider uses the first source that is present, in this order. If that source fails, it stops. It never falls through to an identity you did not expect.

  • 1

    SPIFFE Workload API

    When SPIFFE_ENDPOINT_SOCKET is set. Fetches a JWT-SVID for the audience.

  • 2

    SVID file

    When PREGO_SVID_FILE is set. Reads a JWT-SVID, for spiffe-helper setups.

  • 3

    GitLab CI

    When PREGO_ID_TOKEN is set from id_tokens with aud: prego.k8skill.com.

  • 4

    GitHub Actions

    When the Actions OIDC variables are set. The workflow needs permissions: id-token: write.

  • 5

    Token file

    When PREGO_TOKEN_FILE is set. Kubernetes projected tokens, AWS or GCP workload identity.

  • 6

    API key

    When PREGO_API_KEY is set (prk_…). The STS takes the tenant from the key.

Safety rules

  • Never prints, logs or writes a token to disk. No token cache in the provider.
  • Sends subject tokens only over https. Plain http only to localhost, for tests.
  • Never follows an HTTP redirect, so a subject token cannot go to another host.
  • TLS checks are always on. For an on-prem TLS proxy, add its CA with PREGO_CA_FILE.
  • The full STS contract is public in PROTOCOL.md, so you can review it or write your own client.

Security

Report a vulnerability by email to security@k8skill.com. Do not open a public issue, and do not send real tokens. See SECURITY.md.

License

MIT or Apache-2.0, at your option. Copyright Katskill LLC. The "Prego" name and logo are not licensed for reuse. Fonts on this page use the SIL Open Font License 1.1.