dex/Documentation/security_guide.md

Security Guide

According to the OpenID Connect Spec, TLS is required for connection between the client and the dex server. This guide explains how to set up a TLS connection for dex.

Create certificates, key files.

To get up and running you will need:

• Certificate Authority file (CA cert).
• Certificate file for the server signed by the CA above.
• Private Key file of the server, used by the server to exchange keys during TLS handshake.

There are a lot of tools and guides available to help you generate these files:

• Use 'openssl' command line. The guide can be found here
• Use etcd-ca, which is a simple certificate manager written in Go. Despite the its name, it can be used in other cases than etcd as well.
• Use Cloudflare's cfssl, we also provide example configs here, which is as simple as run make.

Start the server using TLS

Assume we already generated a CA file, a server certificate and a key file, then in order to make the dex server accept TLS connections, we will run the dex-worker with --cert-file=$PATH_TO_SERVER_CERTIFICATE and --key-file=$PATH_TO_SERVER_KEY_FILE, For example:

./build
./bin/dex-worker \
    --cert-file=examples/tls-setup/certs/dex.pem \
    --key-file=examples/tls-setup/certs/dex-key.pem \
    --listen="https://127.0.0.1:5556" \
    --issuer="https://127.0.0.1:5556" \
    --clients=./static/fixtures/clients.json \
    --connectors=./static/fixtures/connectors.json.sample \
    --email-cfg=./static/fixtures/emailer.json.sample \
    --users=./static/fixtures/users.json.sample \
    --no-db

Where:
--cert-file and --key-file tells the dex-worker which certificate and key file to use.
--listen tells dex-worker where to receive requests.
--clients, --connectors, --email-cfg and --users tells dex-worker where to find user/client data when database access is not enabled (--no-db).

When establishing connection to the server, we will need to provide the CA file to client unless the server's ceritificate is signed by CAs that already trusted by client's machine. For example:

./build
./bin/example-app \
    --trusted-ca-file=examples/tls-setup/certs/ca.pem \
    --client-id="XXX" \
    --client-secret="secrete" \
    --redirect-url="http://127.0.0.1:5555/callback" \
    --discovery="https://127.0.0.1:5556" \
    --listen="http://127.0.0.1:5555"

Where:
--trusted-ca-file tells the app where to find the CA file that we will trust. Note that if the server's certificate is self-signed, then the server's certificate is also the CA file here.
--client-id, --client-secret and --redirect-url are the registered client's identity information.
--discovery and --listen tell the app where to connect to the server and where to handle requests.

Next, you can go to http://127.0.0.1:5555 to register, login and enjoy your OIDC tokens generated by dex server.