diff --git a/Documentation/api.md b/Documentation/api.md
index a7a5612bc0b94a591c9735ea34904c46ba2f3d5a..5171b5e1b8d805e5b646b1cc2711134fbf37c360 100644
--- a/Documentation/api.md
+++ b/Documentation/api.md
@@ -107,7 +107,7 @@ Between v1 and v2, dex switched from REST to gRPC. This largely stemmed from pro
Many arguments _against_ gRPC cite short term convenience rather than production use cases. Though this is a recognized shortcoming, dex already implements many features for developer convenience. For instance, users who wish to manually edit clients during testing can use the `staticClients` config field instead of the API.
[grpc]: http://www.grpc.io/
-[api-proto]: https://github.com/coreos/dex/blob/v2.0.0-alpha.5/api/api.proto
+[api-proto]: ../api/api.proto
[protoc]: https://github.com/google/protobuf/releases
[protoc-gen-go]: https://github.com/golang/protobuf
[google-apis]: https://github.com/google/apis-client-generator
diff --git a/Documentation/getting-started.md b/Documentation/getting-started.md
new file mode 100644
index 0000000000000000000000000000000000000000..25cac5abffc3011d30a89adacca0a3717fa4bba1
--- /dev/null
+++ b/Documentation/getting-started.md
@@ -0,0 +1,47 @@
+# Getting started
+
+## Building the dex binary
+
+Dex requires a Go installation and a GOPATH configured. For setting up a Go workspace, refer to the [official documentation][go-setup]. Clone it down the correct place, and simply type `make` to compile the dex binary.
+
+```
+$ git clone https://github.com/coreos/dex.git $GOPATH/src/github.com/coreos/dex
+$ cd $GOPATH/src/github.com/coreos/dex
+$ make
+```
+
+## Configuration
+
+Dex exclusively pulls configuration options from a config file. Use the [example config][example-config] file found in the `examples/` directory to start an instance of dex with an in-memory data store and a set of predefined OAuth2 clients.
+
+```
+./bin/dex serve examples/config-dev.yaml
+```
+
+The [example config][example-config] file documents many of the configuration options through inline comments. For extra config options, look at that file.
+
+## Running a client
+
+Dex operates like most other OAuth2 providers. Users are redirected from a client app to dex to login. Dex ships with an example client app (also built with the `make` command), for testing and demos.
+
+By default, the example client is configured with the same OAuth2 credentials defined in `examples/config-dev.yaml` to talk to dex. Running the example app will cause it to query dex's [discovery endpoint][oidc-discovery] and determine the OAuth2 endpoints.
+
+```
+./bin/example-app
+```
+
+Login to dex through the example app using the following steps.
+
+1. Navigate to the example app in your browser at http://localhost:5555/ in your browser.
+2. Hit "login" on the example app to be redirected to dex.
+3. Choose the "Login with Email" and enter "admin@example.com" and "password"
+4. Approve the example app's request.
+5. See the resulting token the example app claims from dex.
+
+## Further reading
+
+Check out the Documentation directory for further reading on setting up different storages, interacting with the dex API, intros for OpenID Connect, and logging in through other identity providers such as Google, GitHub, or LDAP.
+
+[go-setup]: https://golang.org/doc/install
+[example-config]: ../examples/config-dev.yaml
+[oidc-discovery]: https://openid.net/specs/openid-connect-discovery-1_0-17.html#ProviderMetadata
diff --git a/Documentation/logos/dex-glyph-bw.png b/Documentation/logos/dex-glyph-bw.png
new file mode 100644
index 0000000000000000000000000000000000000000..0934cbb715435353158fec86b9b774e91fbf2e5b
Binary files /dev/null and b/Documentation/logos/dex-glyph-bw.png differ
diff --git a/Documentation/logos/dex-glyph-bw.svg b/Documentation/logos/dex-glyph-bw.svg
new file mode 100644
index 0000000000000000000000000000000000000000..57e0695f6943d1d7b24d25eae9a4ca1a4ecc52be
--- /dev/null
+++ b/Documentation/logos/dex-glyph-bw.svg
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 17.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+ width="112px" height="109px" viewBox="0 0 112 109" enable-background="new 0 0 112 109" xml:space="preserve">
+<g>
+ <path d="M88.345,51.574c7.588-3.55,12.764-10.49,14.175-18.53C96.396,19.395,84.663,9.054,70.094,4.851
+ c4.923,7.133,7.272,15.583,6.771,24.17C83.311,34.466,87.716,42.55,88.345,51.574z M27.27,38.542
+ c-8.207-1.045-16.333,1.973-21.858,8.054C3.23,61.683,7.869,76.84,18.099,88.158c-0.527-8.64,1.856-17.306,6.831-24.483
+ C22.19,55.048,23.32,45.944,27.27,38.542z M33.01,76.928c-2.997,8.079-1.755,17.193,3.642,24.215
+ c12.155,4.943,26.051,5.146,38.643-0.035c-7.818-2.516-14.886-7.518-19.887-14.731C47.233,86.23,39.124,83.032,33.01,76.928z
+ M63.122,22.202c-1.507-8.158-7.053-15.383-15.23-18.732C33.778,5.711,20.745,13.966,12.76,26.631
+ c8.115-2.487,16.74-2.178,24.529,0.639C44.816,22.008,54.043,20.144,63.122,22.202z M85.891,66.457
+ c-3.086,7.399-8.722,13.188-15.678,16.61c6.194,5.604,14.805,7.758,22.852,5.834c9.054-9.587,13.884-22.198,13.9-35.009
+ C101.549,60.198,94.131,64.67,85.891,66.457z"/>
+ <g>
+ <circle cx="56.035" cy="53.892" r="15.972"/>
+ </g>
+</g>
+</svg>
diff --git a/Documentation/logos/dex-glyph-color.png b/Documentation/logos/dex-glyph-color.png
new file mode 100644
index 0000000000000000000000000000000000000000..bcd5f21bfdcd445325d013080c1c5bf339de11ae
Binary files /dev/null and b/Documentation/logos/dex-glyph-color.png differ
diff --git a/Documentation/logos/dex-glyph-color.svg b/Documentation/logos/dex-glyph-color.svg
new file mode 100644
index 0000000000000000000000000000000000000000..2668039fe9ef6b18737c54ddc29d8ace9dd5bae2
--- /dev/null
+++ b/Documentation/logos/dex-glyph-color.svg
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 17.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+ width="112px" height="109px" viewBox="0 0 112 109" enable-background="new 0 0 112 109" xml:space="preserve">
+<g>
+ <path fill="#449FD8" d="M88.345,51.574c7.588-3.55,12.764-10.49,14.175-18.53C96.396,19.395,84.663,9.054,70.094,4.851
+ c4.923,7.133,7.272,15.583,6.771,24.17C83.311,34.466,87.716,42.55,88.345,51.574z M27.27,38.542
+ c-8.207-1.045-16.333,1.973-21.858,8.054C3.23,61.683,7.869,76.84,18.099,88.158c-0.527-8.64,1.856-17.306,6.831-24.483
+ C22.19,55.048,23.32,45.944,27.27,38.542z M33.01,76.928c-2.997,8.079-1.755,17.193,3.642,24.215
+ c12.155,4.943,26.051,5.146,38.643-0.035c-7.818-2.516-14.886-7.518-19.887-14.731C47.233,86.23,39.124,83.032,33.01,76.928z
+ M63.122,22.202C61.615,14.044,56.069,6.819,47.892,3.47C33.778,5.711,20.745,13.966,12.76,26.631
+ c8.115-2.487,16.74-2.178,24.529,0.639C44.816,22.008,54.043,20.144,63.122,22.202z M85.891,66.457
+ c-3.086,7.399-8.722,13.188-15.678,16.61c6.194,5.604,14.805,7.758,22.852,5.834c9.054-9.587,13.884-22.198,13.9-35.009
+ C101.549,60.198,94.131,64.67,85.891,66.457z"/>
+ <g>
+ <circle fill="#F04D5C" cx="56.035" cy="53.892" r="15.972"/>
+ </g>
+</g>
+</svg>
diff --git a/Documentation/logos/dex-glyph-white.png b/Documentation/logos/dex-glyph-white.png
new file mode 100644
index 0000000000000000000000000000000000000000..0a7215c9ac2eabc42141dc7f018436cecafebb36
Binary files /dev/null and b/Documentation/logos/dex-glyph-white.png differ
diff --git a/Documentation/logos/dex-glyph-white.svg b/Documentation/logos/dex-glyph-white.svg
new file mode 100644
index 0000000000000000000000000000000000000000..294813667575cb40ad98bf1fdc5f72ec2cdc3650
--- /dev/null
+++ b/Documentation/logos/dex-glyph-white.svg
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 17.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+ width="112px" height="109px" viewBox="0 0 112 109" enable-background="new 0 0 112 109" xml:space="preserve">
+<g>
+ <g>
+ <path fill="#FFFFFF" d="M88.345,51.878c7.588-3.55,12.764-10.49,14.175-18.53C96.396,19.699,84.663,9.358,70.094,5.155
+ c4.923,7.133,7.272,15.583,6.771,24.17C83.311,34.77,87.716,42.854,88.345,51.878z M27.27,38.845
+ c-8.207-1.045-16.333,1.973-21.858,8.054C3.23,61.987,7.869,77.144,18.099,88.462c-0.527-8.64,1.856-17.306,6.831-24.483
+ C22.19,55.352,23.32,46.248,27.27,38.845z M33.01,77.231c-2.997,8.079-1.755,17.193,3.642,24.215
+ c12.155,4.943,26.051,5.146,38.643-0.035c-7.818-2.516-14.886-7.518-19.887-14.731C47.233,86.533,39.124,83.336,33.01,77.231z
+ M63.122,22.506c-1.506-8.158-7.053-15.383-15.229-18.732C33.778,6.015,20.745,14.27,12.76,26.935
+ c8.115-2.487,16.74-2.178,24.529,0.639C44.816,22.312,54.043,20.448,63.122,22.506z M85.891,66.761
+ c-3.086,7.399-8.722,13.188-15.678,16.61c6.194,5.604,14.805,7.758,22.852,5.834c9.054-9.587,13.884-22.198,13.9-35.009
+ C101.549,60.502,94.131,64.974,85.891,66.761z"/>
+ <g>
+ <circle fill="#FFFFFF" cx="56.035" cy="54.196" r="15.972"/>
+ </g>
+ </g>
+</g>
+</svg>
diff --git a/Documentation/logos/dex-horizontal-color.png b/Documentation/logos/dex-horizontal-color.png
new file mode 100644
index 0000000000000000000000000000000000000000..98a85a9643f76fae3ab4dc90a92c91a003263cf9
Binary files /dev/null and b/Documentation/logos/dex-horizontal-color.png differ
diff --git a/Documentation/logos/dex-horizontal-color.svg b/Documentation/logos/dex-horizontal-color.svg
new file mode 100644
index 0000000000000000000000000000000000000000..4f8ca6b5eb252b01d098d4492ac838de38ecaa99
--- /dev/null
+++ b/Documentation/logos/dex-horizontal-color.svg
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 17.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+ width="298px" height="109px" viewBox="0 0 298 109" enable-background="new 0 0 298 109" xml:space="preserve">
+<g>
+ <g>
+ <path fill="#231F20" d="M183.537,67.645c0-5.045,0.777-9.561,2.332-13.556c1.555-3.992,3.614-7.377,6.179-10.151
+ c2.564-2.774,5.486-4.896,8.764-6.368c3.279-1.469,6.684-2.206,10.214-2.206c3.866,0,7.334,0.674,10.404,2.017
+ c3.067,1.346,5.631,3.279,7.692,5.801c2.058,2.522,3.634,5.549,4.728,9.079c1.092,3.532,1.64,7.484,1.64,11.854
+ c0,2.269-0.126,4.161-0.378,5.673H193.75c0.421,6.642,2.46,11.897,6.116,15.763c3.658,3.869,8.427,5.801,14.313,5.801
+ c2.941,0,5.653-0.441,8.133-1.324c2.479-0.883,4.855-2.038,7.125-3.467l3.656,6.808c-2.692,1.683-5.673,3.153-8.953,4.414
+ c-3.278,1.261-7.021,1.891-11.222,1.891c-4.121,0-7.966-0.736-11.539-2.206c-3.574-1.47-6.684-3.573-9.331-6.305
+ c-2.648-2.731-4.729-6.072-6.242-10.025C184.293,77.187,183.537,72.689,183.537,67.645z M226.41,62.98
+ c0-6.305-1.324-11.117-3.971-14.439c-2.648-3.321-6.368-4.981-11.159-4.981c-2.187,0-4.269,0.441-6.242,1.324
+ c-1.976,0.883-3.763,2.145-5.36,3.784c-1.598,1.639-2.922,3.656-3.971,6.052c-1.053,2.397-1.746,5.152-2.082,8.261H226.41z"/>
+ <path fill="#231F20" d="M255.79,66.132l-18.536-29.256h11.222l8.196,13.493c0.924,1.683,1.891,3.385,2.9,5.108
+ c1.01,1.724,2.06,3.426,3.153,5.106h0.504c0.924-1.68,1.849-3.382,2.774-5.106c0.925-1.723,1.849-3.425,2.775-5.108l7.44-13.493
+ h10.844l-18.536,30.39l19.923,30.895h-11.222l-8.953-14.25c-1.094-1.847-2.187-3.697-3.279-5.549
+ c-1.094-1.847-2.228-3.656-3.404-5.421h-0.504c-1.094,1.765-2.145,3.552-3.153,5.358c-1.009,1.809-2.017,3.68-3.026,5.612
+ l-8.323,14.25H235.74L255.79,66.132z"/>
+ <path fill="#231F20" d="M181.116,91.189c-1.091,0.243-1.576,0.243-2.182,0.243c-1.253,0-2.412-0.908-2.71-3.174V8.378h-10.467
+ v23.581l0.449,9.298v1.124c-2.672-2.164-5.302-3.875-7.888-5.127c-2.608-1.261-5.675-1.891-9.207-1.891
+ c-3.53,0-6.893,0.756-10.088,2.269c-3.196,1.514-6.011,3.658-8.449,6.431c-2.439,2.774-4.394,6.159-5.864,10.151
+ c-1.472,3.995-2.206,8.471-2.206,13.43c0,10.258,2.29,18.158,6.873,23.707c4.581,5.549,10.739,8.323,18.473,8.323
+ c3.614,0,6.999-0.862,10.152-2.585c3.152-1.723,5.946-3.762,8.386-6.116h0.189c1.006,5.65,4.144,8.701,10.175,8.701
+ c2.667,0,4.364-0.363,5.697-0.969L181.116,91.189z M165.757,82.525c-2.522,2.859-5.043,4.981-7.565,6.368
+ c-2.523,1.387-5.215,2.08-8.07,2.08c-5.382,0-9.542-2.058-12.485-6.179c-2.944-4.118-4.414-9.876-4.414-17.275
+ c0-3.53,0.462-6.725,1.388-9.583c0.924-2.857,2.184-5.316,3.782-7.377c1.596-2.06,3.467-3.658,5.612-4.792
+ c2.143-1.135,4.433-1.702,6.873-1.702c2.522,0,4.98,0.485,7.377,1.45c2.395,0.968,4.895,2.629,7.502,4.981V82.525z"/>
+ </g>
+ <g>
+ <path fill="#449FD8" d="M93.012,51.878c7.588-3.55,12.764-10.49,14.175-18.53C101.063,19.699,89.329,9.358,74.76,5.155
+ c4.923,7.133,7.272,15.583,6.771,24.17C87.978,34.77,92.383,42.854,93.012,51.878z M31.937,38.845
+ c-8.207-1.045-16.333,1.973-21.858,8.054c-2.183,15.088,2.457,30.245,12.687,41.563c-0.527-8.64,1.856-17.306,6.831-24.483
+ C26.857,55.352,27.987,46.248,31.937,38.845z M37.677,77.231c-2.997,8.079-1.755,17.193,3.642,24.215
+ c12.155,4.943,26.051,5.146,38.643-0.035c-7.818-2.516-14.886-7.518-19.887-14.731C51.9,86.533,43.791,83.336,37.677,77.231z
+ M67.788,22.506c-1.506-8.158-7.053-15.383-15.229-18.732C38.445,6.015,25.411,14.27,17.426,26.935
+ c8.115-2.487,16.74-2.178,24.529,0.639C49.482,22.312,58.71,20.448,67.788,22.506z M90.557,66.761
+ c-3.086,7.399-8.722,13.188-15.678,16.61c6.194,5.604,14.805,7.758,22.852,5.834c9.054-9.587,13.884-22.198,13.9-35.009
+ C106.215,60.502,98.797,64.974,90.557,66.761z"/>
+ <g>
+ <circle fill="#F04D5C" cx="60.702" cy="54.196" r="15.972"/>
+ </g>
+ </g>
+</g>
+</svg>
diff --git a/Documentation/logos/dex-horizontal-white.png b/Documentation/logos/dex-horizontal-white.png
new file mode 100644
index 0000000000000000000000000000000000000000..8f072508f9efe14977e5e518e8e6b99473b4810c
Binary files /dev/null and b/Documentation/logos/dex-horizontal-white.png differ
diff --git a/Documentation/logos/dex-horizontal-white.svg b/Documentation/logos/dex-horizontal-white.svg
new file mode 100644
index 0000000000000000000000000000000000000000..b828ae0cfe28d0c071a4b910d49b50832364c08b
--- /dev/null
+++ b/Documentation/logos/dex-horizontal-white.svg
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Generator: Adobe Illustrator 17.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+ width="298px" height="109px" viewBox="0 0 298 109" enable-background="new 0 0 298 109" xml:space="preserve">
+<g>
+ <g>
+ <path fill="#FFFFFF" d="M183.537,67.645c0-5.045,0.777-9.561,2.332-13.556c1.555-3.992,3.614-7.377,6.179-10.151
+ c2.564-2.774,5.486-4.896,8.764-6.368c3.279-1.469,6.684-2.206,10.214-2.206c3.866,0,7.334,0.674,10.404,2.017
+ c3.067,1.346,5.631,3.279,7.692,5.801c2.058,2.522,3.634,5.549,4.728,9.079c1.092,3.532,1.64,7.484,1.64,11.854
+ c0,2.269-0.126,4.161-0.378,5.673H193.75c0.421,6.642,2.46,11.897,6.116,15.763c3.658,3.869,8.427,5.801,14.313,5.801
+ c2.941,0,5.653-0.441,8.133-1.324c2.479-0.883,4.855-2.038,7.125-3.467l3.656,6.808c-2.692,1.683-5.673,3.153-8.953,4.414
+ c-3.278,1.261-7.021,1.891-11.222,1.891c-4.121,0-7.966-0.736-11.539-2.206c-3.574-1.47-6.684-3.573-9.331-6.305
+ c-2.648-2.731-4.729-6.072-6.242-10.025C184.293,77.187,183.537,72.689,183.537,67.645z M226.41,62.98
+ c0-6.305-1.324-11.117-3.971-14.439c-2.648-3.321-6.368-4.981-11.159-4.981c-2.187,0-4.269,0.441-6.242,1.324
+ c-1.976,0.883-3.763,2.145-5.36,3.784c-1.598,1.639-2.922,3.656-3.971,6.052c-1.053,2.397-1.746,5.152-2.082,8.261H226.41z"/>
+ <path fill="#FFFFFF" d="M255.79,66.132l-18.536-29.256h11.222l8.196,13.493c0.924,1.683,1.891,3.385,2.9,5.108
+ c1.01,1.724,2.06,3.426,3.153,5.106h0.504c0.924-1.68,1.849-3.382,2.774-5.106c0.925-1.723,1.849-3.425,2.775-5.108l7.44-13.493
+ h10.844l-18.536,30.39l19.923,30.895h-11.222l-8.953-14.25c-1.094-1.847-2.187-3.697-3.279-5.549
+ c-1.094-1.847-2.228-3.656-3.404-5.421h-0.504c-1.094,1.765-2.145,3.552-3.153,5.358c-1.009,1.809-2.017,3.68-3.026,5.612
+ l-8.323,14.25H235.74L255.79,66.132z"/>
+ <path fill="#FFFFFF" d="M181.116,91.189c-1.091,0.243-1.576,0.243-2.182,0.243c-1.253,0-2.412-0.908-2.71-3.174V8.378h-10.467
+ v23.581l0.449,9.298v1.124c-2.672-2.164-5.302-3.875-7.888-5.127c-2.608-1.261-5.675-1.891-9.207-1.891
+ c-3.53,0-6.893,0.756-10.088,2.269c-3.196,1.514-6.011,3.658-8.449,6.431c-2.439,2.774-4.394,6.159-5.864,10.151
+ c-1.472,3.995-2.206,8.471-2.206,13.43c0,10.258,2.29,18.158,6.873,23.707c4.581,5.549,10.739,8.323,18.473,8.323
+ c3.614,0,6.999-0.862,10.152-2.585c3.152-1.723,5.946-3.762,8.386-6.116h0.189c1.006,5.65,4.144,8.701,10.175,8.701
+ c2.667,0,4.364-0.363,5.697-0.969L181.116,91.189z M165.757,82.525c-2.522,2.859-5.043,4.981-7.565,6.368
+ c-2.523,1.387-5.215,2.08-8.07,2.08c-5.382,0-9.542-2.058-12.485-6.179c-2.944-4.118-4.414-9.876-4.414-17.275
+ c0-3.53,0.462-6.725,1.388-9.583c0.924-2.857,2.184-5.316,3.782-7.377c1.596-2.06,3.467-3.658,5.612-4.792
+ c2.143-1.135,4.433-1.702,6.873-1.702c2.522,0,4.98,0.485,7.377,1.45c2.395,0.968,4.895,2.629,7.502,4.981V82.525z"/>
+ </g>
+ <g>
+ <path fill="#FFFFFF" d="M93.012,51.878c7.588-3.55,12.764-10.49,14.175-18.53C101.063,19.699,89.329,9.358,74.76,5.155
+ c4.923,7.133,7.272,15.583,6.771,24.17C87.978,34.77,92.383,42.854,93.012,51.878z M31.937,38.845
+ c-8.207-1.045-16.333,1.973-21.858,8.054c-2.183,15.088,2.457,30.245,12.687,41.563c-0.527-8.64,1.856-17.306,6.831-24.483
+ C26.857,55.352,27.987,46.248,31.937,38.845z M37.677,77.231c-2.997,8.079-1.755,17.193,3.642,24.215
+ c12.155,4.943,26.051,5.146,38.643-0.035c-7.818-2.516-14.886-7.518-19.887-14.731C51.9,86.533,43.791,83.336,37.677,77.231z
+ M67.788,22.506c-1.506-8.158-7.053-15.383-15.229-18.732C38.445,6.015,25.411,14.27,17.426,26.935
+ c8.115-2.487,16.74-2.178,24.529,0.639C49.482,22.312,58.71,20.448,67.788,22.506z M90.557,66.761
+ c-3.086,7.399-8.722,13.188-15.678,16.61c6.194,5.604,14.805,7.758,22.852,5.834c9.054-9.587,13.884-22.198,13.9-35.009
+ C106.215,60.502,98.797,64.974,90.557,66.761z"/>
+ <g>
+ <circle fill="#FFFFFF" cx="60.702" cy="54.196" r="15.972"/>
+ </g>
+ </g>
+</g>
+</svg>
diff --git a/README.md b/README.md
index f9ae424e4ede7fa04c151210b313742f33815c22..c7ec586bc14e53725575a654f1c308f94402eb63 100644
--- a/README.md
+++ b/README.md
@@ -1,65 +1,32 @@
# dex - A federated OpenID Connect provider
-
+[](https://godoc.org/github.com/coreos/dex)
-__This is an experimental version of dex that is likely to change in
-incompatible ways.__
+
-dex is an OAuth2 server that presents clients with a low overhead framework for
-identifying users while leveraging existing identity services such as Google
-Accounts, FreeIPA, GitHub, etc, for actual authentication. dex sits between your
-applications and an identity service, providing a backend agnostic flavor of
-OAuth2 called [OpenID Connect](https://openid.net/connect/), a spec will allows
-dex to support:
+Dex is an OpenID Connect server that allows users to login through upstream identity providers. Clients use a standards-based OAuth2 flow to login users, while the actual authentication is performed by established user management systems such as Google, GitHub, FreeIPA, etc.
-* Short-lived, signed tokens with predefined fields (such as email) issued on
-behalf of users.
-* Well known discovery of OAuth2 endpoints.
+[OpenID Connect][openid-connect] is a flavor of OAuth that builds on top of OAuth2 using the JOSE standards. This allows dex to provide:
+
+* Short-lived, signed tokens with standard fields (such as email) issued on behalf of users.
+* "well-known" discovery of OAuth2 endpoints.
* OAuth2 mechanisms such as refresh tokens and revocation for long term access.
* Automatic signing key rotation.
-Any system which can query dex can cryptographically verify a users identity
-based on these tokens, allowing authentication events to be passed between
-backend services.
-
-One such application that consumes OpenID Connect tokens is the [Kubernetes](
-http://kubernetes.io/) API server, allowing dex to provide identity for any
-Kubernetes clusters.
-
-## Getting started
-
-dex requires a Go installation and a GOPATH configured. Clone it down the
-correct place, and simply type `make` to compile dex.
-
-```
-git clone https://github.com/coreos/dex.git $GOPATH/src/github.com/coreos/dex
-cd $GOPATH/src/github.com/coreos/dex
-git checkout dev
-make
-```
-
-dex is a single, scalable binary that pulls all configuration from a config
-file (no command line flags at the moment). Use one of the config files defined
-in the `examples` folder to start up dex with an in-memory data store.
-
-```
-./bin/dex serve examples/config-dev.yaml
-```
+Standards-based token responses allows applications to interact with any OpenID Connect server instead of writing backend specific "access_token" dances. Systems that can already consume ID Tokens issued by dex include:
-dex allows OAuth2 clients to be defined statically through the config file. In
-another window, run the `example-app` (an OAuth2 client). By default this is
-configured to use the client ID and secret defined in the config file.
+* [Kubernetes][kubernetes]
+* [Amazon STS][amazon-sts]
-```
-./bin/example-app
-```
+## Documentation
-Then to interact with dex, like any other OAuth2 provider, you must first visit
-a client app, then be prompted to login through dex. This can be achieved using
-the following steps:
+* [Getting started](Documentation/getting-started.md)
+* [Storage options](Documentation/storage.md)
+* [Intro to OpenID Connect](Documentation/openid-connect.md)
+* [gRPC API](Documentation/api.md)
+* Identity provider logins (coming soon!)
+* Client libraries (coming soon!)
-1. Navigate to http://localhost:5555/ in your browser.
-2. Hit "login" on the example app to be redirected to dex.
-3. Choose the "Login with Email" and enter "admin@example.com" and "password"
-4. Approve the example app's request.
-5. See the resulting token the example app claims from dex.
+[openid-connect]: https://openid.net/connect/
+[kubernetes]: http://kubernetes.io/docs/admin/authentication/#openid-connect-tokens
+[amazon-sts]: https://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html
diff --git a/examples/config-dev.yaml b/examples/config-dev.yaml
index 39710e9b5ad3ef5824eaaf4f915609918470d665..2cf7245d59386cc20e0736f2c0ca807960e15584 100644
--- a/examples/config-dev.yaml
+++ b/examples/config-dev.yaml
@@ -1,29 +1,38 @@
# The base path of dex and the external name of the OpenID Connect service.
-# Clients use this value to do discovery.
+# This is the canonical URL that all clients MUST use to refer to dex. If a
+# path is provided, dex's HTTP service will listen at a non-root URL.
issuer: http://127.0.0.1:5556/dex
# The storage configuration determines where dex stores its state. Supported
# options include SQL flavors and Kubernetes third party resources.
+#
+# See the storage document at Documentation/storage.md for further information.
storage:
type: sqlite3
config:
file: examples/dex.db
-# Configuration for the
+# Configuration for the HTTP endpoints.
web:
http: 127.0.0.1:5556
- # HTTPS options are also supported:
+ # Uncomment for HTTPS options.
# https: 127.0.0.1:5554
# tlsCert: /etc/dex/tls.crt
# tlsKey: /etc/dex/tls.key
-# Uncomment this block to enable the gRPC API.
+# Uncomment this block to enable the gRPC API. This values MUST be different
+# from the HTTP endpoints.
# grpc:
# addr: 127.0.0.1:5557
# tlsCert: /etc/dex/grpc.crt
# tlsKey: /etc/dex/grpc.key
# tlsClientCA: /etc/dex/client.crt
+# Uncomment this block to enable configuration for the expiration time durations.
+# expiry:
+# signingKeys: "6h"
+# idTokens: "24h"
+
# Instead of reading from an external storage, use this list of clients.
#
# If this option isn't choosen clients may be added through the gRPC API.
@@ -43,12 +52,12 @@ connectors:
# name: Google
# config:
# issuer: https://accounts.google.com
-# # Config values starting with a "$" will read from the environment.
+# # Connector config values starting with a "$" will read from the environment.
# clientID: $GOOGLE_CLIENT_ID
# clientSecret: $GOOGLE_CLIENT_SECRET
-# redirectURI: http://127.0.0.1:5556/dex/callback/google
+# redirectURI: http://127.0.0.1:5556/dex/google
-# Let dex keep a list of passwords which can be used to login the user
+# Let dex keep a list of passwords which can be used to login to dex.
enablePasswordDB: true
# A static list of passwords to login the end user. By identifying here, dex
@@ -61,8 +70,3 @@ staticPasswords:
hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
username: "admin"
userID: "08a8684b-db88-4b73-90a9-3cd1661f5466"
-
-# Uncomment this block to enable configuration for the expiration time durations.
-# expiry:
-# signingKeys: "6h"
-# idTokens: "24h"