Integrate Ory in a NestJS application

This article is the third part of a series that explores integrating Ory, within the NestJS framework. In the previous articles, we introduced Ory and its core components and discussed creating dedicated NestJS libraries to simplify Ory integration. In this post, we will build upon the concepts and libraries developed in the previous articles and dive into the practical aspects of integrating Ory in a NestJS application.

What is better than a concrete example to demonstrate the integration? Our demonstration app is a web-based platform (REST API) called CatFoster. CatFoster is a community hub where cat owners needing temporary care for their pets can connect with cat lovers willing to foster animals in their homes.

Note: The CatFoster application is a simplified example that demonstrates the integration of Ory in a NestJS application. The application will not cover frontend development and deployment, focusing solely on showcasing the backend implementation of the authentication and authorization features of Ory.

The journey to integrate Ory in the CatFoster application will be divided into three main phases:

1. Design Phase: We will outline the architecture, user flows, entities, and permissions for the CatFoster application. This phase will help us understand the requirements and functionalities of the application before diving into the implementation.

2. Implementation Phase: We will create a new Nx workspace, set up a NestJS application, configure Ory Kratos and Ory Keto using Docker Compose, and implement the necessary modules, services, controllers, and entities to integrate Ory into the CatFoster application.

3. Testing Phase: We will start with manual testing and then write end-to-end tests for the application by running the application locally. This phase will show how to set up an Ory environment for testing.

Note: If this is your first time working with Ory, I recommend reading the Introduction to Ory article to familiarize yourself with the core components and concepts of Ory.

Key Features

1. User Authentication and Profile Management:

   • Ory Integration: Utilize Ory's authentication system to handle user registrations, logins, password resets, and profile management.

   • User Roles: There is one static user role, Admin, that a super admin can assign to users after registration.

2. Cat Profiles:

   • Listing and Management: Cat owners can create profiles for their cats, including photos, descriptions, special care instructions, and availability for fostering. Admins can edit and delete cat profiles.

   • Search and Filters: Users looking to foster cats can search for them based on filters.

3. Fostering Matchmaking:

   • Requests and Approvals: Cat fosters can send fostering requests to cat owners, who can review and approve or deny them based on the foster's profiles.

   • Authorization Checks: Use Ory to manage authorization, ensuring that only cat owners can approve fostering requests and only registered users can send requests.

Design phase

Architecture

• Self-service UI: This is the frontend where users can log in and manage their accounts. It communicates directly with Ory Kratos for authentication-related tasks.

• Ory Kratos: Handles authentication. It's responsible for user login, account management, and session management. It interacts with the NestJS app via HTTP webhooks to replicate user data on signup.

• HTTP Webhooks: Serve as the communication link between Ory Kratos and the NestJS app, ensuring the user is replicated in the local database upon signup.

• NestJS App: The core of your application is handling business logic, CRUD operations with the Postgres database, authentication checks with Ory Kratos, and authorization with Ory Keto.

• Ory Keto: Manages authorization, determining what authenticated users are allowed to do within the application.

• Postgres: The database where user data (replicated from Ory on signup), cat profiles and fostering requests are stored. The NestJS app interacts with Postgres for all data storage and retrieval operations.

User Flows

To visualize the user flow for the CatFoster project, we will create a series of diagrams using Mermaid to illustrate the different user interactions within the system. These interactions include signing up and signing in, creating a cat profile, updating and deleting their cat profiles, requesting to foster a cat, and approving fostering requests.

User Sign-Up and Sign-In Flow

Cat Profile Edition Flows

It all starts with the user creating a cat profile. Once the profile is created, the user (owner or member of the admin group) can update or delete it. The following sequence diagrams illustrate these flows.

Request Fostering Flow

This flow ensures that users can request to foster a cat only if they meet specific criteria, such as not being the cat's owner and not already fostering this cat. This mechanism helps prevent conflicts and ensures a smooth fostering process.

Approve Fostering Request Flow

This flow ensures that only cat owners can approve fostering requests, maintaining control over who fosters their cats.

