diff --git a/README.md b/README.md index 2c0045b..82368c2 100644 --- a/README.md +++ b/README.md @@ -3,94 +3,38 @@ A helper web-app which talks to one or more [Dex Identity services](https://github.com/coreos/dex) to generate `kubectl` commands for creating and modifying a `kubeconfig`. -* The Web UI supports generating tokens against multiple clusters - * Dev / Staging / Production etc -* Generates appropriate `kubectl config` commands (user/cluster/context) -* SSL Support - -## Screen shots - -![Index Page](examples/index-page.png) - -![Kubeconfig Page](examples/kubeconfig-page.png) - -## Building a binary - - make - -Creates ./bin/dex-k8s-authenticator - -## Building a container - - make container - -## Configuraton - -An example configuration is available [here](examples/config.yaml) - -Configuration also supports environment variables to be used for cluster configuration. - -``` -clusters: - - name: example-cluster - short_description: "Example Cluster" - description: "Example Cluster Long Description..." - client_secret: ${CLIENT_SECRET_EXAMPLE_CLUSTER} -``` +The Web UI supports generating tokens against multiple cluster such as Dev / Staging / Production. -## Running -### Start Dex Server instance - -Follow the example here: -https://github.com/coreos/dex/blob/master/Documentation/getting-started.md - -Start it with using the provided `./examples/dex-server-config-dev.yaml` - -### Start Dex K8s Authenticator - - ./bin/dex-k8s-authenticator --config ./examples/config.yaml - -* Browse to http://localhost:5555 -* Click 'Example Cluster' -* Click 'Log in with Email' -* Login with `admin@example.com` followed by the password `password` -* You should be redirected back to the dex-k8s-authenticator - -## Deploying using Helm - -This project provides [`helm` charts](charts) for deploying both `dex` and -`dex-k8s-authenticator` to your Kubernetes cluster. Instructions are provided -for each chart. - -## Multiple Clusters - -You can run multiple Dex Server instances with different backends if required. +## Also provides +* Helm Charts +* SSL Support +* Linux/Mac/Windows instructions -Just update the `examples/config.yaml` to add an extra cluster to the list with the -required settings. +## Documentation -## SSL +- [Developing and Running](docs/develop.md) +- [Configuration Options](docs/config.md) +- [Using the Helm Charts](docs/helm.md) +- [SSL Support](docs/ssl.md) -### Docker +## Screen shots -Mount a directory containing your self signed certificates to */certs* and the entrypoint will update the local trust store before starting dex-k8s-authenticator. Certificates must have a .crt extension in order to be included by update-ca-certificates. +![Index Page](examples/index-page.png) - docker run --rm -t -i -v /tmp/certs:/certs:ro -v /tmp/config.yml:/tmp/config.yml:ro mintel/dex-k8s-authenticator:latest --config /tmp/config.yml +![Kubeconfig Page](examples/kubeconfig-page.png) -### HELM -Add list of Certificates to your values.yaml file, certificates need to be base64 encoded. +## Contributing +Feel free to raise feature-requests and bugs. PR's are also very welcome. ## Alternatives -A similar web UI that generates `kubectl` configurations without using `dex` to authenticate first -* https://github.com/negz/kuberos - -OIDC helpers that run locally to setup `kubectl`: -* https://github.com/micahhausler/k8s-oidc-helper -* https://github.com/coreos/dex/tree/master/cmd/example-app +- https://github.com/heptiolabs/gangway +- https://github.com/micahhausler/k8s-oidc-helper +- https://github.com/negz/kuberos +- https://github.com/negz/kubehook -A Kubernetes JWT webhook helper with a similar UX to Kuberos -* https://github.com/negz/kubehook +This application is based on the original [example-app](https://github.com/coreos/dex/tree/master/cmd/example-app +) available in the CoreOS Dex repo. \ No newline at end of file diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..8493d04 --- /dev/null +++ b/docs/config.md @@ -0,0 +1,41 @@ +# Configuration + +An example configuration is available [here](../examples/config.yaml) + +## Configuration options + + +| Name | Required | Context | Description | +|-------------------|----------|---------|---------------------------------------------------------------------------------------| +| name | yes | cluster | Internal id of cluster | +| short_description | yes | cluster | Short description of cluster | +| description | yes | cluster | Extended description of cluster | +| client_secret | yes | cluster | OAuth2 client-secret (shared between dex-k8s-auth and dex) | +| client_id | yes | cluster | OAuth2 client-id public identifier (shared between dex-k8s-auth and dex) | +| issuer | yes | cluster | Dex issuer url | +| redirect_uri | yes | cluster | Redirect uri called by dex (defines a callback on dex-k8s-auth) | +| k8s_master_uri | no | cluster | Kubernetes api-server endpoint (used in kubeconfig) | +| k8s_ca_uri | no | cluster | A url pointing to the CA for generating 'certificate-authority' option in kubeconfig | +| k8s_ca_pem | no | cluster | The CA for your k8s server (used in generating instructions) | +| tls_cert | no | root | Path to TLS cert if SSL enabled | +| tls_key | no | root | Path to TLS key if SSL enabled | +| idp_ca_uri | no | root | A url pointing to the CA for generating 'idp-certificate-authority' in the kubeconfig | +| trusted_root_ca | no | root | A list of trusted-root CA's to be loaded by dex-k8s-auth at runtime | +| listen | yes | root | The listen address/port | +| web_path_prefix | no | root | A path-prefix to serve dex-k8s-auth at (defaults to '/') | +| kubectl_version | no | root | A kubectl-version string that is used to provided a download path | +| logo_uri | no | root | A url pointing to a logo image that is displayed in the header | +| debug | no | root | Enable more debug by setting to true | + +## Environment Variable Support + +Environment variables can be included in the configuration. This enables you to pass in dynamic variables or secrets without having to hardcode them. +``` +clusters: + - name: example-cluster + short_description: "Example Cluster" + description: "Example Cluster Long Description..." + client_secret: ${CLIENT_SECRET_EXAMPLE_CLUSTER} +``` + +In this example, `${CLIENT_SECRET_EXAMPLE_CLUSTER}` is substituted at runtime. Must be enclosed by `${...}` diff --git a/docs/develop.md b/docs/develop.md new file mode 100644 index 0000000..5a98408 --- /dev/null +++ b/docs/develop.md @@ -0,0 +1,36 @@ +# Developing and Running + +## Building a binary + + make + +Creates ./bin/dex-k8s-authenticator + +## Building a container + + make container + +## Running it + +### Start a Dex Server instance + +You must have a `dex` instance running before starting `dex-k8s-authenticator`. + +Follow the example here: +https://github.com/coreos/dex/blob/master/Documentation/getting-started.md + +Start it with using the provided `./examples/dex-server-config-dev.yaml` + +### Start Dex K8s Authenticator + + ./bin/dex-k8s-authenticator --config ./examples/config.yaml + +* Browse to http://localhost:5555 +* Click 'Example Cluster' +* Click 'Log in with Email' +* Login with `admin@example.com` followed by the password `password` +* You should be redirected back to the dex-k8s-authenticator + +### Configuration Options + +Additional configuration options are explained [here](config.md) \ No newline at end of file diff --git a/docs/helm.md b/docs/helm.md new file mode 100644 index 0000000..80b7a83 --- /dev/null +++ b/docs/helm.md @@ -0,0 +1,13 @@ +# Helm Charts + +This project provides Helm Charts to install `dex` and `dex-k8s-authenticator` into a Kubernetes cluster. + +Follow the links for specific documentation on each chart: +- [dex-k8s-authenticator](../charts/dex-k8s-authenticator) +- [dex](../charts/dex) + + +Please note, that whilst we maintain our own `dex` chart, there is now an official version available in the main helm charts repo: + +- https://github.com/helm/charts/tree/master/stable/dex + diff --git a/docs/ssl.md b/docs/ssl.md new file mode 100644 index 0000000..bc3a69a --- /dev/null +++ b/docs/ssl.md @@ -0,0 +1,56 @@ +# SSL + +## Adding Trusted Certificates + +There are a couple of ways to have `dex-k8s-authenticator` use trusted certificates. + +### 1. Mounting `/certs/` volume + +`entrypoint.sh` runs `update-ca-certificates` against certificates found in `/certs/` + +They must end in the extension `.crt` + +If using docker, you can mount a volume like so: + +``` +docker run --rm -t -i \ + -v /tmp/certs:/certs:ro \ + -v /tmp/config.yml:/tmp/config.yml:ro \ + mintel/dex-k8s-authenticator:latest --config /tmp/config.yml +``` + +### 2. `trusted_root_ca` config option + +You can define multiple certificates via the configuration file: + +```yaml +trusted_root_ca: + - | + -----BEGIN CERTIFICATE----- + MIIGJDCCBAygAwI... + -----END CERTIFICATE----- +``` + +## Serving requests on SSL + +The configuration file requires the following: + + +```yaml +listen: https://127.0.0.1:5555 +tls_cert: /path/to/dex-client.crt +tls_key: /path/to/dex-client.key +``` + +- Note, the `listen` option is using `https` not `http` +- You need to supply both `.crt` and the `.key` files + +The `.crt` and `.key` file can be mounted as a volume. + +## Helm Charts + +### dex-k8a-authenticator + +Our Helm chart providers options for both using trusted root certs, and serving requests on SSL. + +For more information on SSL support in our Helm chart, please read [here](../charts/dex-k8s-authenticator) \ No newline at end of file