dex/README.md
2015-08-18 11:26:57 -07:00

155 lines
5.3 KiB
Markdown

dex
=====
[![Build Status](https://semaphoreci.com/api/v1/projects/52d56c45-8487-42ac-b124-056df1630122/411983/badge.svg)](https://semaphoreci.com/coreos/dex)
[![Docker Repository on Quay.io](https://quay.io/repository/coreos/dex/status?token=64f952fa-9aa9-4f8e-ab8d-93bfbe770d25 "Docker Repository on Quay.io")](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.
## 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