Entities and Relationships

The diagram below represents the entities of CatProfile, User, and Fostering in our CatFoster application and illustrates their relationships. This diagram shows each entity's attributes and their associations, such as ownership and fostering relationships.

• User: Represents users of the system, which can be cat owners, fosters, or both. Attributes include basic user information like id, name, email. Relationships include ownedCats, a list of CatProfile entities that the user owns, and fosteringActivities, a list of Fostering entities indicating the cats they are fostering or have fostered.

• CatProfile: Represents the profiles of cats available for fostering. Attributes include the cat's id, name, age, description, ownerId (linking back to the User who owns the cat), and photosUrls, a list of URLs to photos of the cat. It has a relationship to Fostering, which indicates any fostering activities it's involved in.

• Fostering: Represents a fostering arrangement between a user (foster) and a cat. Attributes include id, catId (linking to the CatProfile being fostered), fosterUserId (linking to the User who is fostering the cat), startDate, endDate, and status (which can include states like pending, active, or completed).

Permissions

In Ory Keto (the authorization component of Ory), developers can express relationships using the Ory Permission Language. You can compare them to DDD Aggregates, where relations between entities and permissions are defined based on the context of the user and the entity with which they interact.

Ory uses the following terminology:

• Subjects: users or groups interacting with the system (e.g., User)

• Objects: entities in the system (e.g., CatProfile, Fostering)

• Relations: associations between objects (e.g., owns, participatesIn, includedIn)

• Permissions: actions that users can perform on objects (e.g., edit, foster, approve)

To manage access control in the CatFoster application, we will translate the user flows and entity relationships into Ory permissions:

Note: The permissions will be implemented using Ory Permission Language Code in the following steps.

Note The relations are always defined as arrays to allow multiple users or groups to be associated with a specific entity. The permissions are defined as functions that receive a context object and return a boolean value based on the user's authorization level.

Implementation Phase

In the implementation phase, we will create a new Nx workspace containing our NestJS application, configure Ory Kratos and Ory Keto using Docker Compose, and set up the necessary modules, services, controllers, and entities to integrate Ory into the CatFoster application.

Setting Up the Nx Workspace

Create a new Nx workspace using the following command:

Install the NestJS plugin for Nx:

npx nx add @nx/nest

Add a new NestJS application to the workspace:

Install the required libraries:

Intermediate workshop

Nx for Scalable Architecture

Master Nx to enforce architecture, speed up your development workflow and improve code quality

Learn more

Configuring external services

We will use Docker Compose to set up Ory Kratos and Ory Keto services. This setup will allow us to run these services locally and interact with them from our NestJS application.

To make the Ory services configuration process more straightforward and reusable for all environments (self-hosted and cloud), we will create separate (template) configuration files for Ory Kratos and Ory Keto that can be extended with environment-specific values.

As a convention, we will:

• create an infra directory at the root of our workspace to store the configuration files for Ory Kratos and Ory Keto

• prefix environment variables with the service name (e.g., kratos_ for Ory Kratos and keto_ for Ory Keto)

Note: Ory Kratos and Ory Keto supports directly using environment variables for configuration. However, using configuration files can be more convenient for managing multiple environments and sharing configurations across different services and more importantly, to configure the Ory Network (the cloud offering of Ory) tenant.

Ory Kratos Configuration

Our Ory Kratos configuration will require four different files:

kratos-template.yaml:

In this file, we use the notation @@ (array) and ## (string) as placeholders for environment-specific values that a script will substitute with actual values during deployment. This approach allows us to maintain a single configuration file template that can be customized for different environments.

The configuration file template includes settings for Ory Kratos's self-service UI, authentication methods, error handling, and session management. These settings can be adjusted based on your application's requirements and security policies.

In the configuration file:

• In dsn, we define the connection string to the Ory Kratos database. Default to memory.

• In selfservice.flows.registration.after, we define a webhook that will be consumed after a successful registration, allowing us to create our user in the local database after the user has signed up with Ory Kratos.

