91 lines
2.5 KiB
Markdown
91 lines
2.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.info"
|
||
|
|
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 = "..."
|
||
|
|
cache_host = "cache.guardianproject.info"
|
||
|
|
netrc_path = "$XDG_CONFIG_HOME/nix/netrc"
|
||
|
|
```
|
||
|
|
|
||
|
|
Path values support environment variable expansion (`$VAR` and `${VAR}`).
|
||
|
|
|
||
|
|
## 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
|
||
|
|
```
|
||
|
|
|
||
|
|
## 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/
|
||
|
|
|
||
|
|
## 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.
|