Authentication

This document describes how authentication works in Determinate—that is, for both FlakeHub and Determinate Nix. It’s divided into two sections:

• Authentication for humans.
• Authentication for Determinate Nix itself. This section includes information on how Determinate uses JSON Web Tokens (JWTs) as its mechanism for encoding authentication-related information.

Authentication for humans

To use features like private flakes and FlakeHub Cache either as an individual or in an organization, you need to manage your account settings in the FlakeHub UI. To authenticate with the FlakeHub UI, you can use one of these platforms:

• GitHub
• Microsoft Entra (to onboard your organization, see our dedicated guide)
• Okta (to onboard your organization, see our dedicated guide)

Authentication for Determinate Nix

Nix uses a netrc file to supply authentication-related information to external platforms. Determinate Nix automatically places this netrc file at /nix/var/determinate/netrc and handles its contents for you; you don’t ever need to update this file yourself.

That file should look something like this if you’ve supplied Determinate Nix with an auth token:

machine flakehub.com login flakehub password flakehub1_...
machine api.flakehub.com login flakehub password flakehub1_...
machine cache.flakehub.com login flakehub password flakehub1_...

In a real netrc file, the flakehub1_... would be a real FlakeHub-issued JWT prepended by flakehub1_.

JSON Web Tokens (JWTs)

Authentication to FlakeHub is driven by JSON Web Tokens (JWTs). JWTs provide a highly flexible, dynamic way to encode auth-related information based on the carefully considered industry standard set out in RFC 7519. We chose JWTs for two reasons:

1. They can bear arbitrarily granular information via claims.
2. They are issued by many widely used platforms, such as GitHub and Amazon Web Services (AWS), enabling FlakeHub to take advantage of federated authentication.

Unlike many other platforms in the Nix ecosystem, we opted not to use static credentials like public/private key pairs for two reasons:

1. Unlike JWTs, static keys bear only raw key matter, not complex information that can inform decision making about access control and other matters.
2. Static keys impose a steep operational burden, requiring continuous rotation and vigilance in ensuring that they aren’t improperly exposed. To give an example, when using static keys in CI, you’d need to copy/paste those keys into your CI environment as secrets or environment variables. With JWTs from a JWT-based identity provider, on the other hand, this is unnecessary.

Supported platforms

FlakeHub supports JWT-based authentication on these platforms:

• GitHub, GitLab, Semaphore, and Buildkite. FlakeHub uses JWTs issued by these platforms to authenticate CI workflows.
• Amazon Web Services (AWS). FlakeHub uses JWTs issued by AWS’s Secure Token Service (STS) for workloads running on services like EC2.
• Google Cloud Platform (GCP). FlakeHub uses JWTs issued by GCP’s metadata identity service for workloads running on services like Google Compute Engine.

In addition to these platforms, FlakeHub also provides support for authentication via generated tokens for individual users.

Generated tokens

While platforms like GitHub and AWS use platform-based auth, FlakeHub issues its own JWTs to authenticate other systems, such as developer workstations. You can generate as many tokens as you need in the FlakeHub UI.

When you’ve copied the token, you can use Determinate Nixd to register the token:

determinate-nixd login

Paste the copied token in and Determinate Nixd configures Nix to use that token. Determinate Nixd also supports an interactive login flow that enables you to run determinate-nixd login, as above, and then click on the provided URL to go directly to a web interface where you can generate a token.

Device tokens

In FlakeHub, device tokens are JSON Web Tokens (JWTs) that are used for embedded devices, CI runners, build servers, and other systems. They’re tied to a specific FlakeHub organization and are valid until either (a) they’re explicitly revoked or (b) 90 days have passed, whichever comes first.

Token types

FlakeHub offers two types of device tokens: normal and resolve only.

Normal tokens

These tokens authorize a device to fetch store paths from FlakeHub Cache and to access private flakes.

Resolve-only tokens

These tokens only permit the user to resolve store paths in FlakeHub, not to fetch from FlakeHub Cache or access private flakes. See our guide to deploying with resolve-only tokens.

You can manage device tokens either in the FlakeHub UI or using Determinate Nixd

Determinate Nixd

Determinate Nixd has a determinate-nixd auth token device command that you can use to manage device tokens.

List device tokens

You can list non-expired device tokens using the determinate-nixd auth token device list command, specifying the organization using the --org / -o option:

determinate-nixd auth token device list \
  --org my-org

You can limit the number of displayed tokens using the --limit / -l option:

determinate-nixd auth token device list \
  --org my-org \
  --limit 10

The output displays this information for each token:

• UUID
• Description
• Expiration date
• Issue date
• Type

Generate device tokens

You can generate device tokens using the determinate-nixd auth token device create command, specifying the organization using the --org / -o option and a description for the token using the --description / -d option:

determinate-nixd auth token device create \
  --org my-org \
  --description "Submarine #137"

This pipes the token to stdout.

Revoke device tokens

You can revoke device tokens using the determinate-nixd auth token device revoke command, specifying the organization using the --org / -o option and the token ID using the --token-id option:

determinate-nixd auth token device revoke \
  --org my-org \
  --token-id "174579a8-b247-4cde-9636-54383015eb3e"

FlakeHub UI

You can manage device tokens in the FlakeHub UI by going to the settings page for your organization at the proper URL of this form:

Generate device tokens

On the settings page, click New token, then select a token type.

For a normal token, provide a description and click Create token. For a resolve-only token, provide a description, select a project (a flake), provide a version constraint for flake releases, and click Create token.

Once you’ve confirmed creating the token, you’ll see a view that enables you to copy the generated token by clicking Copy.

Revoke device tokens

On the settings page, select the desired token, click Revoke followed by Revoke again in the confirmation pop-up.