@@ -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.
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.
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.
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.
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