• In identity.schemas, we define the path to the default schema for user identities. Leaving this field configurable allows us to provide a different identity schema when running the application in various environments.

Tips:

For a complete list of configuration options and their descriptions, refer to the Configuration Reference.

The easiest way to create a configuration file for Ory Kratos is to use the Configuration Editor tool. This tool provides a user-friendly interface to generate a configuration file based on your application's requirements and security policies.

identity.schema.json:

In this file, we set the JSON schema to represent the user identity, including the required properties, formats, and additional settings for authentication, verification, and recovery. Ory Kratos will use this schema to validate user data and enforce security policies.

Tips: You can learn more about the Ory Kratos identity schema and how to customize it for your application in the Ory Kratos documentation.

after-webhook.jsonnet:

This Jsonnet file defines the payload to be sent to the webhook server after a successful registration. In this example, we check if the user's email starts with "test-" and cancel the registration process. You can customize this file to include additional data or perform specific actions based on your application's requirements.

Tips: You can customize this file to include additional data or perform specific actions based on your application's requirements, see docs.

Ory Keto Configuration

Ory Keto's configuration is less complex than Ory Kratos, as it focuses on defining relationships between entities and permissions based on the Ory Permission Language. We will create three files for Ory Keto:

keto-template.yaml:

The namespace.location field specifies the path to the policy definitions (see the namespaces.ts file below).

Tips:

For a complete list of configuration options and their descriptions, refer to the Configuration Reference.

The easiest way to create a configuration file for Ory Keto is to use the Configuration Editor tool.

namespaces.ts:

This file defines the namespaces, relations, and permissions for Ory Keto. It includes the relationships between entities (e.g., User, CatProfile, Fostering) and the permissions that users or groups have on these entities (e.g., edit, foster, approve, etc).

The built-in types from the @ory/permission-namespace-types are defined in Typescript as follows:

Ory helpers

To substitute the placeholders in the configuration files with actual values (from the .env file), we use a script that reads environment variables and generates the final configuration files for Ory Kratos and Ory Keto.

This script makes the workflow (much) more efficient and less error-prone than manually updating the configuration files. You should check it out in the tools/ory/generate-config.ts.

We can consume it with the package.json scripts:

Note: As a convention, I created a tools directory at the root of the workspace to store the helper scripts and utilities.

Docker Compose Configuration

docker-compose.yaml:

Our Docker Compose configuration will include services for Ory Kratos, Kratos self-service UI, Ory Keto, and a PostgreSQL database to store user and cat profile data. We will also include a service for MailSlurper, a fake SMTP server that we will use to test email notifications.

Note:

The kratos-migrate and keto-migrate services run the database migrations for Ory Kratos and Ory Keto, respectively, before starting the main services.

The kratos-selfservice-ui-node service runs the self-service UI for Ory Kratos, allowing users to interact with the authentication flows with a user-friendly interface.

.env:

Create a .env file at the root of the workspace, copy the content of .env.example file, and update the following values:

Note: The keto_dsn and kratos_dsn values are the connection strings for the PostgreSQL databases used by Ory Keto and Ory Kratos, respectively. These values should match the database services' configurations in the docker-compose.yaml file. They are set to memory by default, meaning the data will be stored in memory and lost when the service is restarted.

Testing the Configuration

To test the configuration, run the following commands:

Creating the NestJS Application

In the next steps, we will create the necessary modules, services, controllers, and entities in the NestJS application to integrate Ory Kratos and Ory Keto into the CatFoster application.

Each domain (User, CatProfile, Fostering) will have a scoped directory. Under the libs directory, we will create a user directory for user-related modules, a cat directory for cat-related modules, and a fostering directory for fostering-related modules. Each directory will contain the service, controller, and other related files in their respective subdirectories/library.

However, entities will be shared in a single directory - entities - under the libs directory to avoid circular dependencies.

Intermediate workshop

NestJS Workshop: Building for Production

