154 lines
5.3 KiB
Markdown
154 lines
5.3 KiB
Markdown
dex
|
|
=====
|
|
|
|
[](https://quay.io/repository/coreos/dex)
|
|
|
|
dex is a federated identity management service.
|
|
It provides OpenID Connect (OIDC) to users, while it proxies to multiple remote identity providers (IdP) to drive actual authentication.
|
|
We named the project 'dex' beceause it is a central index of users that other pieces of software can authenticate against.
|
|
|
|
## Architecture
|
|
|
|
dex consists of multiple components:
|
|
|
|
- **dex-worker** is the primary server component of dex
|
|
- host a user-facing API that drives the OIDC protocol
|
|
- proxy to remote identity providers via "connectors"
|
|
- **dex-overlord** is an auxiliary process responsible for two things:
|
|
- rotation of keys used by the workers to sign identity tokens
|
|
- garbage collection of stale data in the database
|
|
- **dexctl** is CLI tool used to manage an dex deployment
|
|
- configure identity provider connectors
|
|
- administer OIDC client identities
|
|
|
|
A typical dex deployment consists of N dex-workers behind a load balanacer, and one dex-overlord.
|
|
The dex-workers directly handle user requests, so the loss of all workers can result in service downtime.
|
|
The single dex-overlord runs its tasks periodically, so it does not need to maintain 100% uptime.
|
|
|
|
## Connectors
|
|
|
|
Remote IdPs could implement any auth-N protocol.
|
|
*connectors* contain protocol-specific logic and are used to communicate with remote IdPs.
|
|
Possible examples of connectors could be: OIDC, LDAP, Local Memory, Basic Auth, etc.
|
|
dex ships with an OIDC connector, and a basic "local" connector for in-memory testing purposes.
|
|
Future connectors can be developed and added as future interoperability requirements emerge.
|
|
|
|
## Relevant Specifications
|
|
|
|
These specs are referenced and implemented to some degree in the `jose` package of this project.
|
|
|
|
- [JWK](https://tools.ietf.org/html/draft-ietf-jose-json-web-key-36)
|
|
- [JWT](https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-30)
|
|
- [JWS](https://tools.ietf.org/html/draft-jones-json-web-signature-04)
|
|
|
|
OpenID Connect (OIDC) is broken up into several specifications. The following (amongst others) are relevant:
|
|
|
|
- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
|
|
- [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)
|
|
- [OAuth 2.0 RFC](https://tools.ietf.org/html/rfc6749)
|
|
|
|
## Example OIDC Discovery Endpoints
|
|
|
|
- https://accounts.google.com/.well-known/openid-configuration
|
|
- https://login.salesforce.com/.well-known/openid-configuration
|
|
|
|
# Building
|
|
|
|
## With Host Go Environment
|
|
|
|
`./build`
|
|
|
|
## With Docker
|
|
|
|
`./go-docker ./build`
|
|
|
|
## Docker Build and Push
|
|
|
|
Binaries must be compiled first.
|
|
Builds a docker image and pushes it to the quay repo.
|
|
The image is tagged with the git sha and 'latest'.
|
|
|
|
```
|
|
export QUAY_USER=xxx
|
|
export QUAY_PASSWORD=yyy
|
|
./build-docker-push
|
|
```
|
|
|
|
## Rebuild API from JSON schema
|
|
|
|
Go API bindings are generated from a JSON Discovery file.
|
|
To regenerate run:
|
|
|
|
```
|
|
./schema/generator
|
|
```
|
|
|
|
For updating generator dependencies see docs in: `schema/generator_import.go`.
|
|
|
|
## Runing Tests
|
|
|
|
Run all tests: `./test`
|
|
|
|
Single package only: `PKG=<pkgname> ./test`
|
|
|
|
Functional tests: `./test-functional`
|
|
|
|
Run with docker:
|
|
|
|
```
|
|
./go-docker ./test
|
|
./go-docker ./test-functional
|
|
```
|
|
|
|
# Running
|
|
|
|
Run the main dex server:
|
|
|
|
After building, run `./bin/dex` and provider the required arguments.
|
|
Additionally start `./bin/dex-overlord` for key rotation and database garbage collection.
|
|
|
|
# Deploying
|
|
|
|
Generate systemd unit files by injecting secrets into the unit file templates located in: `./static/...`.
|
|
|
|
```
|
|
source <path-to-secure>/prod/dex.env.txt
|
|
./build-units
|
|
```
|
|
|
|
Resulting unit files are output to: `./deploy`
|
|
|
|
# Registering Clients
|
|
|
|
Like all OAuth2 servers clients must be registered with a callback url.
|
|
New clients can be registered with the dexctl CLI tool:
|
|
```
|
|
dexctl --db-url=postgres://localhost/auth?sslmode=disable new-client http://example.com/auth/callback
|
|
```
|
|
|
|
The tool will print the `client-id` and `client-secret` to stdout; you must save these for use in your client application. The output of this command is "KEY=VALUE" format, so If you `eval` it in your shell, the relevant variables are available to use.
|
|
|
|
Note that for the initial invocation of `dexctl` you need to provide a DSN URL to create a new-client. Once you have created this initial client, you can use its client-id and client-secret as credentials to dexctl, and make requests via the HTTP API instead of the DB:
|
|
|
|
```
|
|
dexctl --endpoint=http://your-issuer-url --client-id=your_client_id --client-secret=your_client_secret new-client
|
|
```
|
|
|
|
or, if you want to go the eval route:
|
|
```
|
|
eval "$(dexctl --endpoint=http://your-issuer-url --client-id=your_client_id --client-secret=your_client_secret new-client)"
|
|
```
|
|
|
|
The latter form makes the variables `DEX_APP_CLIENT_ID`, `DEX_APP_CLIENT_SECRET` and `DEX_APP_REDIRECTURL_0` available to your shell.
|
|
|
|
This will allow you to create new clients from machines that cannot hit the database.
|
|
|
|
# Standup Dev Script
|
|
|
|
A script which will create a database, create a client, start an overlord and a worker and start the example app exists at `contrib/standup-db.sh`.
|
|
|
|
# Coming Soon
|
|
|
|
- Multiple backing Identity Providers
|
|
- Identity Management
|
|
- Authorization
|