# TLS Setup

According to the [OpenID Connect Spec](http://openid.net/specs/openid-connect-core-1_0.html),
TLS [is required](http://openid.net/specs/openid-connect-core-1_0.html#TLSRequirements) 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](http://www.g-loaded.eu/2005/11/10/be-your-own-ca/)
- Use [etcd-ca](https://github.com/coreos/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](https://github.com/cloudflare/cfssl), we also provide example configs [here](../examples/tls-setup), 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:

```shell
./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: <br/>
`--cert-file` and `--key-file` tells the dex-worker which certificate and key file to use. <br/>
`--listen` tells dex-worker where to receive requests. <br/>
`--clients`, `--connectors`, `--email-cfg` and `--users` tells dex-worker where to find user/client data when database access is not enabled (`--no-db`). <br/>

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:

```shell
./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: <br/>
`--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. <br/>
`--client-id`, `--client-secret` and `--redirect-url` are the registered client's identity information. <br/>
`--discovery` and `--listen` tell the app where to connect to the server and where to handle requests. <br/>

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