Mastering NestJS: From Basics to Advanced Application Design

Learn more

Entities

Each domain will have an entity class using TypeORM decorators to define the database schema. Entities' primary and foreign keys will be UUIDs, and the relationships will be declared using the @ManyToOne, @OneToMany, or @ManyToMany decorators. In Ory Keto, the entities' names will qualify as subjects and the keys as objects.

The entities library with Nx generators:

You can refer to the entity classes in the following files:

• libs/shared/entities/src/lib/user-entities.ts

• libs/shared/entities/src/lib/catprofile-entities.ts

• libs/shared/entities/src/lib/fostering-entities.ts

Application configuration

The @nestjs/config module will load environment variables and configuration files into the NestJS application. The configuration module will be responsible for loading the Ory Kratos and Ory Keto configuration files and making them available to the application. To validate the configuration, we will create an environment-variables.ts file that checks if the required environment variables are set and the configuration files exist.

Note:

When using the cloud hosted Ory Network, ORY_KETO_ADMIN_URL, ORY_KETO_PUBLIC_URL, ORY_KRATOS_PUBLIC_URL, and ORY_KRATOS_ADMIN_URL should be configured with the Ory Network tenant URL. ORY_KETO_API_KEY and ORY_KRATOS_API_KEY should be set to the API key generated on the Ory Network tenant.

ORY_ACTION_API_KEY is a custom API key used to authenticate requests from Ory Kratos webhooks. It should be the same as the one configured in the Ory Kratos configuration file via selfservice_flows_registration_after_hook_config_auth_config_value environment variable.

The validateEnvironmentVariables function is consumed by the ConfigModule, it uses the class-validator library to validate the environment variables based on the EnvironmentVariables class. If any validation errors occur, the function throws an error with the details of the validation errors.

Creating the Users Module

The UsersModule will contain the service and controller related to user management; the library will be generated with the NestJS plugin from Nx:

The UsersController will handle Ory Kratos webhooks registered in Ory Kratos configuration to create users in the local database after successful registration and HTTP requests to get current user information.

To protect the routes, we will create the OryActionGuard that authenticates requests from Kratos webhooks and use the OryAuthenticationGuard (from @getlarge/kratos-client-wrapper) that authenticates users using the Kratos session.

Note:

The onSignUp and onSignIn methods handle the requests from the Ory Kratos webhooks for user registration and sign-in. The getCurrentUser method retrieves the current user information from the Ory Kratos session.

The OryActionGuard authenticates requests from Ory Kratos webhooks using the ORY_ACTION_API_KEY environment variable. The OryAuthenticationGuard authenticates users using the Kratos session passed in the request headers (cookie or authorization token) and sets the user information in the request object.

The paths for the onSignUp and onSignIn methods should match the paths defined in the Ory Kratos configuration file for the respective webhooks (selfservice_flows_login_after_hook_config_url and selfservice_flows_registration_after_hook_config_url)

Check the previous article for more details on the OryAuthenticationGuard

The UsersService is responsible for two tasks:

• After signing up, create an internal user and bind it to the new identity under the metadata_public field to store the user's ID in the Ory Kratos session.

• Before signing in, check if the identity has a verified email address unless the identity schema does not require email verification.

Note:

In the onSignUp method modifies the identity before its storage in the Ory Kratos DB, see documentation here. Since the identity is not created yet, the identity id is set to 00000000-0000-0000-0000-000000000000.

In the onSignIn method, if the user's email address is not verified, an error is thrown to prevent login, see documentation. This logic is similar to the original require_verified_address hook in Ory Kratos. Unless the identity schema does not require email verification, the user can log in without a verified email address. We will use this logic to skip the email verification step for our end-to-end tests. The OryWebhookError class is a custom error class that extends the HttpException class from NestJS. It formats the error response in the format expected by Ory Kratos webhooks allowing the error message to be displayed in the Self-Service UI.

Creating the Cat Profiles Module

The CatProfilesModule will contain the service and controller related to cat profile management; the library will be generated with the NestJS plugin from Nx:

