MIRACL Trust OIDC Integration Samples

This repository contains samples showcasing the integration between MIRACL Trust platform and various OIDC libraries. There are also 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 - 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. 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 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 these values, you'll need to register and create an application in our platform.

Usage

You can start every sample with its native tooling. For instructions, see the 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.

Run with Docker

You can also use Docker to run any of the samples.

cd samples/<variant>
docker build -t sample .
docker run \
  --publish 8000:8000 \
  --env CLIENT_ID=<client-id> \
  --env CLIENT_SECRET=<client-secret> \
  --env ISSUER=<oidc-issuer> \
  sample

Run on a different port with Docker

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:

docker run \
  --publish <custom-port>:8000 \
  --env CLIENT_ID=<client-id> \
  --env CLIENT_SECRET=<client-secret> \
  --env ISSUER=<oidc-issuer> \
  --env REDIRECT_URL=http://localhost:<custom_port>/login \
  sample

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.

Run through a proxy

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. See the README 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:

docker run \
  --publish 8080:8080 \
  proxy
docker run \
  --publish 8000:8000 \
  --env PROXY_HOST=127.0.0.1 \
  --env PROXY_PORT=8080 \
  --env CLIENT_ID=<client-id> \
  --env CLIENT_SECRET=<client-secret> \
  --env ISSUER=<oidc-issuer> \
  sample

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.