docs: typescript login (#7621)

* typescript docs

* docs

* self service part

* deploy part

* headers

* update description

* illustration description

* endpoints

* Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx

Co-authored-by: Livio Spring <livio.a@gmail.com>

* Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx

Co-authored-by: Livio Spring <livio.a@gmail.com>

* Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx

Co-authored-by: Livio Spring <livio.a@gmail.com>

* Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx

Co-authored-by: Livio Spring <livio.a@gmail.com>

* Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx

Co-authored-by: Livio Spring <livio.a@gmail.com>

* Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx

Co-authored-by: Livio Spring <livio.a@gmail.com>

* rm scope

* Update docs/docs/guides/integrate/login-ui/typescript-repo.mdx

Co-authored-by: Livio Spring <livio.a@gmail.com>

* screenshot deploy to vercel

---------

Co-authored-by: Livio Spring <livio.a@gmail.com>

docs/docs/guides/integrate/login-ui/typescript-repo.mdx

@@ -5,11 +5,10 @@ sidebar_label: Typescript Repository
 
 To replace our current golang built login UI and showcase the use of our new resource, session and OIDC APIs, we've created the [Typescript Repository](https://github.com/zitadel/typescript).
 The typescript repository contains all TypeScript and JavaScript packages and applications you need to create your own Login UI using the ZITADEL APIs.
-The repo implements the [OIDC standard](./oidc-standard)
 
 ## Included Apps And Packages
 
-- `login`: The future login UI used by ZITADEL Cloud, powered by Next.js
+- **[login](./typescript-repo#new-login-ui)**: The future 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 Tailwind CSS
@@ -17,7 +16,46 @@ The repo implements the [OIDC standard](./oidc-standard)
 - `@zitadel/tsconfig`: shared `tsconfig.json`s used throughout the monorepo
 - `eslint-config-zitadel`: ESLint preset
 
-## Implemented features of OIDC Standard
+## Login UI
+
+The new implementation of the login is based on Next.js and implements the [OIDC standard](./oidc-standard) by proxying requests to the ZITADEL backend and using the session API.
+The UI uses the branding and behaves based on the policies and settings of your instance or organization.
+It is also allows users to authenticate directly (without an OIDC context) and self service their account.
+Its set of features will increase with time and its progress will be tracked [here](./typescript-repo#implemented-features).
+
+### Architectural Overview
+
+The new login app consists of a confidential (backend) part and a browser (client side) part.
+In addition to that, the OIDC specification builds upon a proxy which is set up in the Next.js middleware. It rewrites requests of the paths `/.well-known/:path*`, `/oauth/:path*`, `/oidc/:path*` to ZITADEL.
+
+The backend side of the application is authorized using a machine user's personal access token.
+This token is used to fetch policies and settings from your instances or organization which define how users are authenticated and how the login is displayed.
+
+The frontend side of the application communicates to the backend side by using a cookie which is set by the server.
+The cookie consists of an id and a token and is bound to a session which is updated continuously.
+
+The following illustration shows the architecture of the login and a potential authentication code flow starting from an application which implements the OIDC specification respectively.
+
+![Next.js Login Architecture](/img/typescript-login-architecture.png)
+
+_Note that the illustration is just a representation of the architecture and may not specify actual endpoints._
+
+The flow starts by the `/authorize` endpoint which is intercepted by the login and forwarded to ZITADEL.
+ZITADEL interprets the request and specifically redirects back to the login app.
+It does so by redirecting to `/login`.
+The login is then able to load an [AuthRequest](/docs/apis/resources/oidc_service/oidc-service-get-auth-request#get-oidc-auth-request-details).
+
+The Auth Request defines how users proceed to authenticate. If no special prompts or scopes are set, the login brings up the `/loginname` page.
+The /loginname page allows to enter loginname or email of a user. User discovery is implemented at /api/loginname and if the user is found, they will be redirected to the available authentication method page.
+Right after the user is found, a session is created and set as cookie.
+This cookie is then hydrated with more information once the users continues.
+The OIDC Auth request is always passed in the url to have a context to the ongoing authentication flow.
+If enough user information is retrieved and the user is authenticated according to the policies, the flow is finalized by [requesting a the callback url](/docs/apis/resources/oidc_service/oidc-service-create-callback) for the auth request and the user is redirected back to the application.
+The application can then request a token calling the /token endpoint of the login which is proxied to the ZITADEL API.
+
+### Implemented features
+
+#### OIDC Standard
 
 - [x] Authorization Code Flow with PKCE
 - [x] AuthRequest `hintUserId`
@@ -25,8 +63,9 @@ The repo implements the [OIDC standard](./oidc-standard)
 - [ ] AuthRequest `prompt`
   - [x] Login
   - [x] Select Account
-  - [ ] Consent
   - [x] Create
+  - [x] None
+  - [ ] Consent
 - Scopes
   - [x] `openid email profile address``
   - [x] `offline access`
@@ -53,13 +92,41 @@ The repo implements the [OIDC standard](./oidc-standard)
     - [ ] Azure
     - [ ] Apple
 - Register
+
   - [x] Email Password
   - [x] Passkey
 
-## How to setup domains
+#### Self service
 
-In order to use the new login app, the domain must be registered on your instance and use https.
+The self service part of the application allows to load the login without an OIDC flow.
+Authenticated users are directly able to self service their account.
+
+- [ ] Change user information
+- [ ] Password Change
+- [x] Setup Passkey
+- [ ] Setup Multifactor TOTP
+- [ ] Setup Multifactor Passkey (U2F)
+- [ ] Validate Account (email verification)
+
+### Setup
+
+In order to run the new login app, make sure to follow the instructions in the [Readme](https://github.com/zitadel/typescript/blob/main/README.md#run-login-ui).
+
+#### How to setup domains for OIDC
+
+When setting up the new login app for OIDC, the domain must be registered on your instance and use https.
 If you are using a self hosted instance, [install](/docs/apis/resources/system/system-service-add-domain) your domain on your instance using the system service.
 
-The login using our cloud service is still experimental, but you can purchase your domain on zitadel.com, install it on your domain following [our guide](/docs/guides/manage/cloud/instances#add-custom-domain).
+If you want to use the login with your cloud instance, you can purchase your domain on zitadel.com, install it on your domain following [our guide](/docs/guides/manage/cloud/instances#add-custom-domain).
 After your domain has been verified, you can reconfigure your DNS settings in order to deploy the login on your own.
+
+#### Deploy to Vercel
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fzitadel%2Ftypescript&env=ZITADEL_API_URL,ZITADEL_SERVICE_USER_ID,ZITADEL_SERVICE_USER_TOKEN&root-directory=apps/login&envDescription=Setup%20a%20service%20account%20with%20IAM_OWNER%20membership%20on%20your%20instance%20and%20provide%20its%20id%20and%20personal%20access%20token.&project-name=zitadel-login&repository-name=zitadel-login)
+
+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.
+
+![Deploy to Vercel](/img/deploy-to-vercel.png)