realStandal / kratos-react-example

ORY Kratos identity management example using the React framework; written in TypeScript.

Kratos React Example

This example is in-complete. Registration and Login flows are implemented; however, functionality related to state-management, trivial UX, and other Kratos flows are yet to be created. It still serves to provide a working-example of how the Kratos identification flow takes place; using kratos-selfservice-ui-node as a starting-point.

This is a React web-application built using create-react-app. It provides a self-service user-interface for interacting with a Kratos Identity and User Management system.

It has been written using TypeScript and uses the Bootstrap framework for UX.

Getting Started

This is a lengthy set of steps to use this repository and some meta-data about Kratos (for my future-benefit as well). Consult the next section if you want to just get it up-and-running, no explanation.

Tl;dr

Assuming you're familiar with Kratos:

• You'll need:
  • Docker
    • Docker Compose or Desktop
  • NodeJS (LTS should do, this is for running the React app)
    • Yarn 1.22.X installed globally.
  • (Optionally) Postman or Curl.
• clone the repository into an empty directory (./ target, or enter it once cloned).
• Run the following to start Kratos and MailSlurper containers: docker-compose -f kratos/docker-compose.yml up --build --force-recreate
  • A message resembling msg=Starting the admin httpd on: 0.0.0.0:4434 means your Kratos container is up-and-running.
  • You can verify the installation further by running docker exec kratos kratos --help or curl http://127.0.0.1:4433/version.
• Now we'll start the react-app in development mode using Yarn.
  • Run cd react-app.
  • Install dependencies (yarn install).
  • Start the development-server with yarn start.
• At this point, everything is set-up and ready for testing.
  • By default, react-app will load to an empty page.
  • Navigate to 127.0.0.1:3000/auth/register and 127.0.0.1:3000/auth/login to experiment with these flows.
  • The source code can be used as a reference for implementation; the file-structure is of little importance. The most important bits are files prefixed with auth- and login.tsx/register.tsx.

Prerequisites

Below are required dependencies/libraries/tools which you should have installed prior to continuing. Proceeding each is the version I will be using to write this guide; I'm not guaranteeing other versions will or will not work. minor and patch inconsistencies should be ok.

You're likely familiar with these; if not, nothing complex or crazy is taking place.

• Docker Engine (20.10.2)
  • Docker Desktop for Windows or Mac (3.1.0)
  • Docker Compose Docker Desktop includes this tool. (1.27.4)
• Node.JS (14.15.0)
  • Yarn (1.22.10)

1) Clone the Repository

In an empty directory, use the following command:

$ git clone https://github.com/LockTech/kratos-react-web-example.git ./

2) Kratos Stand-up

We'll begin by starting a Kratos container with minimal configuration. We'll be using Docker Compose to:

• Populate an SQLite database
• Start a MailSlurper service
• Begin the Kratos container

This work-flow has been taken from the Kratos Quickstart Guide, almost verbatum. Most of the configuration files were taken from the Kratos repository.

2.1) Start the Containers

By running the following, still at the root of the project.

$ docker-compose -f kratos/docker-compose.yml --build --force-recreate

The docker-compose.yml file has been configured to allocate 512Mb of RAM and .5 a CPU-core. You should configure this to best meet your development-needs; but I'd imagine this would cover any testing/prototyping needs.

Once completed, you should see lines resembling: "Starting the admin httpd on: 0.0.0.0:4434" and "Starting the public httpd on: 0.0.0.0:4433".

2.2) Testing Your Success

If so, you can use a tool such as Postman or curl to test that the endpoints are reachable.

Using curl, we can test that Kratos has been installed, is running, and has been configured to use the version our docker-compose file specified:

$ curl http://127.0.0.1:4433/version

Which should output, among many things, the following:

StatusCode        : 200
StatusDescription : OK
Content           : {"version":"v0.5.5-alpha.1"}
...

You should be able to interact with the Kratos container directly by running:

$ docker exec kratos kratos --help

Where the first kratos is the container's name, and the second is the Kratos CLI.

3) Start react-app

From here-on-out we'll be using the react-app directory.

3.1) Install Dependencies

react-app uses the Yarn package manager. Install it if you don't already have it (or remove yarn.lock).

3.2) Start the development-server

Using yarn start, start the application in development mode. This will open your browser to http://127.0.0.1:3000.

Note: Your page will be blank. I've yet to implement the trivial UX of the app; sorry.

3.3) Test Registration

Navigate to http://127.0.0.1:3000/auth/register. You should be automatically redirected to Kratos' /self-service/registration/browser endpoint, it'll likely happen faster than you can tell. You'll know it happened successfully if you see ?flow=XXXX... as a query in the URL.

At this point, you've initiated the registration-flow. You can use ?flow to interact with a few of the Kratos endpoints. curl the following: /self-service/registration/flows?id=string substituting string with your flow-ID. This will provide you with information on the registration flow.

You'll notice that ...fields: contains the same fields as the UI on your browser. These fields are generated during each request, meaning a change to identity.schema.json will result in a change to the UI; the only cavet is you'll need to update auth-form-translator provide a more user-friendly UI.

Go ahead and register an account; if successful, you should be redirected to the (blank) home page with an additional cookie containing your Kratos-token.

3.4) Logging Out

If you direct your browser to http://127.0.0.1:4433/self-service/browser/flows/logout you will be logged out. This will invalidate your current session and remove any cookies.

3.5) Logging In

With your session invalidated, navigate to http://127.0.0.1/auth/login and login to the account you just created. Once again, you should be redirected to the home page.

4) Administration

By default, the Kratos administrative endpoints are open and freely accessible (to anyone on your network).

You can use these, in a client such as Postman or curl, to view the identities stored by Kratos. With an account registered, perform curl http://127.0.0.1:4434/identities. This should provide you with a list of identities stored by Kratos.

5) Celebrate

I mean you read it! And I wrote it! Great teamwork, everyone.