Improve documentation

miracl · Jan 10, 2025 · 44b1817 · 44b1817
1 parent 0d46e90
commit 44b1817
Show file tree

Hide file tree

Showing 8 changed files with 276 additions and 54 deletions.
diff --git a/README.md b/README.md
@@ -4,11 +4,12 @@
 ![nodejs](https://github.com/miracl/oidc-samples/workflows/nodejs/badge.svg)
 ![dotnet6](https://github.com/miracl/oidc-samples/workflows/dotnet6/badge.svg)
 ![dotnet](https://github.com/miracl/oidc-samples/workflows/dotnet/badge.svg)
+![python](https://github.com/miracl/oidc-samples/workflows/python/badge.svg)
 
-These samples provide example integrations between the [MIRACL
-Trust](https://miracl.com) platform and various OIDC libraries. The integration
-test suit validates both the compatibility and the correct operation of the
-client library.
+This repository contains samples showcasing the integration between [MIRACL
+Trust platform](https://miracl.com) and various OIDC libraries. There are also
+[integration tests](./integration-tests/) that validate both the compatibility
+and the correct operation of the client libraries.
 
 ## ENV Variables
 
@@ -19,23 +20,33 @@ All samples work with the following environment variables:
 - `ISSUER` - OpenID Connect Issuer. The default is "https://api.mpin.io".
 - `REDIRECT_URL` - The redirect URL of the app in the MIRACL Trust platform.
   The default value is "http://localhost:8000/login".
-- `CLIENT_ID` - The client id of the app in the MIRACL Trust platform. Has no
-  default value and is required.
-- `CLIENT_SECRET`- The client secret of the app in the MIRACL Trust platform.
-  Has no default value and is required.
-- `PROXY_HOST`- The host address of the proxy, which you wish to run the sample
-  behind. The default value is empty string.
-- `PROXY_PORT`- The port of the proxy, which you wish to run the sample behind.
-  The default value is empty string.
+- `CLIENT_ID` - The Client ID of the app in the MIRACL Trust platform. It has
+  no default value and is mandatory.
+- `CLIENT_SECRET`- The Client Secret of the app in the MIRACL Trust platform.
+  It has no default value and is mandatory.
+- `PROXY_HOST`- The host address of the proxy behind which you run the sample.
+  The default value is an empty string. It is used only when the setup requires
+  a proxy, allowing us to validate that the OIDC client works behind a proxy.
+- `PROXY_PORT`- The port of the proxy behind which you run the sample. The
+  default value is an empty string. It is used only when the setup requires a
+  proxy, allowing us to validate that the OIDC client works behind a proxy.
+
+To get those values, you'll need to [register](https://miracl.com/resources/docs/get-started/register/)
+and [create an app](https://miracl.com/resources/docs/get-started/low-code/) in
+our platform.
 
-The required env vars are `CLIENT_ID` and `CLIENT_SECRET`.
+## Usage
 
-To get those values, you'll need to [register and create an app in our
-platform](https://docs.miracl.cloud/get-started/).
+You can start every sample with its native tooling. For instructions, see the
+README.md of the sample you are interested in.
 
-## Usage
+Once you start your sample of choice, go to http://localhost:8000, which will
+take you to the MIRACL Trust authorization page. You need to enrol the device
+the first time you use the sample. Then, you can authenticate directly using M-PIN.
+
+### Run with Docker
 
-You can run any sample as Docker container
+You can also use Docker to run any sample.
 
 ```bash
 cd samples/<variant>
@@ -47,24 +58,40 @@ docker run \
   sample
 ```
 
-Afterwards visit `http://localhost:8000`. If you need to set another `PORT` or
-`HOST`, change the `8000:8000` port mapping and add the env variables in the
-`docker run` command.
+### Run on a different port with Docker
+
+All samples use port 8000 as the default; hence, the sample starts at 8000, and
+the default OIDC Redirect URL is http://localhost:8000/login. To change the
+port you access the sample on, do the following:
+
+```bash
+docker run \
+  --publish <custom-port>:8000 \
+  --env CLIENT_ID=<client-id> \
+  --env CLIENT_SECRET=<client-secret> \
+  --env REDIRECT_URL=http://localhost:<custom_port>/login \
+  sample
+```
+
+Note that we don't need to change the port the sample runs on in the container -
+just the Docker mapping. The redirect URL must also be updated in
+the command and the application configuration in the [MIRACL Trust
+Portal](https://trust.miracl.cloud).
 
-## Running through proxy
+## Running through a proxy
 
-In order to test how OIDC libraries behave in some edge cases(for ex. when the
-OIDC server misbehaves) - we need to modify the traffic between the library and
-the sample showcasing that library.
+To test how OIDC libraries behave in some edge cases (e.g. when the
+OIDC server misbehaves), we need to modify the traffic between the library and
+the sample showcasing it.
 
 You have the option to use our proxy with the provided samples. You can check
-the [README](proxy/README.md) in the proxy directory for how to build and run
-it.
+the [README](proxy/README.md) in the proxy directory for information on how to
+build and run it.
 
-Provided that you have a built docker image of the proxy and the sample that you
-wish to run, it's as simple as just running both `docker run` commands, with the
-addition of the `PROXY_HOST` and `PROXY_PORT` environment variables. If you've
-stuck to the default values, those commands are:
+Provided that you have built Docker images of the proxy and the sample that you
+wish to run, you can run both `docker run` commands with the addition of the
+`PROXY_HOST` and `PROXY_PORT` environment variables. If you use the default values,
+the commands to run the sample behind the proxy are:
 
 ```bash
 docker run \
@@ -80,7 +107,7 @@ docker run \
 ```
 
 You can confirm that the requests from the sample are going through a proxy if
-you enable the verbose mode of the proxy, using the `VERBOSE` environment
-variable in the command above. When the proxy and sample are started and you
+you enable the verbose mode of the proxy using the `VERBOSE` environment
+variable in the command above. When the proxy and the sample are started and you
 complete a registration and authentication, the proxy output will log out the
 information of the proxied requests.
diff --git a/integration-tests/README.md b/integration-tests/README.md
@@ -7,6 +7,17 @@ implementation with popular client side implementations.
 
 The integration test defines some flags. Use the following command to see them.
 
+### Setup
+
+The integration tests can be run directly with Go or with a Docker container.
+You must pass the app's credentials to the tests through environment
+variables as follows:
+
+``` bash
+export CLIENT_ID=<client-id>
+export CLIENT_SECRET=<client-secret>
+```
+
 ### Run
 
 ```bash

diff --git a/proxy/README.md b/proxy/README.md
@@ -15,3 +15,22 @@ A POST request to the `/session` endpoint starts a MITM session. The body of the
 request should contain JSON document with `modifyUrl` property. This property
 is the URL where the proxy will redirect all traffic until the session is
 stopped. A `DELETE` request to the `/session` endpoint stops the session.
+
+## Usage
+
+The proxy is written in Go, so it can be run either as a Go service:
+
+```bash
+cd ./proxy
+go run .
+```
+
+or as a Docker container:
+
+```
+docker build -t proxy .
+docker run --publish 8080:8080 proxy
+```
+
+Then you need to pass the PROXY_HOST and PROXY_PORT environment variables to
+your sample as described [here](../README.md?tab=readme-ov-file#running-through-proxy).
diff --git a/samples/dotnet/README.md b/samples/dotnet/README.md
@@ -1,16 +1,45 @@
-# MIRACL Trust DotNet Framework 4.8 OIDC Integration Sample
+# MIRACL Trust .NET Framework 4.8 OIDC Integration Sample
 
-This is an example integration with the standard dotnet framework library using Owin and OpenID Connect dependencies: 
-- [https://www.nuget.org/packages/Microsoft.AspNet.Identity.Owin/](https://www.nuget.org/packages/Microsoft.AspNet.Identity.Owin/)
+![dotnet](https://github.com/miracl/oidc-samples/workflows/dotnet/badge.svg)
+
+This is an example of an [OIDC integration](https://miracl.com/resources/docs/guides/authentication/oidc/)
+with the [MIRACL Trust platform](https://miracl.com) using standard .NET framework library.
+It uses Owin and OpenID Connect dependencies to integrate with the MIRACL Trust platform:
+- [https://www.nuget.org/packages/Microsoft.AspNet.Identity.Owin](https://www.nuget.org/packages/Microsoft.AspNet.Identity.Owin/)
 - [https://www.nuget.org/packages/Microsoft.Owin.Host.SystemWeb](https://www.nuget.org/packages/Microsoft.Owin.Host.SystemWeb)
-- [https://www.nuget.org/packages/OpenAthens.Owin.Security.OpenIdConnect/](https://www.nuget.org/packages/OpenAthens.Owin.Security.OpenIdConnect/)
+- [https://www.nuget.org/packages/OpenAthens.Owin.Security.OpenIdConnect](https://www.nuget.org/packages/OpenAthens.Owin.Security.OpenIdConnect/)
 
-## Usage
+# Setup
 
-You can run any sample as Docker container
+To start an OIDC integration, you must create an OIDC application in the
+[MIRACL Trust Portal](https://trust.miracl.com) as described [here](https://miracl.com/resources/docs/get-started/low-code/).
+The `Redirect URL` must be the same as the one the sample is run with. If you use the
+sample's default value, it must be set to `http://localhost:59504/login`.
+You must pass the app's credentials to the sample through its `web.config` file
+as follows:
 
+``` bash
+  <appSettings>
+    .....
+    <add key="REDIRECT_URL" value="http://localhost:59504/login" />
+    <add key="CLIENT_ID" value="CLIENT_ID" />
+    <add key="CLIENT_SECRET" value="CLIENT_SECRET" />
+  </appSettings>
 ```
-cd samples/<variant>
-docker build -t sample .
-docker run -p 8000:8000 -e CLIENT_ID=<client-id> -e CLIENT_SECRET=<client-secret> sample
-```
+
+# Usage
+
+To run the sample, do the following:
+
+1. Open the OidcSample.sln in your Visual Studio.
+1. Right click over the solution in the Solution Explorer and press
+   `Restore NuGet Packages`.
+1. Run the sample using `F5` or the Run button of the redactor.
+
+This starts the sample HTTP server. When you access http://localhost:59504/, you
+will be directed to the MIRACL Trust authorization page to begin the
+registration and authentication process. After a successful authentication, the
+sample retrieves the OIDC UserInfo endpoint and returns the result.
+
+If you would like to run the sample with Docker, follow the instructions in the
+main [README.md](../../README.md#run-with-docker) file.
diff --git a/samples/dotnet6/README.md b/samples/dotnet6/README.md
@@ -1,5 +1,39 @@
-# MIRACL Trust DotNet 6.0 OIDC Integration Sample
+# MIRACL Trust .NET 6.0 OIDC Integration Sample
 
-This example integrates the
-[.NET authentication library](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.OpenIdConnect/)
-with the MIRACL Trust platform.
+![dotnet6](https://github.com/miracl/oidc-samples/workflows/dotnet6/badge.svg)
+
+This is an example of an [OIDC integration](https://miracl.com/resources/docs/guides/authentication/oidc/)
+with the [MIRACL Trust platform](https://miracl.com) using .NET 6.0.
+It uses the [.NET authentication](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.OpenIdConnect/)
+library to integrate with the MIRACL Trust platform.
+
+# Setup
+
+To start an OIDC integration, you must create an OIDC application in the
+[MIRACL Trust Portal](https://trust.miracl.com) as described [here](https://miracl.com/resources/docs/get-started/low-code/).
+The `Redirect URL` must be the same as the one the sample is run with. If you use the
+sample's default value, it must be set to `http://localhost:8000/login`.
+You must pass the app's credentials to the sample through environment
+variables as follows:
+
+``` bash
+export CLIENT_ID=<client-id>
+export CLIENT_SECRET=<client-secret>
+```
+
+# Usage
+
+To run the sample, do the following:
+
+```bash
+cd samples/dotnet6
+dotnet run
+```
+
+This starts the sample HTTP server. When you access http://localhost:8000/, you
+will be directed to the MIRACL Trust authorization page to begin the
+registration and authentication process. After a successful authentication, the
+sample retrieves the OIDC UserInfo endpoint and returns the result.
+
+If you would like to run the sample with Docker, follow the instructions in the
+main [README.md](../../README.md#run-with-docker) file.
diff --git a/samples/go/README.md b/samples/go/README.md
@@ -1,4 +1,35 @@
 # MIRACL Trust Go OIDC Integration Sample
 
-This example integrates the [go-oidc library](https://github.com/coreos/go-oidc)
-with the MIRACL Trust platform.
+![go](https://github.com/miracl/oidc-samples/workflows/go/badge.svg)
+
+This is an example of an [OIDC integration](https://miracl.com/resources/docs/guides/authentication/oidc/)
+with the [MIRACL Trust platform](https://miracl.com) using Go.
+It uses the [go-oidc](https://github.com/coreos/go-oidc) library
+to integrate with the MIRACL Trust platform. See its documentation for
+the integration steps.
+
+# Setup
+
+To start an OIDC integration, you must create an OIDC application in the
+[MIRACL Trust Portal](https://trust.miracl.com) as described [here](https://miracl.com/resources/docs/get-started/low-code/).
+The `Redirect URL` must be the same as the one the sample is run with. If you use the
+sample's default value, it must be set to `http://localhost:8000/login`.
+
+# Usage
+
+To run the sample, do the following:
+
+```bash
+cd samples/go
+go run . \
+    -client-id <client-id> \
+    -client-secret <client-secret>
+```
+
+This starts the sample HTTP server. When you access http://localhost:8000/, you
+will be directed to the MIRACL Trust authorization page to begin the
+registration and authentication process. After a successful authentication, the
+sample retrieves the OIDC UserInfo endpoint and returns the result.
+
+If you would like to run the sample with Docker, follow the instructions in the
+main [README.md](../../README.md#run-with-docker) file.
diff --git a/samples/nodejs/README.md b/samples/nodejs/README.md
@@ -1,5 +1,41 @@
 # MIRACL Trust Node.js OIDC Integration Sample
 
-This example integrates the
-[openid-client](https://www.npmjs.com/package/openid-client) library with the
-MIRACL Trust platform.
+![nodejs](https://github.com/miracl/oidc-samples/workflows/nodejs/badge.svg)
+
+This is an example of an [OIDC integration](https://miracl.com/resources/docs/guides/authentication/oidc/)
+with the [MIRACL Trust platform](https://miracl.com) using Node.js.
+It uses the [openid-client](https://www.npmjs.com/package/openid-client) library
+to integrate with the MIRACL Trust platform. See its documentation for
+the integration steps.
+
+# Setup
+
+To start an OIDC integration, you must create an OIDC application in the
+[MIRACL Trust Portal](https://trust.miracl.com) as described [here](https://miracl.com/resources/docs/get-started/low-code/).
+The `Redirect URL` must be the same as the one the sample is run with. If you use the
+sample's default value, it must be set to `http://localhost:8000/login`.
+You must pass the app's credentials to the sample through environment
+variables as follows:
+
+``` bash
+export CLIENT_ID=<client-id>
+export CLIENT_SECRET=<client-secret>
+```
+
+# Usage
+
+To run the sample, do the following:
+
+```bash
+cd samples/nodejs
+npm install
+node index.js
+```
+
+This starts the sample HTTP server. When you access http://localhost:8000/, you
+will be directed to the MIRACL Trust authorization page to begin the
+registration and authentication process. After a successful authentication, the
+sample retrieves the OIDC UserInfo endpoint and returns the result.
+
+If you would like to run the sample with Docker, follow the instructions in the
+main [README.md](../../README.md#run-with-docker) file.
diff --git a/samples/python/README.md b/samples/python/README.md
@@ -1,5 +1,40 @@
 # MIRACL Trust Python OIDC Integration Sample
 
-This example integrates the
-[IdPyOIDC](https://idpy-oidc.readthedocs.io/en/latest/) library with the
-MIRACL Trust platform.
+![python](https://github.com/miracl/oidc-samples/workflows/python/badge.svg)
+
+This is an example of an [OIDC integration](https://miracl.com/resources/docs/guides/authentication/oidc/)
+with the [MIRACL Trust platform](https://miracl.com) using Python.
+It uses the [IdPyOIDC](https://idpy-oidc.readthedocs.io/en/latest/) library
+to integrate with the MIRACL Trust platform. See its documentation for
+the integration steps.
+
+# Setup
+
+To start an OIDC integration, you must create an OIDC application in the
+[MIRACL Trust Portal](https://trust.miracl.com) as described [here](https://miracl.com/resources/docs/get-started/low-code/).
+The `Redirect URL` must be the same as the one the sample is run with. If you use the
+sample's default value, it must be set to `http://localhost:8000/login`.
+
+# Usage
+
+To run the sample, you need to first [setup](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)
+your environment.
+
+```bash
+cd samples/python
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -r requirements.txt
+
+python app.py \
+    --client-id <client-id> \
+    --client-secret <client-secret>
+```
+
+This starts the sample HTTP server. When you access http://localhost:8000/, you
+will be directed to the MIRACL Trust authorization page to begin the
+registration and authentication process. After a successful authentication, the
+sample retrieves the OIDC UserInfo endpoint and returns the result.
+
+If you would like to run the sample with Docker, follow the instructions in the
+main [README.md](../../README.md#run-with-docker) file.