From d1c3fa3422b9cb6db404aa3de43572c633bfbee2 Mon Sep 17 00:00:00 2001 From: Alexandre Bouthinon Date: Sat, 9 Jan 2021 03:51:26 +0100 Subject: [PATCH] Update README.md and add demo and dev Docker Compose --- .traefik.yml | 5 +- README.md | 148 ++++++++++++++++++- docker-compose.demo.yml | 99 +++++++++++++ docker-compose.yml => docker-compose.dev.yml | 16 +- 4 files changed, 259 insertions(+), 9 deletions(-) create mode 100644 docker-compose.demo.yml rename docker-compose.yml => docker-compose.dev.yml (80%) diff --git a/.traefik.yml b/.traefik.yml index 6a9d383..4fadfa7 100644 --- a/.traefik.yml +++ b/.traefik.yml @@ -1,7 +1,7 @@ displayName: Basic Auth powered by Kuzzle type: middleware import: github.com/alexandrebouthinon/traefik-kuzzle-auth -summary: Traefik Basic Auth Plugin powered by Kuzzle +summary: Traefik Basic Auth middleware powered by Kuzzle testData: customRealm: "Use a valid Kuzzle user to authenticate" kuzzle: @@ -11,4 +11,5 @@ testData: login: /_login/local getCurrentUser: /_me # With Kuzzle v1 you must use '/users/_me' allowedUsers: - - admin \ No newline at end of file + - admin + - developer \ No newline at end of file diff --git a/README.md b/README.md index 9abf4d3..f61547b 100644 --- a/README.md +++ b/README.md @@ -17,14 +17,154 @@

