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 two platforms:

• GitHub
• Microsoft Entra (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 and GitLab. 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.

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.