From ec87a295591eb762ffa214f9c0da9ed7c9485721 Mon Sep 17 00:00:00 2001 From: Ben Burwell Date: Tue, 14 Apr 2020 00:18:46 -0400 Subject: Simplify further --- README.md | 134 +++----------------------------------------------------------- 1 file changed, 5 insertions(+), 129 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 8387e5b..76953cd 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # Cashier -[![Build Status](https://travis-ci.org/nsheridan/cashier.svg?branch=master)](https://travis-ci.org/nsheridan/cashier) - - [Cashier](#cashier) - [How it works](#how-it-works) - [Installing](#installing) @@ -10,17 +8,9 @@ - [Server](#server) - [Client](#client) - [Configuration](#configuration) - - [server](#server-1) - - [database](#database) - - [auth](#auth) - - [Provider-specific options](#provider-specific-options) - - [ssh](#ssh) - - [aws](#aws) - - [vault](#vault) - [Usage](#usage) - [Using cashier client](#using-cashier-client) - [Configuring SSH](#configuring-ssh) - - [Revoking certificates](#revoking-certificates) - [Future Work](#future-work) - [Contributing](#contributing) @@ -88,103 +78,20 @@ Note: Cashier has only been tested on macOS and Linux. # Configuration Configuration is divided into different sections: `server`, `auth`, `ssh`, and `aws`. -## A note on files: -For any option that takes a file path as a parameter (e.g. SSH signing key, TLS key, TLS cert), the path can be one of: - -- A relative or absolute filesystem path e.g. `/data/ssh_signing_key`, `tls/server.key`. -- An AWS S3 bucket + object path starting with `/s3/` e.g. `/s3/my-bucket/ssh_signing_key`. You should add an [aws](#aws) config as needed. -- A Google GCS bucket + object path starting with `/gcs/` e.g. `/gcs/my-bucket/ssh_signing_key`. -- A [Vault](https://www.vaultproject.io) path + key starting with `/vault/` e.g. `/vault/secret/cashier/ssh_signing_key`. You should add a [vault](#vault) config as needed. - -Exception to this: the `http_logfile` option **ONLY** writes to local files. - ## server -- `use_tls` : boolean. If this is set then either `tls_key` and `tls_cert` are required, or `letsencrypt_servername` is required. -- `tls_key` : string. Path to the TLS key. See the [note](#a-note-on-files) on files above. -- `tls_cert` : string. Path to the TLS cert. See the [note](#a-note-on-files) on files above. -- `letsencrypt_servername`: string. If set will request a certificate from LetsEncrypt. This should match the expected FQDN of the server. -- `letsencrypt_cachedir`: string. Directory to cache the LetsEncrypt certificate. See the [note](#a-note-on-files) on files above. - `address` : string. IP address to listen on. If unset the server listens on all addresses. - `port` : int. Port to listen on. - `user` : string. User to which the server drops privileges to. **Note** Dropping privileges might not work as expected as some [threads may retain their privileges due to the limitations of the Go runtime](https://github.com/golang/go/issues/1435). - `cookie_secret`: string. Authentication key for the session cookie. This can be a secret stored in a [vault](https://www.vaultproject.io/) using the form `/vault/path/key` e.g. `/vault/secret/cashier/cookie_secret`. - `csrf_secret`: string. Authentication key for CSRF protection. This can be a secret stored in a [vault](https://www.vaultproject.io/) using the form `/vault/path/key` e.g. `/vault/secret/cashier/csrf_secret`. - `http_logfile`: string. Path to the HTTP request log. Logs are written in the [Common Log Format](https://en.wikipedia.org/wiki/Common_Log_Format). The only valid destination for logs is a local file path. -- `require_reason`: bool. Require the client to provide a reason when requesting a certificate. Defaults to `false`. -- `database`: See below. - -### database - -The database is used to record issued certificates for audit and revocation purposes. - -- `type` : string. One of `mysql`, `sqlite` or `mem`. -- `address` : string. (`mysql` only) Hostname and optional port of the database server. -- `username` : string. Database username. -- `password` : string. Database password. This can be a secret stored in a [vault](https://www.vaultproject.io/) using the form `/vault/path/key` e.g. `/vault/secret/cashier/mysql_password`. -- `filename` : string. (`sqlite` only). Path to sqlite database. -- `dbname`: string (`mysql` only). Name of database to use. - -Examples: -``` -server { - database { - type = "mysql" - address = "my-db-host.corp" - username = "user" - password = "passwd" - dbname = "cashier_production" - } - - database { - type = "mem" - } - - database { - type = "sqlite" - filename = "/data/cashier.db" - } -} -``` -Cashierd **will not** create the database for you - you need to create this. On startup cashierd will execute any schema changes. -Obviously you should setup a role user for running in prodution. - -## auth -- `provider` : string. Name of the oauth provider. Valid providers are currently "google", "github" and "gitlab". -- `oauth_client_id` : string. Oauth Client ID. This can be a secret stored in a [vault](https://www.vaultproject.io/) using the form `/vault/path/key` e.g. `/vault/secret/cashier/oauth_client_id`. -- `oauth_client_secret` : string. Oauth secret. This can be a secret stored in a [vault](https://www.vaultproject.io/) using the form `/vault/path/key` e.g. `/vault/secret/cashier/oauth_client_secret`. +## github +- `oauth_client_id` : string. Oauth Client ID. +- `oauth_client_secret` : string. Oauth secret. - `oauth_callback_url` : string. URL that the Oauth provider will redirect to after user authorisation. The path is hardcoded to `"/auth/callback"` in the source. -- `provider_opts` : object. Additional options for the provider. -- `users_whitelist` : array of strings. Optional list of whitelisted usernames. If missing, all users of your current domain/organization are allowed to authenticate against cashierd. For Google auth a user is an email address. For GitHub auth a user is a GitHub username. - -### Provider-specific options - -Oauth providers can support provider-specific options - e.g. to ensure organization membership. -Options are set in the `provider_opts` hash. - -Example: - -``` -auth { - provider = "google" - provider_opts { - domain = "example.com" - } -} -``` - -Supported options: - - -| Provider | Option | Notes | -|---------:|-------------:|----------------------------------------------------------------------------------------------------------------------------------------| -| Github | organization | If this is unset then you must whitelist individual users using `users_whitelist`. The oauth client and secrets should be issued by the specified organization. | -| Gitlab | allusers | Allow all valid users to get signed keys. Only allowed if siteurl set. | -| Gitlab | group | If `allusers` and this are unset then you must whitelist individual users using `users_whitelist`. Otherwise the user must be a member of this group. | -| Gitlab | siteurl | Optional. The url of the Gitlab site. Default: `https://gitlab.com/` | -| Google | domain | If this is unset then you must whitelist individual email addresses using `users_whitelist`. | -| Microsoft | groups | Comma separated list of valid groups. | -| Microsoft | tenant | The domain name of the Office 365 account. | +- `users_whitelist` : array of strings. Optional list of whitelisted GitHub usernames. +- `orgs_whitelist` : array of strings. Optional list of whitelisted GitHub orgs. ## ssh - `signing_key`: string. Path to the certificate signing ssh private key. Use `ssh-keygen` to create the key and store it somewhere safe. See also the [note](#a-note-on-files) on files above. @@ -192,21 +99,6 @@ Supported options: - `max_age`: string. If set the server will not issue certificates with an expiration value longer than this, regardless of what the client requests. Must be a valid Go [`time.Duration`](https://golang.org/pkg/time/#ParseDuration) string. - `permissions`: array of string. Specify the actions the certificate can perform. See the [`-O` option to `ssh-keygen(1)`](http://man.openbsd.org/OpenBSD-current/man1/ssh-keygen.1) for a complete list. e.g. `permissions = ["permit-pty", "permit-port-forwarding", force-command=/bin/ls", "source-address=192.168.0.0/24"]` -## aws -AWS configuration is only needed for accessing signing keys stored on S3, and isn't totally necessary even then. -The S3 client can be configured using any of [the usual AWS-SDK means](https://github.com/aws/aws-sdk-go/wiki/configuring-sdk) - environment variables, IAM roles etc. -It's strongly recommended that signing keys stored on S3 be locked down to specific IAM roles and encrypted using KMS. - -- `region`: string. AWS region the bucket resides in, e.g. `us-east-1`. -- `access_key`: string. AWS Access Key ID. This can be a secret stored in a [vault](https://www.vaultproject.io/) using the form `/vault/path/key` e.g. `/vault/secret/cashier/aws_access_key`. -- `secret_key`: string. AWS Secret Key. This can be a secret stored in a [vault](https://www.vaultproject.io/) using the form `/vault/path/key` e.g. `/vault/secret/cashier/aws_secret_key`. - -## vault -Vault support is currently a work-in-progress. - -- `address`: string. URL to the vault server. -- `token`: string. Auth token for the vault. - # Usage Cashier comes in two parts, a [cli](cmd/cashier) and a [server](cmd/cashierd). The server is configured using a HCL configuration file - [example](example-server.conf). @@ -248,22 +140,6 @@ TrustedUserCAKeys /etc/ssh/ca.pub ``` where `/etc/ssh/ca.pub` contains the public part of your signing key. -If you wish to use certificate revocation you need to set the `RevokedKeys` option in sshd_config - see the next section. - -## Revoking certificates -When a certificate is signed a record is kept in the configured database. You can view issued certs at `http(s):///admin/certs` and also revoke them. -The revocation list is served at `http(s):///revoked`. To use it your sshd_config must have `RevokedKeys` set: -``` -RevokedKeys /etc/ssh/revoked_keys -``` -See the [`RevokedKeys` option in the sshd_config man page](http://man.openbsd.org/OpenBSD-current/man5/sshd_config) for more. -Keeping the revoked list up to date can be done with a cron job like: -``` -*/10 * * * * * curl -s -o /etc/ssh/revoked_keys https://sshca.example.com/revoked -``` - -Remember that the `revoked_keys` file **must** exist and **must** be readable by the sshd or else all ssh authentication will fail. - # Future Work - Host certificates - only user certificates are supported at present. -- cgit v1.2.3