Skip to content

Commit

Permalink
Improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
Petya Koleva committed Dec 27, 2024
1 parent b8cfa6b commit 26b80de
Show file tree
Hide file tree
Showing 7 changed files with 253 additions and 47 deletions.
59 changes: 32 additions & 27 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 a collection of samples which integrate between the
[MIRACL Trust platform](https://miracl.com) and various OIDC libraries. This
integration test suite validates both the compatibility and the correct operation
of the client library.

## ENV Variables

Expand All @@ -19,23 +20,23 @@ 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_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.
Has no default value and is required.
It has no default value and is mandatory.
- `PROXY_HOST`- The host address of the proxy, which you wish to run the sample
behind. The default value is empty string.
behind. The default value is an empty string.
- `PROXY_PORT`- The port of the proxy, which you wish to run the sample behind.
The default value is empty string.
The default value is an empty string.

The required env vars are `CLIENT_ID` and `CLIENT_SECRET`.
The required environment variables are `CLIENT_ID` and `CLIENT_SECRET`.

To get those values, you'll need to [register and create an app in our
platform](https://docs.miracl.cloud/get-started/).
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.

## Usage

You can run any sample as Docker container
Every sample can be run in its own framework or as a Docker container as shown
here:

```bash
cd samples/<variant>
Expand All @@ -47,24 +48,28 @@ 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.
Then, go to `http://localhost:8000` where you are navigated to the MIRACL Trust
authorization page to start your registration and authentication. If you need
to set another `PORT` or `HOST`, change the `8000:8000` port mapping and add
the environment variables in the `docker run` command.

See the respective README files for details of every sample if you don't want to
use Docker.

## Running through 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 \
Expand All @@ -80,7 +85,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.
19 changes: 19 additions & 0 deletions proxy/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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#usage].
49 changes: 40 additions & 9 deletions samples/dotnet/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,47 @@
# MIRACL Trust DotNet 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 dotnet framework library.

# Dependencies

This sample 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
The sample can be run directly with dotnet or with a Docker container. If you choose
the latter, follow the instructions [here](../../README.md).

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:

* open the OidcSample.sln in your Visual Studio
* right click over the solution in the Solution Explorer and press
`Restore NuGet Packages`
* run the sample using `F5` or the run button of the redactor.

This runs a sample HTTP server which navigates you to the MIRACL Trust authorization
page to start the registration and authentication.
42 changes: 39 additions & 3 deletions samples/dotnet6/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,41 @@
# MIRACL Trust DotNet 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 DotNet6.0.

# Dependencies

This sample uses [.NET authentication](https://www.nuget.org/packages/Microsoft.AspNetCore.Authentication.OpenIdConnect/)
library to integrate with the MIRACL Trust platform.

# Setup

The sample can be run directly with dotnet6 or with a Docker container. If you choose
the latter, follow the instructions [here](../../README.md).

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 runs a sample HTTP server and when you open http://localhost:8000/,
it navigates you to the MIRACL Trust authorization page to start the
registration and authentication.
41 changes: 39 additions & 2 deletions samples/go/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,41 @@
# 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 Golang.

# Dependencies

This sample uses [go-oidc](https://github.com/coreos/go-oidc) library
to integrate with the MIRACL Trust platform.

# Setup

The sample can be run directly with Go or with a Docker container. If you choose
the latter, follow the instructions [here](../../README.md).

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/go
go run . -client-id="$CLIENT_ID" -client-secret="$CLIENT_SECRET"
```

This runs a sample HTTP server and when you open http://localhost:8000/,
it navigates you to the MIRACL Trust authorization page to start the
registration and authentication.
43 changes: 40 additions & 3 deletions samples/nodejs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,42 @@
# 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.

# Dependencies

This sample uses [openid-client](https://www.npmjs.com/package/openid-client) library
to integrate with the MIRACL Trust platform.

# Setup

The sample can be run directly with Node.js or with a Docker container. If you choose
the latter, follow the instructions [here](../../README.md).

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 runs a sample HTTP server and when you open http://localhost:8000/,
it navigates you to the MIRACL Trust authorization page to start the
registration and authentication.
47 changes: 44 additions & 3 deletions samples/python/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,46 @@
# 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.

# Dependencies

This sample uses [IdPyOIDC](https://idpy-oidc.readthedocs.io/en/latest/) library
to integrate with the MIRACL Trust platform.

# Setup

The sample can be run directly with Python or with a Docker container. If you choose
the latter, follow the instructions [here](../../README.md).

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, you need first to (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 CLIENTID --client-secret CLIENTSECRET
```

This runs a sample HTTP server and when you open http://localhost:8000/,
it navigates you to the MIRACL Trust authorization page to start the
registration and authentication.

0 comments on commit 26b80de

Please sign in to comment.