This is an unofficial repository to provide tools, packages and instructions for Athenz.
It is currently owned and maintained by ctyano.
The athenzusercert CLI interacts with an OAuth 2.0 Identity Provider to obtain an OAuth access token.
It then communicates with the Certificate Signer API (e.g., certsigner-envoy) to retrieve an X.509 certificate.
This certificate is compatible with Athenz and can be used to authenticate the user.
Install from the community Homebrew tap:
brew tap athenz-community/athenz-user-cert https://github.com/athenz-community/athenz-user-cert
brew install athenz-community/athenz-user-cert/athenz-user-cert
Or install from the personal Homebrew tap:
brew tap ctyano/athenz-user-cert https://github.com/ctyano/athenz-user-cert
brew install ctyano/athenz-user-cert/athenz-user-cert
Homebrew formulae are published by GoReleaser to this repository's Formula directory.
The explicit tap URL is required because this project does not use a separate homebrew-athenz-user-cert tap repository.
https://github.com/ctyano/athenz-user-cert/releases
make
The CLI can read optional YAML configuration from $HOME/.athenz/config.yaml.
Set ATHENZ_CONFIG_PATH to use another file.
Values are applied in this order:
command line flags > environment variables > config.yaml > build-time defaults
Example:
signer:
name: zts
athenz:
cn_mode: user
user_domain: user
external_id_domain: external.id.domain
endpoint: https://zts.example.com/zts/v1/usercert
ca_endpoint: https://zts.example.com/zts/v1/ca
signer_tls_ca_path: /usr/local/etc/athenz/zts-server-ca.pem
oidc:
issuer: https://issuer.example.com
client_id: athenz-user-cert
scopes: openid email profile
listen_address: :8080
access_token_cache_expiry_minutes: 15
external_id_claim: email
close_window_delay: 0
zts:
sign_url: https://zts.example.com/zts/v1
external_member_cert_endpoint: https://zts.example.com/zts/v1/extmembercert
timeout: 10Common environment variable overrides include ATHENZ_API_URL,
ATHENZ_CA_ENDPOINT, ATHENZ_SIGNER_TLS_CA_PATH, ATHENZ_OIDC_ISSUER,
ATHENZ_OIDC_ACCESS_TOKEN_CACHE_EXPIRY_MINUTES, and ATHENZ_ZTS_SIGN_URL.
Use ATHENZ_CN_MODE to choose the derived Athenz User
Certificate CN mode: user produces <user_domain>.<username>, and external
produces <external_id_domain>:ext.<external_id>. For the zts signer,
zts.sign_url / ATHENZ_ZTS_SIGN_URL is treated as the ZTS API base URL:
user mode uses /usercert, and external mode uses /extmembercert. Legacy
values ending in /usercert are normalized. Use -zts-external-member-cert-endpoint,
ATHENZ_ZTS_EXTERNAL_MEMBER_CERT_ENDPOINT, or zts.external_member_cert_endpoint to override
the external member certificate endpoint. Use
ATHENZ_USER_DOMAIN for user mode. Use ATHENZ_EXTERNAL_ID_DOMAIN and
ATHENZ_EXTERNAL_ID_CLAIM for external mode.
The OIDC callback server listens on oidc.listen_address (:8080 by default).
When that port is already in use the server automatically shifts to the next
free port. Use oidc.close_window_delay / ATHENZ_OIDC_CLOSE_WINDOW_DELAY /
-oidc-close-window-delay to opt into auto-closing the browser tab after a
successful callback: the success page shows a countdown and calls
window.close(), and on macOS a detached AppleScript also closes the Chrome or
Safari tab whose URL starts with the local callback prefix (best-effort; the
first run may ask for the macOS Automation permission, and Chrome and Safari
are the only browsers covered). The default 0 disables auto-close and keeps
the static "You may close this window now." message.
Use -oidc-issuer https://issuer.example.com to override the OIDC issuer for a
single CLI execution. Cached access tokens are reused only while both their JWT
exp claim and iat age are valid. The maximum cache age defaults to 15 minutes
and can be changed with -oidc-access-token-cache-expiry-minutes,
-oidc-token-expiry-minutes, ATHENZ_OIDC_ACCESS_TOKEN_CACHE_EXPIRY_MINUTES,
ATHENZ_OIDC_TOKEN_EXPIRY_MINUTES, oidc.access_token_cache_expiry_minutes,
oidc.token_expiry_minutes, or the ZTS-compatible config path
athenz.zts.user_cert.token_expiry_minutes.