From 5dc95b20c7141e4a5ca79a727658514fc2d21318 Mon Sep 17 00:00:00 2001 From: Brandon Philips Date: Mon, 9 Nov 2015 03:17:55 +0100 Subject: [PATCH] examples: improve docs in README Make the docs feel more like a tutorial and add some more context. --- examples/README.md | 89 ++++++++++++++++++++---------------- static/fixtures/clients.json | 9 +++- 2 files changed, 57 insertions(+), 41 deletions(-) diff --git a/examples/README.md b/examples/README.md index a6d86481..426c5432 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,49 +1,60 @@ -Running Examples -=== - -The quickest way to start experimenting with dex is to run a single dex-worker -locally, with an in-process database, and then interacting with it using the -example programs in this directory. +# Running Examples +The quickest way to start experimenting with dex is to run a single dex-worker locally, with an in-process database, and then interact with it using the example programs in this directory. ## Build Everything and Start dex-worker -This section is required for both the Example App and the Example CLI. +First, build the example webapp client and example CLI client. -1. Build everything: - ``` - ./build - ``` - -1. Copy the various example configurations. - ``` - cp static/fixtures/connectors.json.sample static/fixtures/connectors.json - cp static/fixtures/users.json.sample static/fixtures/users.json - cp static/fixtures/emailer.json.sample static/fixtures/emailer.json - ``` - -1. Run dex_worker in local mode. - ``` - ./bin/dex-worker --no-db & - ``` +``` +./build +``` +Now copy the example configurations into place to get dex configured. +You can customize these later but the defaults should work fine. -## Example App +``` +cp static/fixtures/connectors.json.sample static/fixtures/connectors.json +cp static/fixtures/users.json.sample static/fixtures/users.json +cp static/fixtures/emailer.json.sample static/fixtures/emailer.json +``` -1. Build and run example app webserver, pointing the discovery URL to local Dex, and +With `dex-worker` configuration in place we can start dex in local mode. + +``` +./bin/dex-worker --no-db & +``` + +## Example Webapp Client + +Build and run the example app webserver by pointing the discovery URL to local Dex, and supplying the client information from `./static/fixtures/clients.json` into the flags. - ``` - ./bin/example-app --client-id=XXX --client-secret=secrete --discovery=http://127.0.0.1:5556 & - ``` -1. Navigate browser to `http://localhost:5555` and click "login" link -1. Click "Login with Local" -1. Enter in sample credentials from `static/fixtures/connectors.json`: - ``` - email: elroy77@example.com - password: bones - ``` -1. Observe user information in example app. - -## Example CLI -*TODO* +``` +./bin/example-app \ + --client-id=example-app \ + --client-secret=example-app-secret \ + --discovery=http://127.0.0.1:5556 +``` + +Visit [http://localhost:5555](http://localhost:5555) in your browser and click "login" link. +Next click "Login with Local" and enter the sample credentials from `static/fixtures/connectors.json`: + +``` +email: elroy77@example.com +password: bones +``` + +The example app will dump out details of the JWT issued by Dex which means that authentication was successful and the application has authenticated you as a valid user. +You can play with adding additional users in connectors.json and users.json. + +## Example CLI Client + +The example CLI will start, connect to the Dex instance to gather discovery information, listen on `localhost:8000`, and then acquire a client credentials JWT and print it out. + +``` +./bin/example-cli \ + --client-id example-cli + --client-secret examplie-cli-secret + --discovery=http://127.0.0.1:5556 +``` diff --git a/static/fixtures/clients.json b/static/fixtures/clients.json index 4a89fada..bc510caa 100644 --- a/static/fixtures/clients.json +++ b/static/fixtures/clients.json @@ -5,8 +5,13 @@ "redirectURLs": ["http://127.0.0.1:5555/callback"] }, { - "id": "core-update", - "secret": "secrete", + "id": "example-app", + "secret": "example-app-secret", + "redirectURLs": ["http://127.0.0.1:5555/callback"] + }, + { + "id": "example-cli", + "secret": "example-cli-secret", "redirectURLs": ["http://127.0.0.1:8000/admin/v1/oauth/login"] }, {