-## What? + + +- [What?](#what) +- [Why?](#why) +- [How?](#how) + - [Prerequisites](#prerequisites) + - [Demo](#demo) + - [Installation](#installation) + - [Configuration](#configuration) +- [Development](#development) +- [Roadmap](#roadmap) +- [What is Kuzzle?](#what-is-kuzzle) + + + +# What? This is a Traefik Basic Auth Plugin using Kuzzle as authentication provider. -## Why? +# Why? + +*One authentication system to rule them all* :sunglasses: + +Kuzzle offer a complex and fine-grained RBAC authentication system, why do not use it everywhere? + + +# How? +> :warning: At this time, Traefik Plugin system is still an experimental feature use it with caution. You can freeze your Traefik version to increase stability if you want to use this plugin on a real world use case + +## Prerequisites + +* A valid [Traefik Pilot](https://pilot.traefik.io) token for your Traefik instance. +* A running Kuzzle server in which one or more users are configured. + + +## Demo +You can found a demonstration Docker Compose file (`docker-compose.demo.yml`) in the repository root. + +```shell +TRAEFIK_PILOT_TOKEN="xxxx" docker-compose -f docker-compose.demo.yml up -d +``` +This will launch: +* A complete Kuzzle stack (Kuzzle, Elasticsearch and Redis containers) +* A Traefik instance with dashboard and latest released plugin version enabled and only available using `admin` Kuzzle user +* A `whoami` instance available using both `admin` and `developer` Kuzzle users + +Once all containers are started and healthy, you can use the [Kuzzle Admin Console](https://next-console.kuzzle.io) to create your users (`admin` and `developer`). + +## Installation +Declare it in the Traefik configuration: + +**YAML** +```yaml +pilot: + token: "xxxx" +experimental: + plugins: + traefik-kuzzle-auth: + moduleName: github.com/alexandrebouthinon/traefik-kuzzle-auth + version: v0.1.0 +``` + +**TOML** +```toml +[pilot] + token = "xxxx" +[experimental.plugins.fail2ban] + moduleName = "github.com/alexandrebouthinon/traefik-kuzzle-auth" + version = "v0.1.0" +``` + +**CLI** +```shell +--pilot.token=${TRAEFIK_PILOT_TOKEN} +--experimental.plugins.traefik-kuzzle-auth.moduleName=github.com/alexandrebouthinon/traefik-kuzzle-auth +--experimental.plugins.traefik-kuzzle-auth.version=v0.1.0 +``` + +## Configuration + +**YAML** +```yaml +middlewares: + your-well-named-middleware: + plugin: + traefik-kuzzle-auth: + customRealm: "Use a valid Kuzzle user to authenticate" # optional + kuzzle: + url: "http://localhost:7512" # required + routes: # optional + ping: /_publicApi + login: /_login/local + getCurrentUser: /_me # With Kuzzle v1 you must use '/users/_me' + allowedUsers: # optional + - admin + - developer +``` + +**TOML** +```toml +[middlewares] + [middlewares.your-well-named-middleware] + [middlewares.your-well-named-middleware.plugin] + [middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth] + customRealm = "Use a valid Kuzzle user to authenticate" # optional + [middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle] + url = "http://localhost:7512" # required + [middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle.routes] # optional + ping = /_publicApi + login = /_login/local + getCurrentUser = /_me # With Kuzzle v1 you must use '/users/_me' + [middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle.allowedUsers] # optional + - admin + - developer +``` + +**Docker Compose Labels** +```yaml +labels: + - "traefik.http.middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.customRealm=Use a valid Kuzzle user to authenticate" # optional + - "traefik.http.middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle.url=http://kuzzle:7512" # required + - "traefik.http.middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle.routes.ping=/_publicApi" # optional + - "traefik.http.middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle.routes.login=/_login/local" # optional + - "traefik.http.middlewares.your-well-named-middleware.plugin.traefik-kuzzle-auth.kuzzle.routes.getCurrentUser=/_me" # With Kuzzle v1 you must use '/users/_me' (optional) + - "traefik.http.middlewares.kuzzle-auth.plugin.traefik-kuzzle-auth.kuzzle.allowedUsers=admin,developer" # optional +``` + +# Development +You can found a development Docker Compose file (`docker-compose.dev.yml`) in the repository root. + +```shell +TRAEFIK_PILOT_TOKEN="xxxx" docker-compose -f docker-compose.dev.yml up -d +``` +This will launch: +* A complete Kuzzle stack (Kuzzle, Elasticsearch and Redis containers) +* A Traefik instance with dashboard and local plugin enabled and only available using `admin` Kuzzle user +* A `whoami` instance available using both `admin` and `developer` Kuzzle users + +Once all containers are started and healthy, you can use the [Kuzzle Admin Console](https://next-console.kuzzle.io) to create your users (`admin` and `developer`). + +# Roadmap + +- [x] [Users](https://docs.kuzzle.io/core/2/guides/main-concepts/permissions/#users) greenlisting +- [ ] [Profiles](https://docs.kuzzle.io/core/2/guides/main-concepts/permissions/#profiles) greenlisting +- [ ] [Kuzzle API Key](https://docs.kuzzle.io/core/2/guides/advanced/api-keys/) authentication -One authentication system to rule them all. Kuzzle offer a complex and fine-grained RBAC authentication system, why do not use it everywhere? +New ideas are welcome, feel free to fill out an issue and let's discuss it :wink: -## What is Kuzzle? +# What is Kuzzle? Kuzzle is a [generic backend](https://docs.kuzzle.io/core/2/guides/introduction/general-purpose-backend/) offering **the basic building blocks common to every application**. diff --git a/docker-compose.demo.yml b/docker-compose.demo.yml new file mode 100644 index 0000000..261fc41 --- /dev/null +++ b/docker-compose.demo.yml @@ -0,0 +1,99 @@ +version: "3.3" + +services: +#------------------------------------------------------------------------------ +# Traefik proxy configured with plugin dev mode and Dashboard +# NOTE: Only 'admin' user can access Traefik Dashboard +#------------------------------------------------------------------------------ + traefik: + image: "traefik:v2.3" + container_name: "traefik" + depends_on: + kuzzle: + condition: service_healthy + command: + - "--api.dashboard=true" + - "--api.insecure=true" + - "--providers.docker=true" + - "--providers.docker.exposedbydefault=false" + - "--entrypoints.web.address=:80" + - "--pilot.token=${TRAEFIK_PILOT_TOKEN}" + - "--experimental.plugins.traefik-kuzzle-auth.moduleName=github.com/alexandrebouthinon/traefik-kuzzle-auth" + - "--experimental.plugins.traefik-kuzzle-auth.version=v0.1.0" + labels: + - "traefik.enable=true" + - "traefik.http.routers.dashboard.entrypoints=web" + - "traefik.http.routers.dashboard.rule=Host(`traefik.localhost`)" + - "traefik.http.routers.dashboard.service=api@internal" + - "traefik.http.routers.dashboard.middlewares=kuzzle-auth" + - "traefik.http.middlewares.kuzzle-auth.plugin.traefik-kuzzle-auth.kuzzle.url=http://kuzzle:7512" + - "traefik.http.middlewares.kuzzle-auth.plugin.traefik-kuzzle-auth.kuzzle.allowedUsers=admin" + ports: + - "80:80" + volumes: + - "/var/run/docker.sock:/var/run/docker.sock:ro" + - "./:/plugins/go/src/github.com/alexandrebouthinon/traefik-kuzzle-auth" + +#------------------------------------------------------------------------------ +# Kuzzle server stack +#------------------------------------------------------------------------------ + + kuzzle: + image: kuzzleio/kuzzle:2 + ports: + - "7512:7512" + - "1883:1883" + cap_add: + - SYS_PTRACE + depends_on: + redis: + condition: service_healthy + elasticsearch: + condition: service_healthy + healthcheck: + test: ["CMD", "curl", "-f", "http://kuzzle:7512/_publicApi"] + timeout: 10s + interval: 10s + retries: 3 + environment: + - kuzzle_services__storageEngine__client__node=http://elasticsearch:9200 + - kuzzle_services__internalCache__node__host=redis + - kuzzle_services__memoryStorage__node__host=redis + - kuzzle_server__protocols__mqtt__enabled=true + - NODE_ENV=production + + redis: + image: redis:5 + healthcheck: + test: ["CMD", "redis-cli", "ping"] + interval: 1s + timeout: 3s + retries: 30 + + elasticsearch: + image: kuzzleio/elasticsearch:7.4.0 + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:9200"] + interval: 2s + timeout: 2s + retries: 10 + ulimits: + nofile: 65536 + +#------------------------------------------------------------------------------ +# Secured application using plugin +# NOTE: Users 'admin' and 'developer' can access this app +#------------------------------------------------------------------------------ + + whoami: + image: "traefik/whoami" + container_name: "simple-service" + depends_on: + - traefik + labels: + - "traefik.enable=true" + - "traefik.http.routers.whoami.rule=Host(`whoami.localhost`)" + - "traefik.http.routers.whoami.entrypoints=web" + - "traefik.http.routers.whoami.middlewares=kuzzle-auth" + - "traefik.http.middlewares.kuzzle-auth.plugin.traefik-kuzzle-auth.kuzzle.url=http://kuzzle:7512" + - "traefik.http.middlewares.kuzzle-auth.plugin.traefik-kuzzle-auth.kuzzle.allowedUsers=admin,developer" diff --git a/docker-compose.yml b/docker-compose.dev.yml similarity index 80% rename from docker-compose.yml rename to docker-compose.dev.yml index 7857c48..0df06ba 100644 --- a/docker-compose.yml +++ b/docker-compose.dev.yml @@ -2,7 +2,8 @@ version: "3.3" services: #------------------------------------------------------------------------------ -# Traefik proxy configured with plugin dev mode +# Traefik proxy configured with plugin dev mode and Dashboard +# NOTE: Only 'admin' user can access Traefik Dashboard #------------------------------------------------------------------------------ traefik: image: "traefik:v2.3" @@ -11,6 +12,7 @@ services: kuzzle: condition: service_healthy command: + - "--api.dashboard=true" - "--api.insecure=true" - "--providers.docker=true" - "--providers.docker.exposedbydefault=false" @@ -18,9 +20,16 @@ services: - "--pilot.token=${TRAEFIK_PILOT_TOKEN}" - "--experimental.devPlugin.goPath=/plugins/go" - "--experimental.devPlugin.moduleName=github.com/alexandrebouthinon/traefik-kuzzle-auth" + labels: + - "traefik.enable=true" + - "traefik.http.routers.dashboard.entrypoints=web" + - "traefik.http.routers.dashboard.rule=Host(`traefik.localhost`)" + - "traefik.http.routers.dashboard.service=api@internal" + - "traefik.http.routers.dashboard.middlewares=kuzzle-auth" + - "traefik.http.middlewares.kuzzle-auth.plugin.dev.kuzzle.url=http://kuzzle:7512" + - "traefik.http.middlewares.kuzzle-auth.plugin.dev.kuzzle.allowedUsers=admin" ports: - "80:80" - - "8080:8080" volumes: - "/var/run/docker.sock:/var/run/docker.sock:ro" - "./:/plugins/go/src/github.com/alexandrebouthinon/traefik-kuzzle-auth" @@ -73,6 +82,7 @@ services: #------------------------------------------------------------------------------ # Secured application using plugin +# NOTE: Users 'admin' and 'developer' can access this app #------------------------------------------------------------------------------ whoami: @@ -86,4 +96,4 @@ services: - "traefik.http.routers.whoami.entrypoints=web" - "traefik.http.routers.whoami.middlewares=kuzzle-auth" - "traefik.http.middlewares.kuzzle-auth.plugin.dev.kuzzle.url=http://kuzzle:7512" - - "traefik.http.middlewares.kuzzle-auth.plugin.dev.kuzzle.allowedUsers=admin" + - "traefik.http.middlewares.kuzzle-auth.plugin.dev.kuzzle.allowedUsers=admin,developer"