mirror of
https://github.com/zitadel/zitadel.git
synced 2026-07-25 18:28:00 +00:00
574e23e834
# Which Problems Are Solved The distinction between Example Applications and SDKs has not been clear. In the SDKs section a lot of Example applications where listed. Also In the SDKs it was not really clear what the SDKs actually are. Also some examples and skds are outdated and not well maintained anymore. # How the Problems Are Solved - Moved all example app guides to the Example Applications Section - Restructured SDKs Nav --> SDKs & Integrations: Frontend & Mobile, Backend & API, Management API Clients - Removed unnecessary / outdated guides - Remove ids in framework.json for frameworks which shouldn't be rendered in console ## Todos: - Update SDKs Introduction page - Add links to common oidc libs for most used frameworks --------- Co-authored-by: Mridang Agarwalla <mridang@zitadel.com>
76 lines
3.2 KiB
Plaintext
76 lines
3.2 KiB
Plaintext
---
|
||
title: Secure Nest.js API Application with ZITADEL
|
||
description: "Secure Node.js APIs in NestJS by validating access tokens with ZITADEL's introspection endpoint."
|
||
sidebar_label: NestJS
|
||
---
|
||
|
||
## ZITADEL with Node.js (NestJS)
|
||
|
||
<Callout>Community Contribution This example was created by a member of the ZITADEL community. It’s a great resource for seeing how others are building, but please note it is maintained by the community rather than the ZITADEL core team.</Callout>
|
||
|
||
|
||
This documentation section guides you through the process of integrating ZITADEL into your Node.js backend using the NestJS framework. The provided example demonstrates authentication using an OIDC (OAuth2) token introspection strategy with a ZITADEL service account for machine-to-machine communication.
|
||
|
||
## Overview
|
||
|
||
The NestJS API includes a single secured route that prints "Hello World!" when authenticated. The API expects an authorization header with a valid JWT, serving as a bearer token to authenticate the user when calling the API. The API will validate the access token on the [introspect endpoint](/apis/openidoauth/endpoints#introspection-endpoint) and receive the user from ZITADEL.
|
||
|
||
The API application utilizes [JWT with Private Key](/apis/openidoauth/authn-methods#jwt-with-private-key) for authentication against ZITADEL and accessing the introspection endpoint. Make sure to create an API Application within Zitadel and download the JSON. In this instance, we use this service account, so make sure to provide the secrets in the example application via environmental variables.
|
||
|
||
## Overview
|
||
|
||
The NestJS API includes a private endpoint `GET http://localhost:${APP_PORT}/api/v1/app`, which returns "Hello World" when authenticated. The authentication is performed using a JWT obtained through the token introspection strategy.
|
||
|
||
## Running the Example
|
||
|
||
### Prerequisites
|
||
|
||
Make sure you have Node.js and npm installed on your machine.
|
||
|
||
### ZITADEL Setup for the API
|
||
|
||
1. Create a ZITADEL instance and a project by following the steps [here](/guides/start/quickstart#3-create-your-zitadel-instance).
|
||
|
||
2. Set up an API application within your project:
|
||
- Create a new application of type "API" with authentication method "Private Key".
|
||
- Create a and save the Private Key JSON file.
|
||
|
||
### Create and Run the API
|
||
|
||
Clone or download the [example repository](https://github.com/ehwplus/zitadel-nodejs-nestjs):
|
||
|
||
```bash
|
||
git clone https://github.com/ehwplus/zitadel-nodejs-nestjs && cd zitadel-nodejs-nestjs
|
||
```
|
||
|
||
and follow the instructions here: https://github.com/ehwplus/zitadel-nodejs-nestjs/blob/main/README.md#installation
|
||
|
||
### Test the API
|
||
|
||
Call the API without authorization headers:
|
||
|
||
```bash
|
||
curl --request GET \
|
||
--url http://localhost:${APP_PORT}/api/v1/app
|
||
```
|
||
|
||
You should get a response with Status Code 401 and an error message.
|
||
|
||
Now, add an authorization header with a valid JWT obtained through ZITADEL:
|
||
|
||
```bash
|
||
export JWT=your-valid-jwt
|
||
|
||
curl --request GET \
|
||
--url http://localhost:${APP_PORT}/api/v1/app \
|
||
--header "authorization: Bearer $JWT"
|
||
```
|
||
|
||
You should now receive a response with Status Code 200 and the message:
|
||
|
||
```json
|
||
"Hello World!"
|
||
```
|
||
|
||
Congratulations! You have successfully integrated ZITADEL authentication into your NestJS API using the Token Introspection strategy.
|