Skip to content

Commit 3910565

Browse files
mfranzoncraig-osterhout
mfranzon
and
craig-osterhout
authored
Add dex guide (#21926)
<!--Delete sections as needed --> ## Description In this guide I want to show how to run and configure Dex as container, to mock an OAuth service, which can be really useful in development/testing. ## Related issues or tickets <!-- Related issues, pull requests, or Jira tickets --> ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Co-authored-by: Craig Osterhout <[email protected]>
1 parent 17c998c commit 3910565

File tree

2 files changed

+170
-0
lines changed

2 files changed

+170
-0
lines changed

‎_vale/config/vocabularies/Docker/accept.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ Datadog
2020
Ddosify
2121
Debootstrap
2222
Dev
23+
Dex
2324
Dev Environments?
2425
Django
2526
Docker Build Cloud

‎content/guides/dex.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: Mocking OAuth services in testing with Dex
3+
description: &desc Mocking OAuth services in testing with Dex
4+
keywords: Dex, container-supported development
5+
linktitle: Mocking OAuth services with Dex
6+
summary: *desc
7+
tags: [app-dev, distributed-systems]
8+
languages: []
9+
params:
10+
time: 10 minutes
11+
---
12+
13+
Dex is an open-source OpenID Connect (OIDC) and OAuth 2.0 identity provider that can be configured to authenticate against various backend identity providers, such as LDAP, SAML, and OAuth. Running Dex in a Docker container allows developers to simulate an OAuth 2.0 server for testing and development purposes. This guide will walk you through setting up Dex as an OAuth mock server using Docker containers.
14+
15+
Nowadays OAuth is the preferred choice to authenticate in web services, the highest part of them give the possibility to access using popular OAuth services like GitHub, Google or Apple. Using OAuth guarantees a higher level of security and simplification since it is not necessary to create new profiles for each service. This means that, by allowing applications to access resources on behalf of users without sharing passwords, OAuth minimizes the risk of credential exposure.
16+
17+
In this guide, you'll learn how to:
18+
19+
- Use Docker to launch up a Dex container.
20+
- Use mock OAuth in the GitHub Action (GHA) without relying on an external OAuth provider.
21+
22+
## Using Dex with Docker
23+
24+
The official [Docker image for Dex](https://hub.docker.com/r/dexidp/dex/) provides a convenient way to deploy and manage Dex instances. Dex is available for various CPU architectures, including amd64, armv7, and arm64, ensuring compatibility with different devices and platforms. You can learn more about Dex standalone on the [Dex docs site](https://dexidp.io/docs/getting-started/).
25+
26+
### Prerequisites
27+
28+
[Docker Compose](/compose/): Recommended for managing multi-container Docker applications.
29+
30+
### Setting Up Dex with Docker
31+
32+
Begin by creating a directory for your Dex project:
33+
34+
```bash
35+
mkdir dex-mock-server
36+
cd dex-mock-server
37+
```
38+
Organize your project with the following structure:
39+
40+
```bash
41+
dex-mock-server/
42+
├── config.yaml
43+
└── compose.yaml
44+
```
45+
46+
Create the Dex Configuration File:
47+
The config.yaml file defines Dex's settings, including connectors, clients, and storage. For a mock server setup, you can use the following minimal configuration:
48+
49+
```yaml
50+
# config.yaml
51+
issuer: http://localhost:5556/dex
52+
storage:
53+
type: memory
54+
web:
55+
http: 0.0.0.0:5556
56+
staticClients:
57+
- id: example-app
58+
redirectURIs:
59+
- 'http://localhost:5555/callback'
60+
name: 'Example App'
61+
secret: ZXhhbXBsZS1hcHAtc2VjcmV0
62+
enablePasswordDB: true
63+
staticPasswords:
64+
- email: "[email protected]"
65+
hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W"
66+
username: "admin"
67+
userID: "1234"
68+
```
69+
70+
Explanation:
71+
- issuer: The public URL of Dex.
72+
73+
- storage: Using in-memory storage for simplicity.
74+
75+
- web: Dex will listen on port 5556.
76+
77+
- staticClients: Defines a client application (example-app) with its redirect URI and secret.
78+
79+
- enablePasswordDB: Enables static password authentication.
80+
81+
- staticPasswords: Defines a static user for authentication. The hash is a bcrypt hash of the password.
82+
83+
> [!NOTE]
84+
>
85+
> Ensure the hash is a valid bcrypt hash of your desired password. You can generate this using tools like [bcrypt-generator.com](https://bcrypt-generator.com/).
86+
or use CLI tools like [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) like in this following example:`echo password | htpasswd -BinC 10 admin | cut -d: -f2`
87+
88+
With Docker Compose configured, start Dex:
89+
```yaml
90+
# docker-compose.yaml
91+
92+
services:
93+
dex:
94+
image: dexidp/dex:latest
95+
container_name: dex
96+
ports:
97+
- "5556:5556"
98+
volumes:
99+
- ./config.yaml:/etc/dex/config.yaml
100+
command: ["dex", "serve", "/etc/dex/config.yaml"]
101+
```
102+
103+
Now it is possible to run the container using the `docker compose` command.
104+
```bash
105+
docker compose up -d
106+
```
107+
108+
This command will download the Dex Docker image (if not already available) and start the container in detached mode.
109+
110+
111+
To verify that Dex is running, check the logs to ensure Dex started successfully:
112+
```bash
113+
docker compose logs -f dex
114+
```
115+
You should see output indicating that Dex is listening on the specified port.
116+
117+
### Using Dex OAuth testing in GHA
118+
119+
To test the OAuth flow, you'll need a client application configured to authenticate against Dex. One of the most typical use cases is to use it inside GitHub Actions. Since Dex supports mock authentication, you can predefine test users as suggested in the [docs](https://dexidp.io/docs). The `config.yaml` file should looks like:
120+
121+
```yaml
122+
issuer: http://127.0.0.1:5556/dex
123+
124+
storage:
125+
type: memory
126+
127+
web:
128+
http: 0.0.0.0:5556
129+
130+
oauth2:
131+
skipApprovalScreen: true
132+
133+
staticClients:
134+
- name: TestClient
135+
id: client_test_id
136+
secret: client_test_secret
137+
redirectURIs:
138+
- http://{ip-your-app}/path/to/callback/ # example: http://localhost:5555/callback
139+
140+
connectors:
141+
# mockCallback connector always returns the user '[email protected]'.
142+
- type: mockCallback
143+
id: mock
144+
name: Mock
145+
```
146+
Now you can insert the Dex service inside your `~/.github/workflows/ci.yaml` file:
147+
148+
```yaml
149+
[...]
150+
jobs:
151+
test-oauth:
152+
runs-on: ubuntu-latest
153+
steps:
154+
- name: Install Dex
155+
run: |
156+
curl -L https://github.com/dexidp/dex/releases/download/v2.37.0/dex_linux_amd64 -o dex
157+
chmod +x dex
158+
159+
- name: Start Dex Server
160+
run: |
161+
nohup ./dex serve config.yaml > dex.log 2>&1 &
162+
sleep 5 # Give Dex time to start
163+
[...]
164+
```
165+
166+
167+
### Conclusion
168+
169+
By following this guide, you've set up Dex as an OAuth mock server using Docker. This setup is invaluable for testing and development, allowing you to simulate OAuth flows without relying on external identity providers. For more advanced configurations and integrations, refer to the [Dex documentation](https://dexidp.io/docs/).

0 commit comments

Comments
 (0)