118 lines
3.5 KiB
Markdown
118 lines
3.5 KiB
Markdown
# nix-cache-login
|
|
|
|
CLI tool for authenticating with a Nix binary cache via Keycloak OIDC. Obtains
|
|
access tokens and writes them to a netrc file so Nix can use them
|
|
transparently.
|
|
|
|
Canonical Repository: https://guardianproject.dev/ops/nix-cache-login
|
|
|
|
## Overview
|
|
|
|
Nix binary caches can be protected with OIDC-based authentication backed by
|
|
Keycloak. This tool handles the token lifecycle:
|
|
|
|
- Workstation users: authenticate via browser (Authorization Code + PKCE), get a 1-hour access token and a 24-hour refresh token
|
|
- Servers: authenticate headlessly via client credentials, get a short-lived access token refreshed on a timer
|
|
|
|
The access token is written to a netrc file, which Nix reads automatically when
|
|
fetching from the cache.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
# run directly
|
|
nix run guardianproject.dev/ops/nix-cache-login
|
|
```
|
|
|
|
Or add as a flake input:
|
|
|
|
```nix
|
|
{
|
|
inputs.nix-cache-login.url = "git+https://guardianproject.dev/ops/nix-cache-login";
|
|
|
|
# use the package
|
|
# nix-cache-login.packages.${system}.default
|
|
}
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Create `$XDG_CONFIG_HOME/nix-cache-login/config.toml` (default `~/.config/nix-cache-login/config.toml`):
|
|
|
|
**Workstation:**
|
|
```toml
|
|
issuer = "https://id.guardianproject.info/realms/gp"
|
|
client_id = "nix-cache"
|
|
cache_host = "cache.guardianproject.dev"
|
|
netrc_path = "$XDG_CONFIG_HOME/nix/netrc"
|
|
```
|
|
|
|
**Server (service account):**
|
|
```toml
|
|
issuer = "https://id.guardianproject.info/realms/gp"
|
|
client_id = "nix-cache-server"
|
|
client_secret_file = "/run/secrets/nix-cache-client-secret"
|
|
cache_host = "cache.guardianproject.dev"
|
|
netrc_path = "$XDG_CONFIG_HOME/nix/netrc"
|
|
```
|
|
|
|
Path values support environment variable expansion (`$VAR` and `${VAR}`).
|
|
|
|
`netrc_path` is the path this tool writes tokens to.
|
|
|
|
Configure Nix to read that same path.
|
|
|
|
This supports both cppnix and detsysnix. The latter has [special
|
|
requirements][additionalnetrcsources] around `netrc` files, so set
|
|
`additionalNetrcSources` to include the configured `netrc_path`.
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
nix-cache-login login # authenticate via browser (default command)
|
|
nix-cache-login refresh # refresh token without browser
|
|
nix-cache-login service-account # headless client credentials flow
|
|
nix-cache-login status # show token expiry info
|
|
nix-cache-login logout # revoke tokens and clean up
|
|
```
|
|
|
|
Config path resolution order:
|
|
|
|
1. `--config`
|
|
2. `$NIX_CACHE_LOGIN_CONFIG`
|
|
3. `$XDG_CONFIG_HOME/nix-cache-login/config.toml`
|
|
4. `/etc/nix-cache-login/config.toml` (server fallback)
|
|
|
|
The NixOS server module exports `NIX_CACHE_LOGIN_CONFIG` and installs
|
|
`/etc/nix-cache-login/config.toml` from `services.nix-cache-login-server.configFile`.
|
|
|
|
## Module Integration
|
|
|
|
The Home Manager and NixOS modules in this repo install the package and refresh
|
|
services.
|
|
|
|
Nix and detsysnix daemon configuration stays outside these modules.
|
|
|
|
Set your daemon to read the `netrc_path` configured in `config.toml`.
|
|
|
|
## Maintenance
|
|
|
|
This tool is actively maintained by [Guardian Project](https://guardianproject.info).
|
|
|
|
### Issues
|
|
|
|
For bug reports and feature requests, please use the [Issues][issues] page.
|
|
|
|
### Security
|
|
|
|
For security-related issues, please contact us through our [security policy][sec].
|
|
|
|
[issues]: https://guardianproject.dev/ops/nix-cache-login/issues
|
|
[sec]: https://guardianproject.info/contact/
|
|
[additionalnetrcsources]: https://docs.determinate.systems/determinate-nix/#additionalnetrcsources
|
|
|
|
## License
|
|
|
|
Copyright (c) 2026 Abel Luck <abel@guardianproject.info>
|
|
|
|
This project is licensed under the GNU General Public License v3.0 or later - see the [LICENSE](LICENSE) file for details.
|