ZITADEL typescript with Turborepo and Changesets

This repository contains all TypeScript and JavaScript packages and applications you need to create your own ZITADEL Login UI. The repo makes use of the build system Turbo and the Changesets CLI for versioning the packages.

⚠️ This repo and packages are in alpha state and subject to change ⚠️

The scope of functionality of this repo and packages is limited and under active development. Once the package structure is set and all APIs are fully implemented we'll move this repo to beta state. You can read the contribution guide on how to contribute. Questions can be raised in our Discord channel or as a GitHub issue.

Developing Your Own ZITADEL Login UI

We think the easiest path of getting up and running, is the following:

1. Fork and clone this repository
2. Run the ZITADEL Cloud login UI locally
3. Make changes to the code and see the effects live on your local machine
4. Study the rest of this README.md and get familiar and comfortable with how everything works.
5. Decide on a way of how you want to build and run your login UI. You can reuse ZITADEL Clouds way. But if you need more freedom, you can also import the packages you need into your self built application.

Included Apps And Packages

• login: The login UI used by ZITADEL Cloud, powered by Next.js
• @zitadel/server: core components for establishing node client connection, grpc stub
• @zitadel/client: core components for establishing web client connection, grpc stub
• @zitadel/react: shared React utilities and components built with tailwindcss
• @zitadel/next: shared Next.js utilities
• @zitadel/tsconfig: shared tsconfig.jsons used throughout the monorepo
• eslint-config-zitadel: ESLint preset

Each package and app is 100% TypeScript.

Login

The login is currently in a work in progress state. The goal is to implement a login UI, using the session API of ZITADEL, which also implements the OIDC Standard and is ready to use for everyone.

In the first phase we want to have a MVP login ready with the OIDC Standard and a basic feature set. In a second step the features will be extended.

This list should show the current implementation state, and also what is missing. You can already use the current state, and extend it with your needs.

• Local User Registration (with Password)
• User Registration and Login with external Provider
  • Google
  • GitHub
  • GitHub Enterprise
  • GitLab
  • GitLab Enterprise
  • Azure
  • Apple
  • Generic OIDC
  • Generic OAuth
  • Generic JWT
  • LDAP
  • SAML SP
• Multifactor Registration an Login
  • Passkeys
  • TOTP
  • OTP: Email Code
  • OTP: SMS Code
• Password Change/Reset
• Domain Discovery
• Branding
• OIDC Standard
  • Authorization Code Flow with PKCE
  • AuthRequest hintUserId
  • AuthRequest loginHint
  • AuthRequest prompt
    • Login
    • Select Account
    • Consent
    • Create
  • Scopes
    • `openid email profile address``
    • offline access
    • urn:zitadel:iam:org:idp:id:{idp_id}
    • urn:zitadel:iam:org:project:id:zitadel:aud
    • urn:zitadel:iam:org:id:{orgid}
  • AuthRequest UI locales

Tooling

• TypeScript for static type checking
• ESLint for code linting
• Prettier for code formatting

Useful Commands

• pnpm generate - Build proto stubs for server and client package
• pnpm build - Build all packages and the login app
• pnpm test - Test all packages and the login app
• pnpm test:watch - Rerun tests on file change
• pnpm dev - Develop all packages and the login app
• pnpm lint - Lint all packages
• pnpm changeset - Generate a changeset
• pnpm clean - Clean up all node_modules and dist folders (runs each package's clean script)

Versioning And Publishing Packages

Package publishing has been configured using Changesets. Here is their documentation for more information about the workflow.

The GitHub Action needs an NPM_TOKEN and GITHUB_TOKEN in the repository settings. The Changesets bot should also be installed on the GitHub repository.

Read the changesets documentation for more information about this automation

NPM

If you want to publish a package to the public npm registry and make them publicly available, this is already setup.

To publish packages to a private npm organization scope, remove the following from each of the package.json's

- "publishConfig": {
-  "access": "public"
- },

GitHub Package Registry

See working with the npm registry

Run Login UI

To run the application make sure to install the dependencies with

pnpm install

then setup the environment for the login application which needs a .env.local in /apps/login. Go to your instance and create a service user for the application having the IAM_OWNER manager role. This user is required to have access to create users on your primary organization and reading policy data so it can be restricted to your personal use case but we'll stick with IAM_OWNER for convenience. Create a PAT and copy the value to paste it under the ZITADEL_SERVICE_USER_TOKEN key. The file should look as follows:

ZITADEL_API_URL=[yourinstanceurl]
ZITADEL_ORG_ID=[yourprimaryorg]
ZITADEL_SERVICE_USER_TOKEN=[yourserviceuserpersonalaccesstoken]

then generate the GRPC stubs with

pnpm generate

and then run it with

pnpm dev

Open the login application with your favorite browser at localhost:3000.

Deploy to Vercel

To deploy your own version on Vercel, navigate to your instance and create a service user. Copy its id from the overview and set it as ZITADEL_SERVICE_USER_ID. Then create a personal access token (PAT), copy and set it as ZITADEL_SERVICE_USER_TOKEN, then navigate to your instance settings and make sure it gets IAM_OWNER permissions. Finally set your instance url as ZITADEL_API_URL. Make sure to set it without trailing slash.