The CatProfilesController will apply the permissions rules from the cat profile edition flow. It will handle CRUD operations for cat profiles and use the OryAuthenticationGuard and the OryAuthorizationGuard (from @getlarge/keto-client-wrapper) to check the user's permissions before allowing access to the routes.

Note:

The CatProfilesController uses the OryPermissionChecks decorator to define permissions that needs to be evaluated in OryAuthorizationGuard.

For more details on the OryAuthorizationGuard check the previous article and the source code in the GitHub repository.

The functions isOwnerPermission and isAdminPermission are factories constructing the stringified relationships tuples from NestJS ExecutionContext.

Note: The tuple will look like CatProfile:<catProfileId>#owners@User:<currentUserId> for the isOwnerPermission function and Group:admin#members@User:<currentUserId> for the isAdminPermission function.

The CatProfilesService will use the CatProfileSchema Repository to interact with the database. The service will also create relationships between users and cat profiles in Ory Keto.

Note:

The CatProfilesService uses the OryRelationshipsService to create relationships between users and cat profiles in Ory Keto. The createAdminRelationship and createOwnerRelationship methods create relationships between the cat profile and the admin group and the user, respectively. The deleteAdminRelationship and deleteOwnerRelationship methods delete the relationships when the cat profile is deleted.

To understand the relationship queries, refer to the Ory Keto example and the @getlarge/keto-relations-parser documentation

Creating the Fostering Module

The FosteringModule will contain the service and controller related to fostering management; the library will be generated with the NestJS plugin from Nx:

The FosteringController will implement the request fostering and approve fostering request flows. As the CatProfilesController, it will use the OryAuthenticationGuard and the OryAuthorizationGuard to authenticate and authorize the requests.

Note: The canRequestFosteringPermission, canReadFosteringPermission, canApproveFosteringPermission and canRejectFosteringPermission factories will return the following relationship tuples:

CatProfile <catProfileId>#foster@User:<userId> for the canRequestFosteringPermission function

Fostering: <fosteringId>#read@User:<userId> for the canReadFosteringPermission function

Fostering <fosteringId>#approve@User:<userId> for the canApproveFosteringPermission function

Fostering:<fosteringId>#reject@User:<userId> for the canRejectFosteringPermission function

The FosteringService will use the FosteringSchema Repository to interact with the database. When a user requests a fostering, the service will create relationships with the cat profile and the current user to limit access to the fostering request. With these relationships:

• The user who requested the fostering can edit the request

• The cat profile owner can approve or reject the fostering request

• Both can read the fostering request

Note: The catProfileRelationQuery and participantRelationQuery factories will return the following relationship tuples:

Fostering:<fosteringId>#participants@User:<userId> for the participantRelationQuery function

Fostering:<fosteringId>#catProfiles@CatProfile:<catProfileId> for the catProfileRelationQuery function

Creating the App Module

The AppModule will import the following modules: the UsersModule, the CatProfilesModule, and the FosteringModule to expose the API endpoints. The module imports and makes available globally the following modules:

• ConfigModule to load the environment variables.

• LoggerModule to log the application events with Pino.

• TypeOrmModule to configure the database connection.

Note:

When running the application in test mode, the ConfigModule will load the .env.test file; this will allow us to use a different database for end-to-end testing.

The TypeOrmModule is configured to connect to the PostgreSQL database using the POSTGRES_URL environment variable.

Testing phase

We made it; we are the Ory champions! 🏆 But wait, we must test our application to ensure everything works as expected.

Manual tests

We will start with a round of manual tests to ensure the application behaves as expected. We will create users, assign users to the admin group, edit cat profiles, and manage fostering requests.

I built some CLI tools to help you with the manual tests:

• kratos-cli will help you create users and generate session tokens to authenticate against the API.

• keto-cli will help you to create relationships and check permissions.

First of all, start the services and the API:

npx nx run cat-fostering-api:serve

Create a new user

Verify the user's email

Use the link in the email sent to the user:

