From 62dd4da8a12d8640d9f0153b268c0dbbe3e5fce5 Mon Sep 17 00:00:00 2001 From: mfranzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 29 Jan 2025 15:48:55 +0100 Subject: [PATCH 01/15] add dex guide --- content/guides/dex.md | 130 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 content/guides/dex.md diff --git a/content/guides/dex.md b/content/guides/dex.md new file mode 100644 index 000000000000..821fc4c5b65a --- /dev/null +++ b/content/guides/dex.md @@ -0,0 +1,130 @@ +--- +title: Mocking OAuth services in testing with Dex +description: &desc Mocking OAuth services in testing with Dex +keywords: Dex, container-supported development +linktitle: Mocking OAuth services with Dex +summary: *desc +tags: [app-dev, distributed-systems] +languages: [] +params: + time: 10 minutes +--- + +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. + +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. + +In this guide, you'll learn how to: + +- Use Docker to launch up a Dex container. +- Use mock OAuth in the local development without relying on an external OAuth provider. + +## Using Dex with Docker + +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/). + +### Prerequisites + +[Docker Compose](https://docs.docker.com/compose/): Recommended for managing multi-container Docker applications. + +### Setting Up Dex with Docker + +Begin by creating a directory for your Dex project: + +```bash +mkdir dex-mock-server +cd dex-mock-server +``` +Organize your project with the following structure: + +```bash +dex-mock-server/ +├── config.yaml +└── docker-compose.yaml +``` + +Create the Dex Configuration File: + +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: + +```yaml +# config.yaml +issuer: http://localhost:5556/dex +storage: + type: memory +web: + http: 0.0.0.0:5556 +staticClients: + - id: example-app + redirectURIs: + - 'http://localhost:5555/callback' + name: 'Example App' + secret: ZXhhbXBsZS1hcHAtc2VjcmV0 +enablePasswordDB: true +staticPasswords: + - email: "admin@example.com" + hash: "$2a$10$2b2cU8CPhOTaGrs1HRQuAueS7JTT5ZHsHSzYiFPm1leZck7Mc8T4W" + username: "admin" + userID: "1234" +``` + +Explanation: + +- issuer: The public URL for Dex. + +- storage: Using in-memory storage for simplicity. + +- web: Dex will listen on port 5556. + +- staticClients: Defines a client application (example-app) with its redirect URI and secret. + +- enablePasswordDB: Enables static password authentication. + +- staticPasswords: Defines a static user for authentication. The hash is a bcrypt hash of the password. + +> Note: 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/) +or use CLI tools like [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) like in this following example: +```bash +echo password | htpasswd -BinC 10 admin | cut -d: -f2 +``` + +Running Dex + +With Docker Compose configured, start Dex: + +```yaml +# docker-compose.yaml + +services: + dex: + image: dexidp/dex:latest + container_name: dex + ports: + - "5556:5556" + volumes: + - ./config.yaml:/etc/dex/config.yaml + command: ["dex", "serve", "/etc/dex/config.yaml"] +``` + +Now it is possible to run the container using `docker compose` command. +```bash +docker compose up -d +``` + +This command will download the Dex Docker image (if not already available) and start the container in detached mode. + + +To Verify that Dex is running, check the logs to ensure Dex started successfully: + +```bash +docker-compose logs -f dex +``` +You should see output indicating that Dex is listening on the specified port. + +Testing the OAuth Flow +Prepare a Test Application: + +To test the OAuth flow, you'll need a client application configured to authenticate against Dex. Dex provides an example app that you can use for this purpose. + +Clone the Dex Repository: + From 576743e44887c85bc351d9db0446616babca58d8 Mon Sep 17 00:00:00 2001 From: mfranzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 12 Mar 2025 10:22:07 +0100 Subject: [PATCH 02/15] more work dex guide --- content/guides/dex.md | 65 +++++++++++++++++++++++++++++++++---------- 1 file changed, 50 insertions(+), 15 deletions(-) diff --git a/content/guides/dex.md b/content/guides/dex.md index 821fc4c5b65a..b8ae2eed3449 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -17,7 +17,7 @@ Nowadays OAuth is the preferred choice to authenticate in web services, the high In this guide, you'll learn how to: - Use Docker to launch up a Dex container. -- Use mock OAuth in the local development without relying on an external OAuth provider. +- Use mock OAuth in the GHA without relying on an external OAuth provider. ## Using Dex with Docker @@ -44,7 +44,6 @@ dex-mock-server/ ``` Create the Dex Configuration File: - 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: ```yaml @@ -69,7 +68,6 @@ staticPasswords: ``` Explanation: - - issuer: The public URL for Dex. - storage: Using in-memory storage for simplicity. @@ -83,15 +81,9 @@ Explanation: - staticPasswords: Defines a static user for authentication. The hash is a bcrypt hash of the password. > Note: 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/) -or use CLI tools like [htpasswd](https://httpd.apache.org/docs/2.4/programs/htpasswd.html) like in this following example: -```bash -echo password | htpasswd -BinC 10 admin | cut -d: -f2 -``` - -Running Dex +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` With Docker Compose configured, start Dex: - ```yaml # docker-compose.yaml @@ -115,16 +107,59 @@ This command will download the Dex Docker image (if not already available) and s To Verify that Dex is running, check the logs to ensure Dex started successfully: - ```bash docker-compose logs -f dex ``` You should see output indicating that Dex is listening on the specified port. -Testing the OAuth Flow -Prepare a Test Application: +#### Using Dex OAuth testing in GHA + +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 suggests in the [docs](https://dexidp.io/docs). The `config.yaml` file should looks like: + +```yaml +issuer: http://127.0.0.1:5556/dex + +storage: + type: memory -To test the OAuth flow, you'll need a client application configured to authenticate against Dex. Dex provides an example app that you can use for this purpose. +web: + http: 0.0.0.0:5556 + +oauth2: + skipApprovalScreen: true + +staticClients: + - name: TestClient + id: client_test_id + secret: client_test_secret + redirectURIs: + - http://{ip-your-app}/path/to/callback/ # example: http://localhost:5555/callback + +connectors: +# mockCallback connector always returns the user 'kilgore@kilgore.trout'. +- type: mockCallback + id: mock + name: Mock +``` +Now you can insert the Dex service inside your `~/.github/workflows/ci.yaml` file: + +```yaml +[...] +jobs: + test-oauth: + runs-on: ubuntu-latest + steps: + - name: Install Dex + run: | + curl -L https://github.com/dexidp/dex/releases/download/v2.37.0/dex_linux_amd64 -o dex + chmod +x dex + + - name: Start Dex Server + run: | + nohup ./dex serve config.yaml > dex.log 2>&1 & + sleep 5 # Give Dex time to start +[...] + +``` -Clone the Dex Repository: From 2c12ba027d740ed0943f63134604565df4f01420 Mon Sep 17 00:00:00 2001 From: mfranzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 12 Mar 2025 10:28:59 +0100 Subject: [PATCH 03/15] add conclusions --- content/guides/dex.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/guides/dex.md b/content/guides/dex.md index b8ae2eed3449..5c4f68d9231c 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -112,7 +112,7 @@ docker-compose logs -f dex ``` You should see output indicating that Dex is listening on the specified port. -#### Using Dex OAuth testing in GHA +### Using Dex OAuth testing in GHA 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 suggests in the [docs](https://dexidp.io/docs). The `config.yaml` file should looks like: @@ -159,7 +159,8 @@ jobs: nohup ./dex serve config.yaml > dex.log 2>&1 & sleep 5 # Give Dex time to start [...] - ``` +### Conclusion +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/). From 47edef86a3571673fa05b8bc572272914e37478e Mon Sep 17 00:00:00 2001 From: Marco Franzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 26 Mar 2025 09:56:27 +0100 Subject: [PATCH 04/15] Update content/guides/dex.md Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> --- content/guides/dex.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/dex.md b/content/guides/dex.md index 5c4f68d9231c..8a5fbdee5002 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -12,7 +12,7 @@ params: 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. -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. +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. In this guide, you'll learn how to: From 8fdaeff96adfcc3abbd12fd68e69222dcdba5bd1 Mon Sep 17 00:00:00 2001 From: Marco Franzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 26 Mar 2025 09:56:36 +0100 Subject: [PATCH 05/15] Update content/guides/dex.md Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> --- content/guides/dex.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/dex.md b/content/guides/dex.md index 8a5fbdee5002..8e57c8387348 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -17,7 +17,7 @@ Nowadays OAuth is the preferred choice to authenticate in web services, the high In this guide, you'll learn how to: - Use Docker to launch up a Dex container. -- Use mock OAuth in the GHA without relying on an external OAuth provider. +- Use mock OAuth in the GitHub Action (GHA) without relying on an external OAuth provider. ## Using Dex with Docker From 2b53f8e9a5939c04f6b4b39b876416203ad90e9d Mon Sep 17 00:00:00 2001 From: Marco Franzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 26 Mar 2025 09:56:47 +0100 Subject: [PATCH 06/15] Update content/guides/dex.md Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> --- content/guides/dex.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/guides/dex.md b/content/guides/dex.md index 8e57c8387348..b585a744b807 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -80,7 +80,9 @@ Explanation: - staticPasswords: Defines a static user for authentication. The hash is a bcrypt hash of the password. -> Note: 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/) +> [!NOTE] +> +> 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/). 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` With Docker Compose configured, start Dex: From 09145addce94dcb3be1ffc3cf3378d0c1752b3e8 Mon Sep 17 00:00:00 2001 From: Marco Franzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 26 Mar 2025 09:57:01 +0100 Subject: [PATCH 07/15] Update content/guides/dex.md Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> --- content/guides/dex.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/dex.md b/content/guides/dex.md index b585a744b807..e624fe1ebb86 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -40,7 +40,7 @@ Organize your project with the following structure: ```bash dex-mock-server/ ├── config.yaml -└── docker-compose.yaml +└── compose.yaml ``` Create the Dex Configuration File: From 9c039f2ae733876b017979fa6ffa8e3f0ceb75e4 Mon Sep 17 00:00:00 2001 From: Marco Franzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 26 Mar 2025 09:57:09 +0100 Subject: [PATCH 08/15] Update content/guides/dex.md Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> --- content/guides/dex.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/dex.md b/content/guides/dex.md index e624fe1ebb86..ddc230f0a443 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -110,7 +110,7 @@ This command will download the Dex Docker image (if not already available) and s To Verify that Dex is running, check the logs to ensure Dex started successfully: ```bash -docker-compose logs -f dex +docker compose logs -f dex ``` You should see output indicating that Dex is listening on the specified port. From 51bc0e8c52d2beac6b1cac0a0c8b102ce9488fc4 Mon Sep 17 00:00:00 2001 From: Marco Franzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 26 Mar 2025 09:57:16 +0100 Subject: [PATCH 09/15] Update content/guides/dex.md Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> --- content/guides/dex.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/dex.md b/content/guides/dex.md index ddc230f0a443..b593e70eaa29 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -108,7 +108,7 @@ docker compose up -d This command will download the Dex Docker image (if not already available) and start the container in detached mode. -To Verify that Dex is running, check the logs to ensure Dex started successfully: +To verify that Dex is running, check the logs to ensure Dex started successfully: ```bash docker compose logs -f dex ``` From e4be9d38c3078a4351152ebfa2d98b8e9b727def Mon Sep 17 00:00:00 2001 From: Marco Franzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 26 Mar 2025 09:57:49 +0100 Subject: [PATCH 10/15] Update content/guides/dex.md Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> --- content/guides/dex.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/dex.md b/content/guides/dex.md index b593e70eaa29..772615e0f312 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -25,7 +25,7 @@ The official [Docker image for Dex](https://hub.docker.com/r/dexidp/dex/) provid ### Prerequisites -[Docker Compose](https://docs.docker.com/compose/): Recommended for managing multi-container Docker applications. +[Docker Compose](/compose/): Recommended for managing multi-container Docker applications. ### Setting Up Dex with Docker From be4b242e5343a7fdcdb4c53cbc279ffcbeed975e Mon Sep 17 00:00:00 2001 From: Marco Franzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 26 Mar 2025 09:58:03 +0100 Subject: [PATCH 11/15] Update content/guides/dex.md Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> --- content/guides/dex.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/dex.md b/content/guides/dex.md index 772615e0f312..b78a83ffb59a 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -100,7 +100,7 @@ services: command: ["dex", "serve", "/etc/dex/config.yaml"] ``` -Now it is possible to run the container using `docker compose` command. +Now it is possible to run the container using the `docker compose` command. ```bash docker compose up -d ``` From 89b489cc15a9baa89b2da6c7d478888983a41806 Mon Sep 17 00:00:00 2001 From: Marco Franzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 26 Mar 2025 09:58:14 +0100 Subject: [PATCH 12/15] Update content/guides/dex.md Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> --- content/guides/dex.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/dex.md b/content/guides/dex.md index b78a83ffb59a..3068e6b4294e 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -116,7 +116,7 @@ You should see output indicating that Dex is listening on the specified port. ### Using Dex OAuth testing in GHA -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 suggests in the [docs](https://dexidp.io/docs). The `config.yaml` file should looks like: +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: ```yaml issuer: http://127.0.0.1:5556/dex From 1cc50e11ce7a2887dcc5020d2a1e0f20b5c30bef Mon Sep 17 00:00:00 2001 From: Marco Franzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 26 Mar 2025 09:58:22 +0100 Subject: [PATCH 13/15] Update content/guides/dex.md Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> --- content/guides/dex.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/guides/dex.md b/content/guides/dex.md index 3068e6b4294e..32b3b97bfc50 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -68,7 +68,7 @@ staticPasswords: ``` Explanation: -- issuer: The public URL for Dex. +- issuer: The public URL of Dex. - storage: Using in-memory storage for simplicity. From ccb86db85444502d44e2a4d84097a47dfbc38813 Mon Sep 17 00:00:00 2001 From: Marco Franzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 26 Mar 2025 09:58:37 +0100 Subject: [PATCH 14/15] Update content/guides/dex.md Co-authored-by: Craig Osterhout <103533812+craig-osterhout@users.noreply.github.com> --- content/guides/dex.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/guides/dex.md b/content/guides/dex.md index 32b3b97bfc50..605d6bacc17f 100644 --- a/content/guides/dex.md +++ b/content/guides/dex.md @@ -165,4 +165,5 @@ jobs: ### Conclusion + 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/). From 6a7a93419d1356e429a871fe9b78a2d50f38f547 Mon Sep 17 00:00:00 2001 From: mfranzon <43796979+mfranzon@users.noreply.github.com> Date: Wed, 26 Mar 2025 10:01:37 +0100 Subject: [PATCH 15/15] add Dex to vale accept.txt --- _vale/config/vocabularies/Docker/accept.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 4b328de64740..71d0de4016db 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -20,6 +20,7 @@ Datadog Ddosify Debootstrap Dev +Dex Dev Environments? Django Docker Build Cloud