Update OIDC samples texts (#92)

Co-authored-by: Lora Trifonova <lora.trifonova@miracl.com>

Author: LoraTod

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/<variant>
@@ -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.

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
 

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()
 

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.

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
 	}
 

samples/dotnet/README.md

@@ -2,23 +2,27 @@
 
 ![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/)
 
 # 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
   <appSettings>
     .....
     <add key="REDIRECT_URL" value="http://localhost:59504/login" />
@@ -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.

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=<client-id>
 export CLIENT_SECRET=<client-secret>
 export ISSUER=<oidc-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.

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 <oidc-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.