• check email in the local MailSlurper UI

• open the latest email with the subject: Please verify your email address

• click on the link 🎉

Test user login

Then copy the session token (starting with ory_st) and paste it in the Authorization header for the following request:

Add the user to the admin group

Reproduce the steps above to create a new user and get the user_id, which was returned by the previous request. Then, use the keto-cli to add the user to the admin group:

It should log the generated relationship:

Check the user's permissions

Create a cat profile

Update a cat profile

Task

You can test the permissions by:

• updating a cat profile that does not belong to you, using the cat_profile_id from another user => it should be forbidden.

• updating a cat profile with an admin user => it should succeed.

Request a fostering

Task

You can test the permissions by:

• requesting a fostering for a cat profile that does not belong to the current user => it should succeed.

• requesting a fostering for a cat profile that belongs to the current user => it should be forbidden.

Check the fostering request

Approve a fostering request

Task

You can test the permissions by:

• approving a fostering request targeting the current user's cat profile => it should succeed.

• approving a fostering request targeting another user's cat profile => it should be forbidden.

Automated tests

To show you how to configure Ory for your automated tests, we will create end-to-end tests to manage cat profiles.

One of the great benefits of Ory is that you can quickly adapt the configuration for the testing environment and apply it to your Docker containers. For instance, we don't need to persist the data in the Kratos and Keto databases between tests. We can also turn off the email address verification in the Kratos configuration to simplify the testing process.

1. create .env.test at the root to use in-memory storage, and load a different identity schema that does not require email verification

2. create apps/cat-fostering-api/.env.test with a different database name

3. use Jest global setup to reconfigure Ory Kratos and Ory Keto and initialize the test database before running the tests

4. use Jest global teardown to clean up the test database and revert the Ory Kratos and Ory Keto configurations after running the tests

5. build factories to create users and cat profiles

6. write the end-to-end tests

7. start the application in test mode npx nx run cat-fostering-api:serve:test (which will set the NODE_ENV to test)

8. run the tests npx nx run cat-fostering-api-e2e:e2e

Configure the testing environment

Create a .env.test file, copy the content from the .env.example file at the root of the project and update the following variables:

Create the apps/cat-fostering-api/.env.test file:

Configure Jest global setup and teardown

We will use the Jest files auto-generated by Nx to configure the global setup and teardown hooks.

To configure the global setup, update the apps/cat-fostering-api-e2e/src/support/global-setup.ts file with:

Note:

The createTestConnection function is a helper function to ensure the test database exists and is clean. It will use the same configuration as the application.

The globalThis.__DB_CONNECTION__ will be used to destroy the connection in the global teardown.

The globalThis.__TEARDOWN_MESSAGE__ will be used to log the teardown message.

The execSync function is used to run the scripts to generate the Ory test configuration and restart the Docker containers.

Continue with the global teardown configuration in the apps/cat-fostering-api-e2e/src/support/global-teardown.ts file:

Note: The global teardown will destroy the test database connection and revert the Ory configurations to the initial state.

Create factories

The factories will wrap the CLI tools we used for the manual tests to create users and permissions. You can find them in the apps/cat-fostering-api-e2e/src/cat-fostering-api/helpers.ts.

Write the end-to-end tests

The end-to-end tests suite will use the factories to create users (including one admin) and cat profiles. To verify that the application creates relationships correctly, we will send HTTP requests to the API to test the following scenarios:

• An (authenticated) user can access their profile

• An (authenticated) user can create a cat profile

• A user can update a cat profile they own

• An admin can update any cat profile

• A user cannot update a cat profile they do not own

Conclusion

If you have made it this far, congratulations! 🎉 You have successfully integrated Ory into your NestJS application. You have learned how to configure Ory Kratos and Ory Keto for multiple environments, create libraries to interact with the Ory services, and use the Ory APIs in your application.

The following step would be to deploy the application to a cloud provider and use the Ory Network instead of the local containers, which I highly recommend and will be the topic of the upcoming post.