diff --git a/README.md b/README.md index 8153424f..2831b718 100644 --- a/README.md +++ b/README.md @@ -6,49 +6,53 @@ ![dotnet](https://github.com/miracl/oidc-samples/workflows/dotnet/badge.svg) ![python](https://github.com/miracl/oidc-samples/workflows/python/badge.svg) -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. +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 All samples work with the following environment variables: -- `HOST` - Host to listen on. The default is "localhost". -- `PORT` - Port of the listening host. The default is "8000". +- `HOST` - The host interface the server listens on. The default is "localhost". +- `PORT` - The port the server listens on. The default is "8000". - `ISSUER` - OpenID Connect Issuer. This must correspond to the OIDC Issuer - configured for your project in the [MIRACL Trust Portal](https://trust.miracl.cloud). - It has no default value and is mandatory. -- `REDIRECT_URL` - The redirect URL of the application in the MIRACL Trust platform. - The default value is "http://localhost:8000/login". + configured for your project in the + [MIRACL Trust Portal](https://trust.miracl.cloud). It is mandatory and has no + default value. +- `REDIRECT_URL` - The redirect URL of the application in the MIRACL Trust + platform. The default value is "http://localhost:8000/login". - `CLIENT_ID` - The Client ID of the application in the MIRACL Trust platform. - It has no default value and is mandatory. -- `CLIENT_SECRET`- The Client Secret of the application 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 + It is mandatory and has no default value. +- `CLIENT_SECRET`- The Client Secret of the application in the MIRACL Trust + platform. It is mandatory and has no default value. +- `PROXY_HOST`- The proxy host address used when running the sample behind a + proxy. 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 proxy port used when running the sample behind a proxy. 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 application](https://miracl.com/resources/docs/get-started/low-code/) +To get these values, you'll need to +[register](https://miracl.com/resources/docs/get-started/register/) and +[create an application](https://miracl.com/resources/docs/get-started/low-code/) in our platform. ## Usage You can start every sample with its native tooling. For instructions, see the -README.md of the sample you are interested in. +README of the sample you are interested in. 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. +the first time you use the sample. Then, you can authenticate directly using +M-PIN. ### Run with Docker -You can also use Docker to run any sample. +You can also use Docker to run any of the samples. ```bash cd samples/ @@ -63,9 +67,9 @@ docker run \ ### 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: +All samples use port 8000 by default. This means the application starts on port +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 \ @@ -77,25 +81,25 @@ docker run \ 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). +Note that you don't need to change the port the sample runs on in the +container - only the Docker mapping. You must also update the redirect URL in +the command and the application configuration in the +[MIRACL Trust Portal](https://trust.miracl.cloud). -## Running through a proxy +## Run through a proxy -To test how OIDC libraries behave in some edge cases (e.g. when the +To test how OIDC libraries behave in certain edge cases (for example, 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 information on how to -build and run it. +You have the option to use our proxy with the provided samples. See the +[README](proxy/README.md) in the proxy directory for information on how to build +and run it. 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: +`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 \ @@ -111,8 +115,8 @@ docker run \ sample ``` -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 the sample are started and you -complete a registration and authentication, the proxy output will log out the -information of the proxied requests. +You can confirm that requests from the sample are passing through the proxy by +enabling verbose mode with 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 index ed493ed0..d9d86ece 100644 --- a/integration-tests/README.md +++ b/integration-tests/README.md @@ -1,11 +1,11 @@ # MIRACL Trust Integration Tests for OIDC Samples -Integration test suit continuously testing the MIRACL Trust OpenID Connect -implementation with popular client side implementations. +Integration test suite that continuously tests the MIRACL Trust OpenID Connect +implementation with popular client-side implementations. ## Getting started -The integration test defines some flags. Use the following command to see them. +The integration test defines several flags. To see them, use the command below. ### Setup diff --git a/integration-tests/main_test.go b/integration-tests/main_test.go index cb775a32..d225c5ff 100644 --- a/integration-tests/main_test.go +++ b/integration-tests/main_test.go @@ -32,7 +32,7 @@ func TestMain(m *testing.M) { flag.StringVar(&options.restarterHost, "restarter-host", "127.0.0.1", "Restarter's HOST") flag.StringVar(&options.restarterPort, "restarter-port", "8081", "Restarter's PORT") flag.StringVar(&options.sampleName, "sample-name", "sample", "Sample's container name") - flag.BoolVar(&options.skipModifyTests, "skip-modify-tests", true, "Specify if the tests which modify requests to be skipped") + flag.BoolVar(&options.skipModifyTests, "skip-modify-tests", true, "Specify whether the tests that modify requests should be skipped") flag.Parse() diff --git a/proxy/README.md b/proxy/README.md index 14cdb8e3..fe689d77 100644 --- a/proxy/README.md +++ b/proxy/README.md @@ -5,16 +5,16 @@ samples for testing purposes. ## Modes -The proxy has two modes - one that simply forwards the traffic and one which -allows us to modify the requests and responses coming and going through the -proxy, using Man-In-The-Middle (MITM). +The proxy has two modes - one that forwards the traffic and one that allows us +to modify the requests and responses coming and going through the proxy, using +Man-In-The-Middle (MITM). ### MITM -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. +A POST request to the `/session` endpoint starts an MITM session. The body of +the request must contain a 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 @@ -32,5 +32,7 @@ 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). +Then, you must pass the PROXY_HOST and PROXY_PORT environment variables to your +sample as described in the +[Run through a proxy](../README.md?tab=readme-ov-file#run-through-proxy) section +of the main README. diff --git a/restarter/main.go b/restarter/main.go index a0ac73d6..f461a2b5 100644 --- a/restarter/main.go +++ b/restarter/main.go @@ -24,7 +24,7 @@ func main() { func restartSignature(w http.ResponseWriter, r *http.Request) { containerName := r.URL.Query().Get("name") if containerName == "" { - http.Error(w, "required query param 'name' missed", http.StatusPreconditionRequired) + http.Error(w, "missing required query param: 'name'", http.StatusPreconditionRequired) return } diff --git a/samples/dotnet/README.md b/samples/dotnet/README.md index f7800bbe..d5d2737b 100644 --- a/samples/dotnet/README.md +++ b/samples/dotnet/README.md @@ -2,9 +2,12 @@ ![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 the Owin and OpenID Connect dependencies to integrate with the MIRACL Trust platform: +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 the 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/) @@ -12,13 +15,14 @@ It uses the Owin and OpenID Connect dependencies to integrate with the MIRACL Tr # 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:59504/login`. -You must pass the app's credentials to the sample through its `web.config` file -as follows: - -``` bash +[MIRACL Trust Portal](https://trust.miracl.com), as described in +[Start Low-Code Integration](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 ..... @@ -30,17 +34,17 @@ as follows: # Usage -To run the sample, do the following: +To run the sample, follow these steps: 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. +1. Right-click over the solution in the Solution Explorer and select **Restore + NuGet Packages**. +1. Press **F5** or click **Run** in the editor to run the sample. -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. +This starts the sample HTTP server. When you open http://localhost:8000/ in your +browser, you will be redirected to the MIRACL Trust authorization page to begin +the registration and authentication process. After 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. +If you want to run the sample with Docker, follow the instructions in the main +[README](../../README.md#run-with-docker) file. diff --git a/samples/dotnet6/README.md b/samples/dotnet6/README.md index 8cc1d0f2..0b7d37c1 100644 --- a/samples/dotnet6/README.md +++ b/samples/dotnet6/README.md @@ -2,21 +2,23 @@ ![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/) +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: +[MIRACL Trust Portal](https://trust.miracl.com), as described in +[Start Low-Code Integration](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 +```bash export CLIENT_ID= export CLIENT_SECRET= export ISSUER= @@ -31,10 +33,10 @@ 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. +This starts the sample HTTP server. When you open http://localhost:8000/ in your +browser, you will be redirected to the MIRACL Trust authorization page to begin +the registration and authentication process. After 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. +If you want to run the sample with Docker, follow the instructions in the main +[README](../../README.md#run-with-docker) file. diff --git a/samples/go/README.md b/samples/go/README.md index cde16600..6cec3872 100644 --- a/samples/go/README.md +++ b/samples/go/README.md @@ -2,18 +2,20 @@ ![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. +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. Refer to the library's documentation for detailed +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`. +[MIRACL Trust Portal](https://trust.miracl.com), as described in +[Start Low-Code Integration](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 @@ -27,10 +29,10 @@ go run . \ -issuer ``` -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. +This starts the sample HTTP server. When you open http://localhost:8000/ in your +browser, you will be redirected to the MIRACL Trust authorization page to begin +the registration and authentication process. After 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. +If you want to run the sample with Docker, follow the instructions in the main +[README](../../README.md#run-with-docker) file. diff --git a/samples/nodejs/README.md b/samples/nodejs/README.md index e1d395c5..179e1e3e 100644 --- a/samples/nodejs/README.md +++ b/samples/nodejs/README.md @@ -2,22 +2,24 @@ ![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. +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. Refer to the library's documentation +for detailed 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: +[MIRACL Trust Portal](https://trust.miracl.com), as described in +[Start Low-Code Integration](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 +```bash export CLIENT_ID= export CLIENT_SECRET= export ISSUER= @@ -33,10 +35,10 @@ 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. +This starts the sample HTTP server. When you open http://localhost:8000/ in your +browser, you will be redirected to the MIRACL Trust authorization page to begin +the registration and authentication process. After 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. +If you want to run the sample with Docker, follow the instructions in the main +[README](../../README.md#run-with-docker) file. diff --git a/samples/python/README.md b/samples/python/README.md index f08e18a4..a19f0ec3 100644 --- a/samples/python/README.md +++ b/samples/python/README.md @@ -2,22 +2,25 @@ ![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. +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. Refer to the library's documentation for +detailed 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`. +[MIRACL Trust Portal](https://trust.miracl.com), as described in +[Start Low-Code Integration](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/) +To run the sample, you must first +[setup](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/) your environment. ```bash @@ -32,10 +35,10 @@ python app.py \ --issuer ``` -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. +This starts the sample HTTP server. When you open http://localhost:8000/ in your +browser, you will be redirected to the MIRACL Trust authorization page to begin +the registration and authentication process. After 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. +If you want to run the sample with Docker, follow the instructions in the main +[README](../../README.md#run-with-docker) file.