@wisemen/nestjs-zitadel
v0.3.0
Published
A NestJS client for the Zitadel v2 API, the v2beta Project, Application, Internal Permission, Authorization, Instance and Action APIs, and the v1 Management and Admin APIs. The package provides a `ZitadelClient` that exposes the Zitadel gRPC service clien
Maintainers
Keywords
Readme
@wisemen/nestjs-zitadel
A NestJS client for the Zitadel v2 API, the v2beta Project, Application,
Internal Permission, Authorization, Instance and Action APIs, and the v1
Management and Admin APIs.
The package provides a ZitadelClient that exposes the Zitadel gRPC service
clients, plus a ZitadelModule that registers it in Nest DI with configuration
resolved at the application boundary.
Register The Module
Use ZitadelModule.forRootAsync(...) when the connection settings come from
ConfigService or another application-specific source.
import { Module } from '@nestjs/common'
import { ConfigModule, ConfigService } from '@nestjs/config'
import {
ZitadelModule,
type ZitadelModuleAsyncOptions,
type ZitadelOptions
} from '@wisemen/nestjs-zitadel'
@Module({
imports: [
ZitadelModule.forRootAsync({
imports: [ConfigModule],
inject: [ConfigService],
useFactory: (configService: ConfigService): ZitadelOptions => ({
baseUrl: configService.getOrThrow('ZITADEL_BASE_URL'),
apiToken: configService.getOrThrow('ZITADEL_API_TOKEN'),
organisationId: configService.get('ZITADEL_ORGANISATION_ID')
})
} satisfies ZitadelModuleAsyncOptions)
]
})
export class IdentityModule {}Use forRoot(...) when the values are already available statically.
Inject The Client
import { Injectable } from '@nestjs/common'
import { ZitadelClient } from '@wisemen/nestjs-zitadel'
@Injectable()
export class SyncUserFromZitadelUseCase {
constructor (
private readonly zitadelClient: ZitadelClient
) {}
async execute (userId: string): Promise<void> {
await this.zitadelClient.userClient.getUserByID({ userId })
}
}v2beta Clients
ZitadelClient exposes v2beta clients for resources that have no stable v2 API
yet:
projectClient(ProjectService): projects, roles and project grantsapplicationClient(AppService): applications and application keyspermissionClient(InternalPermissionService): administrators (instance, organization and project members)authorizationClient(AuthorizationService): authorizations (user grants of project roles)instanceClient(InstanceService): the instance and its custom and trusted domainsactionClient(ActionService): Actions v2 targets and executions
const { id: projectId } = await zitadelClient.projectClient.createProject({
organizationId: zitadelClient.defaultOrganizationId,
name: 'my-project',
projectRoleAssertion: false,
authorizationRequired: false,
projectAccessRequired: false
})These APIs are in beta: request and response shapes can still change between ZITADEL releases. Prefer them over the v1 clients for new code.
v1 Management And Admin Clients
ZitadelClient also exposes the v1 managementClient and adminClient, created
on the same authenticated transport as the v2 clients:
const { project } = await zitadelClient.managementClient.addProject({ name: 'my-project' })
await zitadelClient.adminClient.listIAMMembers({})ZITADEL has deprecated the v1 Management and Admin APIs. Use these clients only
as a fallback for operations that neither the v2 nor the v2beta clients cover.
Personal access tokens, for example, are available on the stable v2
userClient (addPersonalAccessToken).
Standalone Usage (Scripts)
The client does not need Nest DI. In a plain Node script (for example a local setup script), construct it directly from resolved options:
import { ZitadelClient, resolveZitadelOptions } from '@wisemen/nestjs-zitadel'
const zitadelClient = new ZitadelClient(resolveZitadelOptions({
baseUrl: process.env.ZITADEL_BASE_URL!,
apiToken: process.env.ZITADEL_API_TOKEN!
}))
const { org } = await zitadelClient.managementClient.getMyOrg({})v1 Management calls act on the organization of the token's user. To target
another organization, pass the x-zitadel-orgid header per call:
await zitadelClient.managementClient.addProject(
{ name: 'my-project' },
{ headers: { 'x-zitadel-orgid': zitadelClient.defaultOrganizationId } }
)The token and error interceptors are applied the same way as inside Nest. The
package's peer dependencies (@nestjs/common, reflect-metadata, ...) still
need to be installed.
Service User Access Tokens
ZitadelTokenStore gets an access token for a Zitadel service user with the
JWT bearer grant. It caches the token until a minute before it expires.
createAccessTokenGetter takes either a service user or your own
getAccessToken callback. Generated SDKs use it to authenticate.
import { createAccessTokenGetter } from '@wisemen/nestjs-zitadel'
const getAccessToken = createAccessTokenGetter({
serviceUser: { issuer, serviceUserKey, projectId } // serviceUserKey is the base64-encoded key JSON
})
const token = await getAccessToken()Errors
Zitadel gRPC errors are mapped to @wisemen/api-error subclasses of
ZitadelError (ZitadelBadRequestError, ZitadelConflictError,
ZitadelNotFoundError, ZitadelUnauthorizedApiError, ZitadelForbiddenError,
ZitadelNotImplementedError, ZitadelInternalError,
ZitadelGatewayTimeoutError). Unrecognized errors are wrapped in a
ZitadelUnknownError. Reading defaultOrganizationId without an
organisationId configured throws ZitadelUnavailableError.
