From 8d4d182c20358b004261723a7917a217bb6841b0 Mon Sep 17 00:00:00 2001 From: mffap Date: Tue, 7 Mar 2023 09:33:13 +0200 Subject: [PATCH] docs: proposal restructure (#5318) * docs: docs structure * docs: remove sdk from main nav * docs: fix broken links * docs: texts * docs: texts * docs: react example * docs: proposal restructure * remove manual, move troubleshooting * revmove duplicate item * identity providers * broken links and rel paths * examples wip * examples * navigation * support * solution scenarios * concepts * overview * Actions caution to info * suggestions from code review * remove start command again * proposed start command (with and without api) * wip startpage * startpage * broken link integrate * remove get started from nav * Apply suggestions from code review Co-authored-by: Elio Bischof --------- Co-authored-by: Fabienne Co-authored-by: Florian Forster Co-authored-by: Elio Bischof --- .../apis/actions/external-authentication.md | 2 +- docs/docs/apis/openidoauth/scopes.md | 2 +- docs/docs/concepts/features/actions.md | 10 +- docs/docs/concepts/introduction.mdx | 40 +-- docs/docs/concepts/structure/policies.md | 2 +- docs/docs/concepts/usecases/saas.md | 9 +- .../docs/examples/call-zitadel-api/dot-net.md | 2 +- docs/docs/examples/call-zitadel-api/go.md | 2 +- .../examples/identity-proxy/oauth2-proxy.md | 2 +- docs/docs/examples/introduction.mdx | 312 +++++++++++------- docs/docs/examples/libs.md | 12 - docs/docs/examples/login/angular.md | 4 +- docs/docs/examples/login/nextjs-b2b.md | 4 +- docs/docs/examples/login/nextjs.md | 2 +- docs/docs/examples/login/react.mdx | 6 +- docs/docs/examples/sdks.md | 33 ++ .../guides/integrate/access-zitadel-apis.md | 10 +- .../integrate/access-zitadel-system-api.md | 4 +- .../integrate/authenticated-mongodb-charts.md | 4 +- .../guides/integrate/client-credentials.md | 4 +- docs/docs/guides/integrate/event-api.md | 6 +- .../{ => identity-providers}/azuread-oidc.md | 11 +- .../google-oidc.mdx} | 24 +- .../identity-providers/introduction.md | 24 ++ .../integrate/oauth-recommended-flows.md | 4 +- .../{ => services}/atlassian-saml.md | 6 +- .../integrate/{ => services}/auth0-oidc.mdx | 8 +- .../integrate/{ => services}/auth0-saml.md | 6 +- .../integrate/{ => services}/aws-saml.md | 6 +- .../integrate/{ => services}/gitlab-saml.md | 6 +- .../{ => services}/gitlab-self-hosted.mdx | 8 +- .../{ => services}/pingidentity-saml.md | 6 +- docs/docs/guides/integrate/serviceusers.md | 4 +- .../manage/console/instance-settings.mdx | 4 +- docs/docs/guides/manage/customize/behavior.md | 8 +- docs/docs/guides/manage/customize/branding.md | 2 +- .../guides/manage/customize/user-metadata.md | 8 +- .../guides/manage/user/reg-create-user.md | 4 +- docs/docs/guides/overview.mdx | 30 +- docs/docs/guides/solution-scenarios/b2c.mdx | 2 +- .../solution-scenarios/configurations.mdx | 7 +- docs/docs/manuals/introduction.mdx | 27 -- docs/docs/manuals/user-login.md | 47 --- docs/docs/manuals/user-profile.md | 135 -------- docs/docs/manuals/user-register.md | 44 --- docs/docs/sdks/introduction.mdx | 133 ++++++++ .../loadbalancing-example.mdx | 2 +- .../manage/configure/configure.mdx | 2 +- .../trainings/application.md | 0 .../trainings/introduction.md | 0 .../{guides => support}/trainings/project.md | 0 .../trainings/recurring.md | 0 .../{manuals => support}/troubleshooting.md | 2 - docs/docusaurus.config.js | 24 +- docs/package.json | 3 +- docs/sidebars.js | 303 +++++++++-------- docs/src/components/list.jsx | 10 +- docs/src/pages/index.js | 203 +++++++----- docs/static/img/tech/java.svg | 41 +++ docs/static/img/tech/nodejs.svg | 1 + docs/static/img/tech/php.svg | 96 ++++++ 61 files changed, 943 insertions(+), 780 deletions(-) delete mode 100644 docs/docs/examples/libs.md create mode 100644 docs/docs/examples/sdks.md rename docs/docs/guides/integrate/{ => identity-providers}/azuread-oidc.md (94%) rename docs/docs/guides/integrate/{identity-brokering.md => identity-providers/google-oidc.mdx} (65%) create mode 100644 docs/docs/guides/integrate/identity-providers/introduction.md rename docs/docs/guides/integrate/{ => services}/atlassian-saml.md (96%) rename docs/docs/guides/integrate/{ => services}/auth0-oidc.mdx (92%) rename docs/docs/guides/integrate/{ => services}/auth0-saml.md (96%) rename docs/docs/guides/integrate/{ => services}/aws-saml.md (96%) rename docs/docs/guides/integrate/{ => services}/gitlab-saml.md (95%) rename docs/docs/guides/integrate/{ => services}/gitlab-self-hosted.mdx (91%) rename docs/docs/guides/integrate/{ => services}/pingidentity-saml.md (96%) delete mode 100644 docs/docs/manuals/introduction.mdx delete mode 100644 docs/docs/manuals/user-login.md delete mode 100644 docs/docs/manuals/user-profile.md delete mode 100644 docs/docs/manuals/user-register.md create mode 100644 docs/docs/sdks/introduction.mdx rename docs/docs/{guides => support}/trainings/application.md (100%) rename docs/docs/{guides => support}/trainings/introduction.md (100%) rename docs/docs/{guides => support}/trainings/project.md (100%) rename docs/docs/{guides => support}/trainings/recurring.md (100%) rename docs/docs/{manuals => support}/troubleshooting.md (99%) create mode 100644 docs/static/img/tech/java.svg create mode 100644 docs/static/img/tech/nodejs.svg create mode 100644 docs/static/img/tech/php.svg diff --git a/docs/docs/apis/actions/external-authentication.md b/docs/docs/apis/actions/external-authentication.md index cdd06449f7..2bf9eb09fa 100644 --- a/docs/docs/apis/actions/external-authentication.md +++ b/docs/docs/apis/actions/external-authentication.md @@ -2,7 +2,7 @@ title: External Authentication Flow --- -This flow is executed if the user logs in using an [identity provider](../../guides/integrate/identity-brokering) or using a [jwt token](../../concepts/structure/jwt_idp). +This flow is executed if the user logs in using an [identity provider](/guides/integrate/identity-providers/introduction.md) or using a [jwt token](/concepts/structure/jwt_idp). ## Post Authentication diff --git a/docs/docs/apis/openidoauth/scopes.md b/docs/docs/apis/openidoauth/scopes.md index 6e60b7a2b5..4305c6319b 100644 --- a/docs/docs/apis/openidoauth/scopes.md +++ b/docs/docs/apis/openidoauth/scopes.md @@ -24,7 +24,7 @@ In addition to the standard compliant scopes we utilize the following scopes. | Scopes | Example | Description | | :------------------------------------------------ | :----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `urn:zitadel:iam:org:project:role:{rolekey}` | `urn:zitadel:iam:org:project:role:user` | By using this scope a client can request the claim urn:zitadel:iam:roles to be asserted when possible. As an alternative approach you can enable all roles to be asserted from the [project](../../guides/manage/console/roles#authorizations) a client belongs to. | +| `urn:zitadel:iam:org:project:role:{rolekey}` | `urn:zitadel:iam:org:project:role:user` | By using this scope a client can request the claim urn:zitadel:iam:roles to be asserted when possible. As an alternative approach you can enable all roles to be asserted from the [project](/guides/manage/console/roles#authorizations) a client belongs to. | | `urn:zitadel:iam:org:id:{id}` | `urn:zitadel:iam:org:id:178204173316174381` | When requesting this scope **ZITADEL** will enforce that the user is a member of the selected organization. If the organization does not exist a failure is displayed. It will assert the `urn:zitadel:iam:user:resourceowner` claims. | | `urn:zitadel:iam:org:domain:primary:{domainname}` | `urn:zitadel:iam:org:domain:primary:acme.ch` | When requesting this scope **ZITADEL** will enforce that the user is a member of the selected organization and the username is suffixed by the provided domain. If the organization does not exist a failure is displayed | | `urn:zitadel:iam:role:{rolename}` | | | diff --git a/docs/docs/concepts/features/actions.md b/docs/docs/concepts/features/actions.md index 9e5ad3edf5..a8c5d97e43 100644 --- a/docs/docs/concepts/features/actions.md +++ b/docs/docs/concepts/features/actions.md @@ -5,10 +5,8 @@ title: Actions By using ZITADEL actions, you can manipulate ZITADELs behavior on specific Events. This is useful when you have special business requirements that ZITADEL doesn't support out-of-the-box. -:::caution -ZITADEL actions is in an early development stage. -In the [roadmap](https://zitadel.com/roadmap), you see how we are planning to expand and improve it. -Please tell us about your needs and help us prioritize further fixes and features. +:::info +We're working on Actions continuously. In the [roadmap](https://zitadel.com/roadmap), you see how we are planning to expand and improve it. Please tell us about your needs and help us prioritize further fixes and features. ::: ## Why actions? @@ -34,6 +32,6 @@ Within the JavaScript code, you can read and manipulate the state. ## Further reading -- [Assign users a role after they register using an external identity provider](../../guides/manage/customize/behavior) -- [Actions reference](../../apis/actions/introduction#action) +- [Assign users a role after they register using an external identity provider](/guides/manage/customize/behavior) +- [Actions reference](/apis/actions/introduction#action) - [Actions Marketplace: Find example actions to use in ZITADEL](https://github.com/zitadel/actions) diff --git a/docs/docs/concepts/introduction.mdx b/docs/docs/concepts/introduction.mdx index 2a1ee79a64..ed94e66444 100644 --- a/docs/docs/concepts/introduction.mdx +++ b/docs/docs/concepts/introduction.mdx @@ -2,43 +2,9 @@ title: Introduction --- -import {ListElement, ListWrapper, ICONTYPE} from '../../src/components/list'; -import Column from '../../src/components/column'; - This part of the **ZITADEL** documentation contains ZITADEL specific or general concepts required to understand the system or our guides. -Please be reminded that ZITADEL is open source — and so is the documentation. Should you happen to stumble over an incorrectness, a spelling mistake, a hard-to-understand text passage, please don’t hesitate to leave a comment or propose a corresponding change. +![Overview](/img/concepts/objects/object_overview.png) - - - - - - - - -
- - - - -
-
- - - - -
- - - - - - - - - - - - - +This overview shows the general structure of ZITADEL. +You will find more detailed explanations around the different concepts in the following sections. \ No newline at end of file diff --git a/docs/docs/concepts/structure/policies.md b/docs/docs/concepts/structure/policies.md index 9f326df7c7..6b4453dc7f 100644 --- a/docs/docs/concepts/structure/policies.md +++ b/docs/docs/concepts/structure/policies.md @@ -3,6 +3,6 @@ title: Settings/Policies --- Settings and policies are configurations of all the different parts of the Instance or an organization. For all parts we have a suitable default in the Instance. -The default configuration can be overridden for each organization, some policies are currently only available on the instance level. Learn more about our different policies [here](../../guides/manage/console/instance-settings.mdx). +The default configuration can be overridden for each organization, some policies are currently only available on the instance level. Learn more about our different policies [here](/guides/manage/console/instance-settings.mdx). API wise, settings are often called policies. You can read the proto and swagger definitions [here](../../apis/introduction.mdx). diff --git a/docs/docs/concepts/usecases/saas.md b/docs/docs/concepts/usecases/saas.md index b0a5f7ec59..a810e4377a 100644 --- a/docs/docs/concepts/usecases/saas.md +++ b/docs/docs/concepts/usecases/saas.md @@ -1,5 +1,6 @@ --- title: SaaS Product with Authentication and Authorization +sidebar_label: Software-as-a-Service --- This is an example architecture for a typical SaaS product. @@ -52,11 +53,11 @@ There are some different use cases how the login should behave and look like: 1. Restrict Organization -With the primary domain scope the organization will be restricted to the requested domain, this means only users of the requestd organization will be able to login. +With the primary domain scope the organization will be restricted to the requested domain, this means only users of the requested organization will be able to login. The private labeling (branding) and the login policy of the requested organization will be set automatically. :::note -More about the [Scopes](../../apis/openidoauth/scopes) +More about the [Scopes](/apis/openidoauth/scopes) ::: 2. Show private labeling (branding) of the project organization @@ -64,8 +65,8 @@ More about the [Scopes](../../apis/openidoauth/scopes) You can configure on project-level which branding should be shown to users. In the default the design of the instance will be shown, but as soon as the user is identified, the policy of the users organization (if specified) will be triggered. If the setting is set to `Ensure Project Resource Owner Setting`, the private labeling of the project organization will always be triggered. -The last possibility is to show the private labeling of the project organization and as soon as the user is identitfied the user organization settings will be triggered. +The last possibility is to show the private labeling of the project organization and as soon as the user is identified the user organization settings will be triggered. For this the Allow User Resource Owner Setting should be set. :::note -More about [Private Labeling](../../guides/manage/customize/branding) +More about [Private Labeling](/guides/manage/customize/branding) ::: \ No newline at end of file diff --git a/docs/docs/examples/call-zitadel-api/dot-net.md b/docs/docs/examples/call-zitadel-api/dot-net.md index 6ee08c3e2b..0ad0e4f6ce 100644 --- a/docs/docs/examples/call-zitadel-api/dot-net.md +++ b/docs/docs/examples/call-zitadel-api/dot-net.md @@ -113,6 +113,6 @@ If you've run into any other problem, don't hesitate to contact us or raise an i Now you can proceed implementing our APIs by adding more calls. -Checkout more [examples from the SDK](https://github.com/zitadel/zitadel-go/blob/main/example) or refer to our [API Docs](../../apis/introduction). +Checkout more [examples from the SDK](https://github.com/zitadel/zitadel-go/blob/main/example) or refer to our [API Docs](/apis/introduction). > This guide will be updated soon to show you how to use the SDK for your own API as well. diff --git a/docs/docs/examples/call-zitadel-api/go.md b/docs/docs/examples/call-zitadel-api/go.md index 8c685d8462..eebef207bb 100644 --- a/docs/docs/examples/call-zitadel-api/go.md +++ b/docs/docs/examples/call-zitadel-api/go.md @@ -152,6 +152,6 @@ Now you can proceed implementing our APIs by adding more calls or trying to over log.Printf("%s was created on: %s", respOverwrite.Org.Name, respOverwrite.Org.Details.CreationDate.AsTime()) } ``` -Checkout more [examples from the SDK](https://github.com/zitadel/zitadel-go/blob/main/example) or refer to our [API Docs](../../apis/introduction). +Checkout more [examples from the SDK](https://github.com/zitadel/zitadel-go/blob/main/example) or refer to our [API Docs](/apis/introduction). > This guide will be updated soon to show you how to use the SDK for your own API as well. diff --git a/docs/docs/examples/identity-proxy/oauth2-proxy.md b/docs/docs/examples/identity-proxy/oauth2-proxy.md index dc5f635fe6..f9c3a89aec 100644 --- a/docs/docs/examples/identity-proxy/oauth2-proxy.md +++ b/docs/docs/examples/identity-proxy/oauth2-proxy.md @@ -13,7 +13,7 @@ title: OAuth 2.0 Proxy Before we can start building our application we have do do a few configuration steps in ZITADEL Console. You will need to provide some information about your app. We recommend creating a new app to start from scratch. Navigate to your project and add a new application at the top of the page. Select Web Application and continue. -We recommend that you use [Authorization Code](../../apis/openidoauth/grant-types#authorization-code) for the OAuth 2.0 Proxy. +We recommend that you use [Authorization Code](/apis/openidoauth/grant-types#authorization-code) for the OAuth 2.0 Proxy. > Make sure Authentication Method is set to `BASIC` and the Application Type is set to `Web`. diff --git a/docs/docs/examples/introduction.mdx b/docs/docs/examples/introduction.mdx index 96825dfa46..678c390da4 100644 --- a/docs/docs/examples/introduction.mdx +++ b/docs/docs/examples/introduction.mdx @@ -2,132 +2,198 @@ title: Overview --- -import Tabs from "@theme/Tabs"; -import TabItem from "@theme/TabItem"; -import { Card, CardWrapper } from "../../src/components/card"; +Our examples cover a range of programming languages and frameworks, so no matter what you're into, we've got you covered. -Get started with ZITADEL quickly by reading a quickstart or by cloning a [ZITADEL example](https://github.com/search?q=topic%3Aexamples+org%3Azitadel) repo. +## Frontend - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +### Single Page Application -## Clone a sample project + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LanguageExampleQuickstartSDK
+ angular + AngularGuide
+ react + ReactGuide
+ vue + React🚧
- - - - - - - +### Native / Mobile App -## Libraries + + + + + + + + + + + + + + + +
LanguageExampleQuickstartSDK
+ flutter + FlutterGuide
-| Language | Description | Link | -| -------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -| Go | Go client library for ZITADEL. | [https://github.com/zitadel/zitadel-go](https://github.com/zitadel/zitadel-go) | -| .Net | Authentication / Authorization library written in dotnet for the asp.net web application package. | [https://github.com/zitadel/zitadel-net](https://github.com/zitadel/zitadel-net) | -| Dart | Dart library for ZITADEL, contains gRPC and API access elements. | [https://github.com/zitadel/zitadel-dart](https://github.com/zitadel/zitadel-dart) | -| Elixir | API Client for the ZITADEL API. | [https://github.com/jshmrtn/zitadel_api](https://github.com/jshmrtn/zitadel_api) | +### Regular Web App + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LanguageExampleQuickstartSDK
+ nextjs + NextJSGuideNextAuth Provider
+ golang + Go WebSDK
+ java + Java Spring Boot Web
+ php + PHP Web
+ python + Python3 Flask Web
+ dotnet + ASP.NET Core MVC Web
+ +## Backend + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LanguageExampleQuickstartSDK
+ golang + GolangGuideSDK
+ phyton + Python FlaskGuide
+ dotnet + ASP.NET Core WebAPIGuideSDK
+ node + NodeJS
+ php + PHP API
+ java + Java Spring Boot API
diff --git a/docs/docs/examples/libs.md b/docs/docs/examples/libs.md deleted file mode 100644 index 9f287b1d8e..0000000000 --- a/docs/docs/examples/libs.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Libraries ---- - - -| Language | Description | Link | -| ------------ | ---------------------|-------------| -| Go | Go client library for ZITADEL. | [https://github.com/zitadel/zitadel-go](https://github.com/zitadel/zitadel-go) -| .Net | Authentication / Authorization library written in dotnet for the asp.net web application package. | [https://github.com/zitadel/zitadel-net](https://github.com/zitadel/zitadel-net) -| Dart | Dart library for ZITADEL, contains gRPC and API access elements. | [https://github.com/zitadel/zitadel-dart](https://github.com/zitadel/zitadel-dart) | -| Elixir | API Client for the ZITADEL API. | [https://github.com/jshmrtn/zitadel_api](https://github.com/jshmrtn/zitadel_api) | - diff --git a/docs/docs/examples/login/angular.md b/docs/docs/examples/login/angular.md index 86e26ac2f4..774acb6d70 100644 --- a/docs/docs/examples/login/angular.md +++ b/docs/docs/examples/login/angular.md @@ -14,7 +14,7 @@ At the end of the guide, your application has login functionality and has access Before we can start building our application, we have to do a few configuration steps in ZITADEL Console. You will need to provide some information about your app. We recommend creating a new app to start from scratch. Navigate to your Project, then add a new application at the top of the page. Select **User Agent** application type and continue. -We recommend you use [Proof Key for Code Exchange (PKCE)](../../apis/openidoauth/grant-types#proof-key-for-code-exchange) for all SPA applications. +We recommend you use [Proof Key for Code Exchange (PKCE)](/apis/openidoauth/grant-types#proof-key-for-code-exchange) for all SPA applications. ![Create app in console](/img/angular/app-create.png) @@ -158,6 +158,6 @@ If you get stuck, consider checking out our [example](https://github.com/zitadel ### What's next? -Now that you have enabled authentication, it's time to add authorization to your application using ZITADEL APIs. Refer to the [docs](../../apis/introduction) or check out our ZITADEL Console code on [GitHub](https://github.com/zitadel/zitadel) which is using gRPC to access data. +Now that you have enabled authentication, it's time to add authorization to your application using ZITADEL APIs. Refer to the [docs](/apis/introduction) or check out our ZITADEL Console code on [GitHub](https://github.com/zitadel/zitadel) which is using gRPC to access data. For more information about creating an Angular application, refer to [Angular](https://angular.io/start) and for more information about the OAuth/OIDC library used above, consider reading their docs at [angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc). diff --git a/docs/docs/examples/login/nextjs-b2b.md b/docs/docs/examples/login/nextjs-b2b.md index dd98ee50f1..4f64cc6831 100644 --- a/docs/docs/examples/login/nextjs-b2b.md +++ b/docs/docs/examples/login/nextjs-b2b.md @@ -4,7 +4,7 @@ title: Next.js B2B Scenario This is our Zitadel [Next.js](https://nextjs.org/) B2B template. It shows how to authenticate as a user with multiple organizations. The application shows your users roles on the selected organizations, other projects your organization is allowed to use and other users having a grant to use the application. -If you need more info on B2B use cases consider reading our guide for the [B2B solution scenario](../../guides/solution-scenarios/b2b.mdx). +If you need more info on B2B use cases consider reading our guide for the [B2B solution scenario](/guides/solution-scenarios/b2b.mdx). > You can follow along with the template code in our [zitadel-nextjs-b2b](https://github.com/zitadel/zitadel-nextjs-b2b) repo. @@ -134,7 +134,7 @@ Let's call this new organization `Demo-Customer`. ### Users -Now switch back to the organization `Demo-Customer` and [create a new user](/manuals/user-register) in this organization. +Now switch back to the organization `Demo-Customer` and [create a new user](/guides/manage/console/users#create-user) in this organization. Let's call the first user `Alice Admin`. Create a second user called `Eric Employee`. ### Manager Role diff --git a/docs/docs/examples/login/nextjs.md b/docs/docs/examples/login/nextjs.md index b0aaf8d6ad..cd263e290e 100644 --- a/docs/docs/examples/login/nextjs.md +++ b/docs/docs/examples/login/nextjs.md @@ -30,7 +30,7 @@ Before we can start building our application, we have to do a few configuration You will need to provide some information about your app. Navigate to your Project, then add a new application at the top of the page. Select Web application type and continue. -We recommend you use [Authorization Code](../../apis/openidoauth/grant-types#authorization-code) in combination with [Proof Key for Code Exchange (PKCE)](../../apis/openidoauth/grant-types#proof-key-for-code-exchange) for all web applications. +We recommend you use [Authorization Code](/apis/openidoauth/grant-types#authorization-code) in combination with [Proof Key for Code Exchange (PKCE)](/apis/openidoauth/grant-types#proof-key-for-code-exchange) for all web applications. As the requests from your application to ZITADEL are made on NextJS serverside, you can select `CODE` in the next step. This makes sure you still get a secret which is then used in combination with PKCE. Note that the secret never gets exposed on the browser and is therefore kept in a confidential environment. ![Create app in console](/img/nextjs/app-create.png) diff --git a/docs/docs/examples/login/react.mdx b/docs/docs/examples/login/react.mdx index 99e0a9c397..f346cc55e7 100644 --- a/docs/docs/examples/login/react.mdx +++ b/docs/docs/examples/login/react.mdx @@ -11,8 +11,8 @@ At the end of the guide you should have an application able to login a user and Before we can start building our application we have to do a few configuration steps in ZITADEL Console. You will need to provide some information about your app. We recommend creating a new app to start from scratch. Navigate to your Project and add a new application at the top of the page. -Select User Agent and continue. More about the different app types can you find [here](../../guides/integrate/oauth-recommended-flows#different-client-profiles). -We recommend that you use [Authorization Code](../../apis/openidoauth/grant-types#authorization-code) in combination with [Proof Key for Code Exchange](../../apis/openidoauth/grant-types#proof-key-for-code-exchange) for all web applications. +Select User Agent and continue. More about the different app types can you find [here](/guides/integrate/oauth-recommended-flows#different-client-profiles). +We recommend that you use [Authorization Code](/apis/openidoauth/grant-types#authorization-code) in combination with [Proof Key for Code Exchange](/apis/openidoauth/grant-types#proof-key-for-code-exchange) for all web applications. ### Redirect URLs @@ -112,6 +112,6 @@ You have successfully integrated ZITADEL in your React Application! ### Whats next? -Now you can proceed implementing our APIs to include Authorization. You can find our API Docs [here](../../apis/introduction) +Now you can proceed implementing our APIs to include Authorization. You can find our API Docs [here](/apis/introduction) For more information about creating a React application we refer to [React](https://reactjs.org/docs/getting-started.html) and for more information about the used oauth/oidc library consider reading their docs at [oidc-react](https://www.npmjs.com/package/oidc-react). diff --git a/docs/docs/examples/sdks.md b/docs/docs/examples/sdks.md new file mode 100644 index 0000000000..53a639bd88 --- /dev/null +++ b/docs/docs/examples/sdks.md @@ -0,0 +1,33 @@ +--- +title: SDKs +--- + +## ZITADEL SDK + +| Language / Framework | Link Github | User Authentication | Manage resources | Notes | +|--- | --- | --- | --- | --- | +| .NET | [zitadel-net](https://github.com/smartive/zitadel-net) | ✔️ | ✔️ | `community` | +| Elixir | [zitadel_api](https://github.com/jshmrtn/zitadel_api) | ✔️ | ✔️ | `community` | +| Go | [zitadel-go](https://github.com/zitadel/zitadel-go) | ❌ | ✔️ | `official` | +| JVM | 🚧 [WIP](https://github.com/zitadel/zitadel/discussions/3650) | ❓ | ❓ | TBD | +| Python | 🚧 [WIP](https://github.com/zitadel/zitadel/issues/3675) | ❓ | ❓ | TBD | +| NodeJS | [@zitadel/node](https://www.npmjs.com/package/@zitadel/node) | ❌ | ✔️ | `community` | + +## More + +While we are not actively maintaining the following projects, it is worth checking out if you're interested in exploring ZITADEL in different programming languages or frameworks. + +- [NodeJS passport](https://github.com/buehler/node-passport-zitadel) authentication helper +- [Dart library for ZITADEL](https://github.com/smartive/zitadel-dart), contains gRPC and API access elements +- [NextAuth Provider for ZITADEL](https://next-auth.js.org/providers/zitadel) + +If we do not provide an example, SDK or guide, we strongly recommend using existing authentication libraries for your language or framework instead of building your own. +Certified libraries have undergone rigorous testing and validation to ensure high security and reliability. +There are many recommended libraries available, this saves time and ensures that users' data is well-protected. + +You might want to check out the following links to find a good library: + +- [awesome-auth](https://github.com/casbin/awesome-auth) +- [OpenID General References](https://openid.net/developers/libraries/) +- [OpenID certified libraries](https://openid.net/developers/certified/) +- [OpenID uncertified libraries](https://openid.net/developers/uncertified/) \ No newline at end of file diff --git a/docs/docs/guides/integrate/access-zitadel-apis.md b/docs/docs/guides/integrate/access-zitadel-apis.md index 46fca00a09..77f39392f9 100644 --- a/docs/docs/guides/integrate/access-zitadel-apis.md +++ b/docs/docs/guides/integrate/access-zitadel-apis.md @@ -15,7 +15,7 @@ ZITADEL Managers are Users who have permission to manage ZITADEL itself. There a - **Project Mangers**: In this level the user is able to manage a project. - **Project Grant Manager**: The project grant manager is for projects, which are granted of another organization. -On each level we have some different Roles. Here you can find more about the different roles: [ZITADEL Manager Roles](../../guides/manage/console/managers#roles) +On each level we have some different Roles. Here you can find more about the different roles: [ZITADEL Manager Roles](/guides/manage/console/managers#roles) ## Add ORG_OWNER to Service User @@ -38,7 +38,7 @@ This is already described in the [Service User](serviceusers.md), so make sure y With the encoded JWT from the prior step, you will need to craft a POST request to ZITADEL's token endpoint: To access the ZITADEL APIs you need the ZITADEL Project ID in the audience of your token. -This is possible by sending a custom scope for the audience. More about [Custom Scopes](../../apis/openidoauth/scopes) +This is possible by sending a custom scope for the audience. More about [Custom Scopes](/apis/openidoauth/scopes) Use the scope `urn:zitadel:iam:org:project:id:zitadel:aud` to include the ZITADEL project id in your audience @@ -52,7 +52,7 @@ curl --request POST \ ``` - `grant_type` must be set to `urn:ietf:params:oauth:grant-type:jwt-bearer` -- `scope` should contain any [Scopes](../../apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile` and `email` +- `scope` should contain any [Scopes](/apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile` and `email` - `assertion` is the encoded value of the JWT that was signed with your private key from the prior step You should receive a successful response with `access_token`, `token_type` and time to expiry in seconds as `expires_in`. @@ -68,7 +68,7 @@ Content-Type: application/json } ``` -With this token you are allowed to access the [ZITADEL APIs](../../apis/introduction) . +With this token you are allowed to access the [ZITADEL APIs](/apis/introduction) . ## Summary @@ -78,4 +78,4 @@ With this token you are allowed to access the [ZITADEL APIs](../../apis/introduc Where to go from here: -- [ZITADEL API Documentation](../../apis/introduction) +- [ZITADEL API Documentation](/apis/introduction) diff --git a/docs/docs/guides/integrate/access-zitadel-system-api.md b/docs/docs/guides/integrate/access-zitadel-system-api.md index e049d3b16d..1f6d87c8a1 100644 --- a/docs/docs/guides/integrate/access-zitadel-system-api.md +++ b/docs/docs/guides/integrate/access-zitadel-system-api.md @@ -145,7 +145,7 @@ You should get a successful response with a `totalResult` number of 1 and the de } ``` -With this token you are allowed to access the whole [ZITADEL System API](../../apis/system). +With this token you are allowed to access the whole [ZITADEL System API](/apis/system). ## Summary @@ -155,4 +155,4 @@ With this token you are allowed to access the whole [ZITADEL System API](../../a Where to go from here: -* [ZITADEL API Documentation](../../apis/introduction) +* [ZITADEL API Documentation](/apis/introduction) diff --git a/docs/docs/guides/integrate/authenticated-mongodb-charts.md b/docs/docs/guides/integrate/authenticated-mongodb-charts.md index 61cca76b87..aee8dfc4a1 100644 --- a/docs/docs/guides/integrate/authenticated-mongodb-charts.md +++ b/docs/docs/guides/integrate/authenticated-mongodb-charts.md @@ -12,7 +12,7 @@ You will need to provide some information about your app. We recommend creating 1. Navigate to your Project 2. Add a new application at the top of the page. 3. Select Web application type and continue. -4. Use [Authorization Code](../../apis/openidoauth/grant-types#authorization-code) in combination with [Proof Key for Code Exchange (PKCE)](../../apis/openidoauth/grant-types#proof-key-for-code-exchange). +4. Use [Authorization Code](/apis/openidoauth/grant-types#authorization-code) in combination with [Proof Key for Code Exchange (PKCE)](/apis/openidoauth/grant-types#proof-key-for-code-exchange). 5. Skip the redirect settings and confirm the app creation 6. Copy the client ID, you will need to tell MongoDB Charts about it. 7. When you created the app, expand its _OIDC Configuration_ section, change the _Auth Token Type_ to _JWT_ and save the change. @@ -39,7 +39,7 @@ Your configuration should look similar to this: Embed a chart into your application now, following the corresponding [MongoDB docs](https://docs.mongodb.com/charts/saas/embed-chart-jwt-auth/). -If you've done the [Angular Quickstart](../../examples/login/angular.md), your code could look something like this: +If you've done the [Angular Quickstart](/examples/login/angular.md), your code could look something like this: ```html diff --git a/docs/docs/guides/integrate/client-credentials.md b/docs/docs/guides/integrate/client-credentials.md index 5f09fb16a5..584ce82406 100644 --- a/docs/docs/guides/integrate/client-credentials.md +++ b/docs/docs/guides/integrate/client-credentials.md @@ -29,7 +29,7 @@ To be able to access the ZITADEL APIs your service user needs permissions to ZIT 1. Go to the detail page of your organization 2. Click in the top right corner the "+" button 3. Search for your service user -4. Give the user the role you need, for the example we choose Org Owner (More about [ZITADEL Permissions](../manage/console/managers)) +4. Give the user the role you need, for the example we choose Org Owner (More about [ZITADEL Permissions](/guides/manage/console/managers)) ![Add org owner to service user](/img/guides/console-service-user-org-owner.gif) @@ -49,7 +49,7 @@ curl --request POST \ ``` * `grant_type` should be set to `client_credentials` -* `scope` should contain any [Scopes](../../apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile`, `email` +* `scope` should contain any [Scopes](/apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile`, `email` and `urn:zitadel:iam:org:project:id:zitadel:aud`. The latter provides access to the ZITADEL API. You should receive a successful response with `access_token`, `token_type` and time to expiry in seconds as `expires_in`. diff --git a/docs/docs/guides/integrate/event-api.md b/docs/docs/guides/integrate/event-api.md index afb131107d..c47a7342fb 100644 --- a/docs/docs/guides/integrate/event-api.md +++ b/docs/docs/guides/integrate/event-api.md @@ -11,7 +11,7 @@ You need to give a user the [manager role](https://zitadel.com/docs/guides/manag If you like to know more about eventsourcing/eventstore and how this works in ZITADEL, head over to our [concepts](../../concepts/eventstore/overview). ## Request Events -Call the [ListEvents](../../apis/admin) enpoint in the Administration API to get all the events you need. +Call the [ListEvents](/apis/admin) enpoint in the Administration API to get all the events you need. To further restrict your result you can add the following filters: - sequence - editor user id @@ -29,7 +29,7 @@ curl --request POST \ ## Get event types -To be able to filter for the different event types ZITADEL knows, you can request the [EventTypesList](../../apis/admin) +To be able to filter for the different event types ZITADEL knows, you can request the [EventTypesList](/apis/admin) ```bash curl --request POST \ @@ -65,7 +65,7 @@ The following example shows you the event types for a password check (failed/suc ## Get aggregate types -To be able to filter for the different aggregate types (resources) ZITADEL knows, you can request the [AggregateTypesList](../../apis/admin) +To be able to filter for the different aggregate types (resources) ZITADEL knows, you can request the [AggregateTypesList](/apis/admin) ```bash curl --request POST \ diff --git a/docs/docs/guides/integrate/azuread-oidc.md b/docs/docs/guides/integrate/identity-providers/azuread-oidc.md similarity index 94% rename from docs/docs/guides/integrate/azuread-oidc.md rename to docs/docs/guides/integrate/identity-providers/azuread-oidc.md index a0b6e05f6e..4e155663ec 100644 --- a/docs/docs/guides/integrate/azuread-oidc.md +++ b/docs/docs/guides/integrate/identity-providers/azuread-oidc.md @@ -1,5 +1,6 @@ --- -title: Connect with AzureAD through OIDC +title: Configure AzureAD as Identity Provider +sidebar_label: AzureAD --- ## AzureAD Tenant as Identity Provider for ZITADEL @@ -87,7 +88,7 @@ If you don't want your users to get this prompt when using Azure, you have to di 1. Go to the login behaviour settings of your instance or organization, depending if you like to disable it for all or just a specific organization respectively 2. Set "Multi-factor init lifetimes" to 0 -![img.png](../../../static/img/guides/login_lifetimes.png) +![img.png](/img/guides/login_lifetimes.png) #### Create user with verified email @@ -104,11 +105,11 @@ To create the user with a verified email address you must add an action. https://github.com/zitadel/actions/blob/main/examples/verify_email.js ``` -![img.png](../../../static/img/guides/action_email_verify.png) +![img.png](/img/guides/action_email_verify.png) 3. Add the action "email verify" to the flow "external authentication" and to the trigger "pre creation" -![img.png](../../../static/img/guides/action_pre_creation_email_verify.png) +![img.png](/img/guides/action_pre_creation_email_verify.png) #### Automatically redirect to Azure AD @@ -117,7 +118,7 @@ If you like to get automatically redirected to your Azure AD login instead of sh 1. Go to the login behaviour settings of your instance or organization 2. Disable login with username and password 3. Make sure you have only configured AzureAD as external identity provider -4. If you did all your settings on the organization level make sure to send the organization scope in your authorization request: [scope](../../apis/openidoauth/scopes#reserved-scopes) +4. If you did all your settings on the organization level make sure to send the organization scope in your authorization request: [scope](/apis/openidoauth/scopes#reserved-scopes) ### Test the setup diff --git a/docs/docs/guides/integrate/identity-brokering.md b/docs/docs/guides/integrate/identity-providers/google-oidc.mdx similarity index 65% rename from docs/docs/guides/integrate/identity-brokering.md rename to docs/docs/guides/integrate/identity-providers/google-oidc.mdx index 17e35162ee..640eced4a2 100644 --- a/docs/docs/guides/integrate/identity-brokering.md +++ b/docs/docs/guides/integrate/identity-providers/google-oidc.mdx @@ -1,22 +1,8 @@ --- -title: Identity Brokering +title: Configure Google as Identity Provider +sidebar_label: Google --- -## What is Identity Brokering and Federated Identities? - -Federated identity management is an arrangement built upon the trust between two or more domains. Users of these domains are allowed to access applications and services using the same identity. -This identity is known as federated identity and the pattern behind this as identity federation. - -A service provider that specializes in brokering access control between multiple service providers (also referred to as relying parties) is called identity broker. -Federated identity management is an arrangement that is made between two or more such identity brokers across organizations. - -Example: -If Google is configured as identity provider on your organization, the user will get the option to use his Google Account on the Login Screen of ZITADEL (1). -ZITADEL will redirect the user to the login screen of Google where he as to authenticated himself (2) and is sent back after he has finished that (3). -Because Google is registered as trusted identity provider the user will be able to login in with the Google account after he linked an existing ZITADEL Account or just registered a new one with the claims provided by Google (4)(5). - -![Identity Brokering](/img/guides/identity_brokering.png) - ## Register an external identity provider In this step we will add a new Google identity provider to federate identities with ZITADEL. @@ -68,17 +54,17 @@ This case describes how to change it on the organization. ### 4. Send the primary domain scope on the authorization request -ZITADEL will show a set of identity providers by default. This configuration can be changed by users with the [manager role](../../guides/manage/console/managers#roles) `IAM_OWNER`. +ZITADEL will show a set of identity providers by default. This configuration can be changed by users with the [manager role](/guides/manage/console/managers#roles) `IAM_OWNER`. An organization's login settings will be shown - as soon as the user has entered the loginname and ZITADEL can identify to which organization he belongs; or - by sending a primary domain scope. - To get your own configuration you will have to send the [primary domain scope](../../apis/openidoauth/scopes#reserved-scopes) in your [authorization request](../../guides/integrate/login-users#auth-request) . + To get your own configuration you will have to send the [primary domain scope](/apis/openidoauth/scopes#reserved-scopes) in your [authorization request](/guides/integrate/login-users#auth-request) . The primary domain scope will restrict the login to your organization, so only users of your own organization will be able to login, also your branding and policies will trigger. :::note -You need to create your own auth request with your applications parameters. Please see the docs to construct an [Auth Request](../../guides/integrate/login-users#auth-request). +You need to create your own auth request with your applications parameters. Please see the docs to construct an [Auth Request](/guides/integrate/login-users#auth-request). ::: Your user will now be able to choose Google for login instead of username/password or mfa. diff --git a/docs/docs/guides/integrate/identity-providers/introduction.md b/docs/docs/guides/integrate/identity-providers/introduction.md new file mode 100644 index 0000000000..025ddc551a --- /dev/null +++ b/docs/docs/guides/integrate/identity-providers/introduction.md @@ -0,0 +1,24 @@ +--- +title: Identity Brokering +--- + +## What is Identity Brokering and Federated Identities? + +Federated identity management is an arrangement built upon the trust between two or more domains. Users of these domains are allowed to access applications and services using the same identity. +This identity is known as federated identity and the pattern behind this as identity federation. + +A service provider that specializes in brokering access control between multiple service providers (also referred to as relying parties) is called identity broker. +Federated identity management is an arrangement that is made between two or more such identity brokers across organizations. + +Example: +If Google is configured as identity provider on your organization, the user will get the option to use his Google Account on the Login Screen of ZITADEL (1). +ZITADEL will redirect the user to the login screen of Google where he as to authenticated himself (2) and is sent back after he has finished that (3). +Because Google is registered as trusted identity provider the user will be able to login in with the Google account after he linked an existing ZITADEL Account or just registered a new one with the claims provided by Google (4)(5). + +![Identity Brokering](/img/guides/identity_brokering.png) + +## How to use external identity providers in ZITADEL + +Configure external identity providers on instance level or just for one organization via [Console](/guides/manage/console/instance-settings#identity-providers) or APIs. +The guides in this will help you to set up specific identity providers. +ZITADEL provides also templates to configure generic identity providers, which don't have a template. \ No newline at end of file diff --git a/docs/docs/guides/integrate/oauth-recommended-flows.md b/docs/docs/guides/integrate/oauth-recommended-flows.md index 508cf4f18c..835d9ed8fd 100644 --- a/docs/docs/guides/integrate/oauth-recommended-flows.md +++ b/docs/docs/guides/integrate/oauth-recommended-flows.md @@ -58,7 +58,7 @@ So what do we want to achieve with delegated authentication? - Instead of sending around the user’s credentials - Clients may access protected resources with an **access token** that is only valid for specific scope and limited lifetime (OAuth 2.x) - - Users have to **authorize** applications to access certain [**scopes**](../../apis/openidoauth/scopes) (eg, email address or custom roles). Applications can request [**claims**](../../apis/openidoauth/claims) (key:value pairs, eg email address) for the authorized scopes with the access token or ID token from ZITADEL + - Users have to **authorize** applications to access certain [**scopes**](/apis/openidoauth/scopes) (eg, email address or custom roles). Applications can request [**claims**](/apis/openidoauth/claims) (key:value pairs, eg email address) for the authorized scopes with the access token or ID token from ZITADEL - Access tokens are bearer tokens, meaning that possession of the token provides access to a resource. But the tokens expire frequently and the application must request a new access token via **refresh token** or the user must reauthenticate ![Overview federated identities](/img/guides/consulting_federated_identities_basics.png) @@ -119,7 +119,7 @@ _So what about APIs?_ We recommend using **“JWT bearer token with private key”** ([RFC7523](https://tools.ietf.org/html/rfc7523)) for Machine-to-Machine clients. -What this means is that you have to send an JWT token, containing the [standard claims for access tokens](../../apis/openidoauth/claims) and that is signed with your private key, to the token endpoint to request the access token. We will see how this works in another module about Service Accounts. +What this means is that you have to send an JWT token, containing the [standard claims for access tokens](/apis/openidoauth/claims) and that is signed with your private key, to the token endpoint to request the access token. We will see how this works in another module about Service Accounts. If you don’t have any technical limitations, you should prefer this method over other methods. diff --git a/docs/docs/guides/integrate/atlassian-saml.md b/docs/docs/guides/integrate/services/atlassian-saml.md similarity index 96% rename from docs/docs/guides/integrate/atlassian-saml.md rename to docs/docs/guides/integrate/services/atlassian-saml.md index 894ea717a8..f4e1a81d0c 100644 --- a/docs/docs/guides/integrate/atlassian-saml.md +++ b/docs/docs/guides/integrate/services/atlassian-saml.md @@ -11,9 +11,9 @@ It covers how to: Prerequisites: -- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart) -- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations) -- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects) +- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart) +- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations) +- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects) - existing Atlassian Access setup, including verified domain > We have to switch between ZITADEL and Atlassian. If the headings begin with "ZITADEL" switch to the ZITADEL diff --git a/docs/docs/guides/integrate/auth0-oidc.mdx b/docs/docs/guides/integrate/services/auth0-oidc.mdx similarity index 92% rename from docs/docs/guides/integrate/auth0-oidc.mdx rename to docs/docs/guides/integrate/services/auth0-oidc.mdx index a455ca90aa..6aa17008ba 100644 --- a/docs/docs/guides/integrate/auth0-oidc.mdx +++ b/docs/docs/guides/integrate/services/auth0-oidc.mdx @@ -2,7 +2,7 @@ title: Connect with Auth0 through OIDC --- -import CreateApp from "./application/_application.mdx"; +import CreateApp from "../application/_application.mdx"; This guide shows how to enable login with ZITADEL on Auth0. @@ -13,9 +13,9 @@ It covers how to: Prerequisites: -- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart) -- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations) -- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects) +- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart) +- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations) +- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects) - existing Auth0 tenant as described [here](https://auth0.com/docs/get-started/auth0-overview/create-tenants) > We have to switch between ZITADEL and a Auth0. If the headings begin with "ZITADEL" switch to the ZITADEL Console and if the headings start with "Auth0" please switch to the Auth0 GUI. diff --git a/docs/docs/guides/integrate/auth0-saml.md b/docs/docs/guides/integrate/services/auth0-saml.md similarity index 96% rename from docs/docs/guides/integrate/auth0-saml.md rename to docs/docs/guides/integrate/services/auth0-saml.md index 610db0a6bb..42ba1a1389 100644 --- a/docs/docs/guides/integrate/auth0-saml.md +++ b/docs/docs/guides/integrate/services/auth0-saml.md @@ -11,9 +11,9 @@ It covers how to: Prerequisites: -- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart) -- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations) -- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects) +- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart) +- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations) +- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects) - existing Auth0 tenant as described [here](https://auth0.com/docs/get-started/auth0-overview/create-tenants) > We have to switch between ZITADEL and a Auth0. If the headings begin with "ZITADEL" switch to the ZITADEL Console and diff --git a/docs/docs/guides/integrate/aws-saml.md b/docs/docs/guides/integrate/services/aws-saml.md similarity index 96% rename from docs/docs/guides/integrate/aws-saml.md rename to docs/docs/guides/integrate/services/aws-saml.md index 08219e734b..8665e165a7 100644 --- a/docs/docs/guides/integrate/aws-saml.md +++ b/docs/docs/guides/integrate/services/aws-saml.md @@ -11,9 +11,9 @@ It covers how to: Prerequisites: -- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart) -- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations) -- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects) +- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart) +- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations) +- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects) - prerequisites on AWS side [here](https://docs.aws.amazon.com/singlesignon/latest/userguide/prereqs.html). - enabled AWS SSO [here](https://docs.aws.amazon.com/singlesignon/latest/userguide/step1.html?icmpid=docs_sso_console) diff --git a/docs/docs/guides/integrate/gitlab-saml.md b/docs/docs/guides/integrate/services/gitlab-saml.md similarity index 95% rename from docs/docs/guides/integrate/gitlab-saml.md rename to docs/docs/guides/integrate/services/gitlab-saml.md index ebf54eaf2a..5a15f0a228 100644 --- a/docs/docs/guides/integrate/gitlab-saml.md +++ b/docs/docs/guides/integrate/services/gitlab-saml.md @@ -11,9 +11,9 @@ It covers how to: Prerequisites: -- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart) -- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations) -- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects) +- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart) +- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations) +- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects) - existing Gitlab SaaS Setup in the premium tier > We have to switch between ZITADEL and Gitlab. If the headings begin with "ZITADEL" switch to the ZITADEL diff --git a/docs/docs/guides/integrate/gitlab-self-hosted.mdx b/docs/docs/guides/integrate/services/gitlab-self-hosted.mdx similarity index 91% rename from docs/docs/guides/integrate/gitlab-self-hosted.mdx rename to docs/docs/guides/integrate/services/gitlab-self-hosted.mdx index bdbbd361e7..241d577c9d 100644 --- a/docs/docs/guides/integrate/gitlab-self-hosted.mdx +++ b/docs/docs/guides/integrate/services/gitlab-self-hosted.mdx @@ -2,7 +2,7 @@ title: Gitlab OmniAuth Provider --- -import CreateApp from "./application/_application.mdx"; +import CreateApp from "../application/_application.mdx"; This guide shows how to enable login with ZITADEL on self-hosted Gitlab instances. @@ -14,9 +14,9 @@ It covers how to: Prerequisites: -- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart) -- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations) -- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects) +- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart) +- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations) +- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects) - running Gitlab instance see [installation guide](https://docs.gitlab.com/ee/install/) diff --git a/docs/docs/guides/integrate/pingidentity-saml.md b/docs/docs/guides/integrate/services/pingidentity-saml.md similarity index 96% rename from docs/docs/guides/integrate/pingidentity-saml.md rename to docs/docs/guides/integrate/services/pingidentity-saml.md index a7b420ad2d..fe5b88859c 100644 --- a/docs/docs/guides/integrate/pingidentity-saml.md +++ b/docs/docs/guides/integrate/services/pingidentity-saml.md @@ -11,9 +11,9 @@ It covers how to: Prerequisites: -- existing ZITADEL Instance, if not present follow [this guide](../../guides/start/quickstart) -- existing ZITADEL Organization, if not present follow [this guide](../../guides/manage/console/organizations) -- existing ZITADEL project, if not present follow the first 3 steps [here](../../guides/manage/console/projects) +- existing ZITADEL Instance, if not present follow [this guide](/guides/start/quickstart) +- existing ZITADEL Organization, if not present follow [this guide](/guides/manage/console/organizations) +- existing ZITADEL project, if not present follow the first 3 steps [here](/guides/manage/console/projects) - existing Pingidentity environment [here](https://docs.pingidentity.com/bundle/pingone/page/wqe1564020490538.html) > We have to switch between ZITADEL and Ping Identity. If the headings begin with "ZITADEL" switch to the ZITADEL diff --git a/docs/docs/guides/integrate/serviceusers.md b/docs/docs/guides/integrate/serviceusers.md index e30fe39b83..278e4d9083 100644 --- a/docs/docs/guides/integrate/serviceusers.md +++ b/docs/docs/guides/integrate/serviceusers.md @@ -79,7 +79,7 @@ Payload * `iat` is a unix timestamp of the creation signing time of the JWT, e.g. now and must not be older than 1 hour ago * `exp` is the unix timestamp of expiry of this assertion -Please refer to [JWT_with_Private_Key](../../apis/openidoauth/authn-methods#jwt-with-private-key) in the documentation for further information. +Please refer to [JWT_with_Private_Key](/apis/openidoauth/authn-methods#jwt-with-private-key) in the documentation for further information. If you use Go, you might want to use the [provided tool](https://github.com/zitadel/zitadel-tools) to generate a JWT from the downloaded json. There are many [libraries](https://jwt.io/#libraries-io) to generate and sign JWT. @@ -97,7 +97,7 @@ curl --request POST \ ``` * `grant_type` should be set to `urn:ietf:params:oauth:grant-type:jwt-bearer` -* `scope` should contain any [Scopes](../../apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile` and `email` +* `scope` should contain any [Scopes](/apis/openidoauth/scopes) you want to include, but must include `openid`. For this example, please include `profile` and `email` * `assertion` is the encoded value of the JWT that was signed with your private key from the prior step You should receive a successful response with `access_token`, `token_type` and time to expiry in seconds as `expires_in`. diff --git a/docs/docs/guides/manage/console/instance-settings.mdx b/docs/docs/guides/manage/console/instance-settings.mdx index 1d131b4795..dfd015a933 100644 --- a/docs/docs/guides/manage/console/instance-settings.mdx +++ b/docs/docs/guides/manage/console/instance-settings.mdx @@ -133,7 +133,7 @@ You can configure all kinds of external identity providers for identity brokerin Create a new identity provider configuration and enable it in the list afterwards. For a detailed guide about how to configure a new identity provider for identity brokering have a look at our guide: -[Identity Brokering](../../../guides/integrate/identity-brokering) +[Identity Brokering](/guides/integrate/identity-providers/introduction.md) ## Password Complexity @@ -171,7 +171,7 @@ In the domain policy you have two different settings. One is the "user_login_must_be_domain", by setting this all the users within an organisation will be suffixed with the domain of the organisation. The second is "validate_org_domains" if this is set to true all created domains on an organisation must be verified per acme challenge. -More about how to verify a domain [here](../../../guides/manage/console/organizations#domain-verification-and-primary-domain). +More about how to verify a domain [here](/guides/manage/console/organizations#domain-verification-and-primary-domain). If it is set to false, all registered domain will automatically be created as verified and the users will be able to use the domain for login. ### Use email as username diff --git a/docs/docs/guides/manage/customize/behavior.md b/docs/docs/guides/manage/customize/behavior.md index 865a58457a..061ac9ef06 100644 --- a/docs/docs/guides/manage/customize/behavior.md +++ b/docs/docs/guides/manage/customize/behavior.md @@ -11,7 +11,7 @@ Before you start, make sure you have everything set up correctly. - You need to be at least a ZITADEL _ORG_OWNER_ - Your ZITADEL organization needs to have the actions feature enabled. -- [Your ZITADEL organization needs to have at least one external identity provider enabled](../../integrate/identity-brokering) +- [Your ZITADEL organization needs to have at least one external identity provider enabled](../../integrate/identity-providers/introduction.md) - [You need to have at least one role configured for a project](../console/projects) ## Copy some information for the action @@ -35,7 +35,7 @@ https://github.com/zitadel/actions/blob/main/examples/add_user_grant.js ## Run the action when a user registers -Now, make the action hook into the [external authentication flow](../../../apis/actions/external-authentication). +Now, make the action hook into the [external authentication flow](/apis/actions/external-authentication). 1. In the **Flows ** section, select the **+ New** button. 1. Select the **Flow Type** _External Authentication_. @@ -49,5 +49,5 @@ New users automatically are assiged a role now if they register by authenticatin ## What's next? -- [Read more about the concepts around actions](../../../concepts/features/actions) -- [Read more about all the options you have with actions](../../../apis/actions/introduction) +- [Read more about the concepts around actions](/concepts/features/actions) +- [Read more about all the options you have with actions](/apis/actions/introduction) diff --git a/docs/docs/guides/manage/customize/branding.md b/docs/docs/guides/manage/customize/branding.md index 7e90dfd9f7..6161a746df 100644 --- a/docs/docs/guides/manage/customize/branding.md +++ b/docs/docs/guides/manage/customize/branding.md @@ -43,7 +43,7 @@ If you like to trigger your settings for your applications you have different po ### 1. Primary Domain Scope -Send a [reserved scope](../../../apis/openidoauth/scopes) with your [authorization request](../../integrate/login-users#auth-request) to trigger your organization. +Send a [reserved scope](/apis/openidoauth/scopes) with your [authorization request](../../integrate/login-users#auth-request) to trigger your organization. The primary domain scope will restrict the login to your organization, so only users of your own organization will be able to login. You can use our [OpenID Authentication Request Playground](/apis/openidoauth/authrequest) to learn more about how to trigger an [organization's policies and branding](/apis/openidoauth/authrequest#organization-policies-and-branding). diff --git a/docs/docs/guides/manage/customize/user-metadata.md b/docs/docs/guides/manage/customize/user-metadata.md index 5b33210193..0ab6cd5695 100644 --- a/docs/docs/guides/manage/customize/user-metadata.md +++ b/docs/docs/guides/manage/customize/user-metadata.md @@ -24,7 +24,7 @@ Typical examples for user metadata include: ### Add metadata to a user -- [Add metadata](../../../manuals/user-profile#metadata) to a user +- [Add metadata](/guides/manage/customize/user-metadata) to a user - Make sure you will use this user to login during later steps ## Requesting a token @@ -47,7 +47,7 @@ export ZITADEL_DOMAIN="https://...asd.zitadel.cloud" -Grab zitadel-tools to create the [required string](../../../apis/openidoauth/authn-methods#client-secret-basic) for Basic authentication: +Grab zitadel-tools to create the [required string](/apis/openidoauth/authn-methods#client-secret-basic) for Basic authentication: ```bash git clone git@github.com:zitadel/zitadel-tools.git @@ -93,7 +93,7 @@ Export the result to the environment variable `BASIC_AUTH`. -You need to create a string as described [here](../../../apis/openidoauth/authn-methods#client-secret-basic). +You need to create a string as described [here](/apis/openidoauth/authn-methods#client-secret-basic). Use a programming language of your choice or manually create the strings with online tools (don't use these secrets for production) like: @@ -107,7 +107,7 @@ Export the result to the environment variable `BASIC_AUTH`. ### Create Auth Request -You need to create a valid auth request, including the reserved scope `urn:zitadel:iam:user:metadata`. Please refer to our API documentation for more information about [reserved scopes](../../../apis/openidoauth/scopes#reserved-scopes) or try it out in our [OIDC Authrequest Playground](/apis/openidoauth/authrequest?scope=openid%20email%20profile%20urn%3Azitadel%3Aiam%3Auser%3Ametadata). +You need to create a valid auth request, including the reserved scope `urn:zitadel:iam:user:metadata`. Please refer to our API documentation for more information about [reserved scopes](/apis/openidoauth/scopes#reserved-scopes) or try it out in our [OIDC Authrequest Playground](/apis/openidoauth/authrequest?scope=openid%20email%20profile%20urn%3Azitadel%3Aiam%3Auser%3Ametadata). Login with the user to which you have added the metadata. After the login you will be redirected. diff --git a/docs/docs/guides/manage/user/reg-create-user.md b/docs/docs/guides/manage/user/reg-create-user.md index d4788be2d5..5a889ff904 100644 --- a/docs/docs/guides/manage/user/reg-create-user.md +++ b/docs/docs/guides/manage/user/reg-create-user.md @@ -31,7 +31,7 @@ If nothing is requested, the type will not be restricted and all possibilities o If you already have a user in ZITADEL, it is possible to add passwordless later. -[Add Passwordless Registration ](../../../apis/mgmt) +[Add Passwordless Registration ](/apis/mgmt) Send the user_id in the request and you will get a link and an expiration as response. You can then customize the link the same as described above in the creation process. @@ -39,7 +39,7 @@ You can then customize the link the same as described above in the creation proc The second possibility is to send the link directly to the user per email. Use the following request in that case: -[Send Passwordless Registration ](../../../apis/mgmt) +[Send Passwordless Registration ](/apis/mgmt) ## Verified Email Address diff --git a/docs/docs/guides/overview.mdx b/docs/docs/guides/overview.mdx index 5a181447a5..18bb541cac 100644 --- a/docs/docs/guides/overview.mdx +++ b/docs/docs/guides/overview.mdx @@ -4,16 +4,23 @@ title: Overview Most applications need to know the identity of a user for access control, to securely store their data in the cloud, and provide the same personalized experience across all of the user's devices. -ZITADEL provides backend services, easy-to-use SDKs, and ready-made UI libraries to authenticate users in your application. It supports authentication using passwords and applies additional security with the help of a second factor, for example, OTP, to ensure safe and secure access. -It additionally leverages industry standards like OAuth 2.0 and OpenID Connect such that it can be easily integrated into your custom backend. +With ZITADEL you can rely on a hardened and extensible turnkey solution to solve all of your authentication and authorization needs. +We provide you with a wide range of out of the box features to accelerate your project. Multi-tenancy with branding customization, secure login, self-service, OpenID Connect, OAuth2.x, SAML2, Passwordless with FIDO2 (including Passkeys), OTP, U2F, and an unlimited audit trail is there for you, ready to use. +Execute custom code on selected events within ZITADEL to ensure perfect compatibility with your unique and complex software landscape and data models. + +## Get Started + +### Quick Start Guide + +Follow our [Quick Start Guide](/guides/start/quickstart). + +### Cloud or Self-Hosting ZITADEL can be used in two ways: + - Use the ZITADEL Cloud, our public cloud service. Use the free tier to get started in minutes. - Deploy a self-hosted ZITADEL for full control, wherever you like. - -## Help me choose - If you are unsure, opt for the gracious free tier of [ZITADEL Cloud](./manage/cloud/overview). Choose [ZITADEL Cloud](./manage/cloud/overview) if you want: @@ -29,9 +36,14 @@ Choose [ZITADEL Self-Hosted](/self-hosting/deploy/overview) if you want: - To run ZITADEL in air-gapped or regulated environments - Flexibility when you deploy updates -:::info -Support is available either through the opensource community or a support contract. -::: +## Get Help +Join our [Discord Chat](https://zitadel.com/chat) or open a [Discussion](https://github.com/zitadel/zitadel/discussions) on Github to get help from the community and the team behind ZITADEL. -With our guides, you will learn everything you need to know about specific topics. To get started, jump directly to the [get started](./start/quickstart) docs. +Cloud and Enterprise customers can additionally reach us privately via the [Support communication channels](/legal/support-services). + +## Contribute + +ZITADEL is open source — and so is the documentation. + +Should you happen to stumble over an incorrectness, a spelling mistake, a hard-to-understand text passage, please don’t hesitate to leave a comment or [contribute a corresponding change](https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md). diff --git a/docs/docs/guides/solution-scenarios/b2c.mdx b/docs/docs/guides/solution-scenarios/b2c.mdx index 14cdf06f89..afe027db6b 100644 --- a/docs/docs/guides/solution-scenarios/b2c.mdx +++ b/docs/docs/guides/solution-scenarios/b2c.mdx @@ -29,7 +29,7 @@ You can read more about how ZITADEL handles usernames [here](../manage/console/o ZITADEL gives you a basic storage for users and manages phone and email addresses. It also allows you to store your own application data such as preferences or external identifiers to the metadata of a user. If you are migrating an existing project and you already have an external identity store you can consider bulk importing your user datasets. -Read our [Management API definitions](../../apis/mgmt) for more info. If the users email is not verified or no password is set, a initialization mail will be send. +Read our [Management API definitions](/apis/mgmt) for more info. If the users email is not verified or no password is set, a initialization mail will be send. :::info Requests to the management API are rate limited. Read our [Rate limit Policy](../../legal/rate-limit-policy) for more info. diff --git a/docs/docs/guides/solution-scenarios/configurations.mdx b/docs/docs/guides/solution-scenarios/configurations.mdx index 8a732603a0..f5a11b445f 100644 --- a/docs/docs/guides/solution-scenarios/configurations.mdx +++ b/docs/docs/guides/solution-scenarios/configurations.mdx @@ -1,5 +1,6 @@ --- title: How to configure ZITADEL for your scenario +sidebar_label: FAQ Configurations --- Each customer does have different needs and use-cases. In ZITADEL you are able to configure your settings depending on your needs. @@ -14,13 +15,13 @@ If a user of this organization wants to login, you don't want them to enter thei ### Settings 1. Go to the "Identity Providers" Settings of the organization -2. Configure the needed identity provider: Read this [guide](../integrate/identity-brokering.md) if you don't know how +2. Configure the needed identity provider: Read this [guide](../integrate/identity-providers/introduction.md) if you don't know how 3. Go to the "Login Behavior and Security" settings of the organization 4. Disable "Username Password Allowed" and enable "External IDP allowed" in the Advanced Section Now your application can send either the organizations id (`urn:zitadel:iam:org:id:{id}`) or organizations primary domain (`urn:zitadel:iam:org:domain:primary:{domainname}`) scope on your authorization request to identify on which organization the users should be logged in. -More about the [scopes](../../apis/openidoauth/scopes#reserved-scopes) +More about the [scopes](/apis/openidoauth/scopes#reserved-scopes) ## Custom Application Domain per Organization @@ -45,7 +46,7 @@ This will have the following impacts: - Only allow users from selected organization to login To request the organization send either the the organization id (`urn:zitadel:iam:org:id:{id}`) or organization primary domain (`urn:zitadel:iam:org:domain:primary:{domainname}`) scope on your authentication request from your application. -More about the [scopes](../../apis/openidoauth/scopes#reserved-scopes) +More about the [scopes](/apis/openidoauth/scopes#reserved-scopes) ## Use email to login diff --git a/docs/docs/manuals/introduction.mdx b/docs/docs/manuals/introduction.mdx deleted file mode 100644 index 3bb0968ef8..0000000000 --- a/docs/docs/manuals/introduction.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Overview ---- - -import {ListElement, ListWrapper, ICONTYPE} from '../../src/components/list'; -import Column from '../../src/components/column'; - -In this section we provide manuals for different user profiles. - - - -
- - - - - - -
-
- - - - -
- - diff --git a/docs/docs/manuals/user-login.md b/docs/docs/manuals/user-login.md deleted file mode 100644 index b1dcc51b4d..0000000000 --- a/docs/docs/manuals/user-login.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Login ---- - -## Login Username - -Enter your login name in the input field. Your loginname consists of the username with @ organisation domain. E.g road.runner@acme.zitadel.cloud -If the organization is already pre-selected you do not have to enter the domain. - -![Login Username](/img/accounts_page.png) - -## Select Account - -If you already have logged in with an account in this browser. ZITADEL has stored your usersession and you will be able to choose one of the accounts. - - - -## Login with Password - -Enter you password. If you can't remember it click on the reset password link. You will get an email to set a new passwords. -![Login Password](/img/accounts_password.png) - - -## Login with One Time Password (OTP) - -If you have registered a One time password (OTP) as a second factor you need to enter your code. - -1. Open your authenticator app which you used to set up your OTP -2. Enter the code from the authenticator app in the input field of the login process - -![Login OTP](/img/accounts_multifactor.png) - -You can find out how to register OTP [here](./user-profile##one-time-password-otp). - -### Can't remember your otp - -If you have a problem with your OTP, please contact the support of your organization. - -## Login with Universal Second Factor (U2F) (FaceID, FingerPrint, etc.) - -If you have registered U2F as second factor for your account you will have to verify this factor. -1. Click the button "Verify Token" -2. Your browser/device will show you the methods you have to verify your account (e.g FingerScan, Face Recognition, External Hardware Token, etc) -3. Follow the steps your browser shows you - -![Login Multi Factor](/img/login-mfa.gif) - diff --git a/docs/docs/manuals/user-profile.md b/docs/docs/manuals/user-profile.md deleted file mode 100644 index 66c54ffc8a..0000000000 --- a/docs/docs/manuals/user-profile.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: User Profile ---- - -To get to your user profile you have to login to your ZITADEL Console {your-domain}-{randomstring}.zitadel.cloud or {your-custom-domain}. -If you have no special permissions in the ZITADEL Console, you will get directly to your profile page. -Otherwise click on your user avatar in the top right of the console. A menu will open, with the "Edit Account" button you will be redirected to your profile page. - -## Loginname - -You are able to login with some different login names. The login name consists of the username and the organization suffix. The organization suffix are the registered domains on your organization. -![Loginname](/img/manuals/console_profile_loginname.png) - -## General - -In the general section you can find your profile data and contact information. -In the profile data you can change the following data: - -- Avatar -- Username -- Firstname -- Lastname -- Nickname -- Display Name -- Gender -- Language - -In the contact information you can change your password, email and phone number. The Email and Phone number need to be verified. - -![Profile](/img/manuals/console_profile.png) - -### Change Password - -Change your password by entering your old, new and new confirmation password. - -![Change Password](/img/change_password.gif) - -### Change Email - -Click on the edit button next to the email to change your email address. -You will now get an email to verify that this is your account. This can take a moment. -Click on the button in the mail to verify the address. If you now reload your profile page the email address should be shown as verified. - -If you wait to long to verify the email, your code will probably be expired. -The get a new verification mail click on "resend code" next to the "not verified" label. - -The email doesn't need to be unique within the whole system. - -### Change Phone number - -The phone number is not mandatory withing ZITADEL. If you like to add it, you have to verify it. - -1. Click "edit button" and add your number -2. Get an SMS with a verification code to the added number -3. Click "Verify" below the added number -4. A popup with an Input field for your code will be shown -5. Enter the code a click "OK" - -Your phone number should now be verified. - -## Identity Providers - -The identity provider section shows you, if you have linked an account from another system. (e.g. Google Account, Github, Azure AD, etc) -If you have some linked accounts, in this section you can remove them, if you don't need them anymore. - -## Passwordless - -ZITADEL provides some different authentication methods, passwordless is one of them. -Passwordless has two different types, system based or system independent. - -If you use system based methods make sure to register all the different devices you need to login. (e.g. Notebook, Mobile Phone, etc) - -Examples for passwordless authentication methods are: Fingerprint, Windows Hello, Face Recognition, etc. -For device independent authentication you can use some hardware tokens. e.g. Yubikey, Solokey, etc. - -There are different options how to add a passwordless autehntication. - -1. Add directly on the current device -2. Send a registration link to your email. You can open this email and use the link on any device you like to register -3. Generate a qr code with a registration link and scann the QR Code with the device where you like to register - -Make sure to add at least to different devices or a device independent method - -![Add Passwordless fingerprint](/img/manuals/console_profile_passwordless.gif) - -## Multifactor Authentication - -Multifactor authentication means that after entering the password, you need some kind of second authentication. -At the moment ZITADEL provides Webauthn and OTP. -Webauthn uses your device to authenticate e.g Fingerprint, Face Recognition, Windows Hello. -OTP means One time password, to use this method you need to install some kind of Authenticator App like Google Authenticator, Authy, Microsoft Authenticator. - -### Fingerprint, Security Keys, Face ID, etc. - -Use a method that is provided by your device to authenticate yourself. - -1. Click the button "Add Factor" in the multifactor authentication section of your profile -2. Choose Fingerprint, Security Keys, Face ID and others -3. Enter a name which identifies your authentication (e.g iPhone Road.Runner, Mac Book 1, Yubikey), The name is used for nothing just for yourself to recognize what you have registered. -4. Your device will show you a popup to choose what method you like to register -5. Choose the method ond follow the instructions (e.g. Scan your finger, Enter Pin, etc.) - -![Add MFA Fingerprint](/img/manuals/console_profile_mfa_webauthn.gif) - -### One time Password (OTP) - -For One time password (OTP) you will need an Authenticator app of your choice that provides an authentication code. - -1. Download an Authenticator App of your choice (e.g. Authy, Google Authenticator, Microsoft Authenticator, etc.) -2. Click the button "Add Factor" in the multifactor authentication section of your profile -3. Choose OTP (One-Time-Password) -4. Scan the QR Code with your app -5. Enter the code you get in the app in the Code input field - -You will now be able to use otp as a second factor during the login process - -## Authorization - -In the authorization section you can see all the permissions and roles you have to some different applications. - -## Memberships - -Membership is the role model ZITADEL provides for itself. If you have any permissions to manage something within ZITADEL you will have a membership. -This memeberships are hierarchical and have the following layers: - -- System -- Organization -- Project -- Granted Project - -To read more about the different roles withing ZITADEL click [here](../guides/manage/console/managers.mdx). - -## Metadata - -Sometimes it is needed to store some more data on a user. This data can be stored in the metadata. diff --git a/docs/docs/manuals/user-register.md b/docs/docs/manuals/user-register.md deleted file mode 100644 index a29d8de64a..0000000000 --- a/docs/docs/manuals/user-register.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: User Register ---- - -## Organization and user registration - -ZITADEL allows users to register a organization and/or user with just a few steps. - -A. Register an organization - - 1. Create an organization - 2. Verify your email - 3. Login to ZITADEL and manage the organization - -B. Create User - 1. An administrator can create and manage users within console. - -C. Enable Self Registration for User - - 1. Create an organization as above - 2. Create custom policy - 3. Enable the "Register allowed" flag in the Login Policy - 4. Connect your application and add the applications [scope](../apis/openidoauth/scopes) to the redirect URL. - -This will enable the register option in the login dialog and will register the user within your organization if he does not already have an account. - -Register Organization -![Register Organization](/img/register.gif) - - -Create User -![Create User](/img/create-user.gif) - - -Enable Self Register -![Enable Selfregister](/img/enable-selfregister.gif) - -## Self Register - -When self registration is enabled, users can register themselves in the organization without any administrative effort. - - -Self Register -![Self Register](/img/self-register.gif) diff --git a/docs/docs/sdks/introduction.mdx b/docs/docs/sdks/introduction.mdx new file mode 100644 index 0000000000..96825dfa46 --- /dev/null +++ b/docs/docs/sdks/introduction.mdx @@ -0,0 +1,133 @@ +--- +title: Overview +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; +import { Card, CardWrapper } from "../../src/components/card"; + +Get started with ZITADEL quickly by reading a quickstart or by cloning a [ZITADEL example](https://github.com/search?q=topic%3Aexamples+org%3Azitadel) repo. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +## Clone a sample project + + + + + + + + + +## Libraries + +| Language | Description | Link | +| -------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| Go | Go client library for ZITADEL. | [https://github.com/zitadel/zitadel-go](https://github.com/zitadel/zitadel-go) | +| .Net | Authentication / Authorization library written in dotnet for the asp.net web application package. | [https://github.com/zitadel/zitadel-net](https://github.com/zitadel/zitadel-net) | +| Dart | Dart library for ZITADEL, contains gRPC and API access elements. | [https://github.com/zitadel/zitadel-dart](https://github.com/zitadel/zitadel-dart) | +| Elixir | API Client for the ZITADEL API. | [https://github.com/jshmrtn/zitadel_api](https://github.com/jshmrtn/zitadel_api) | diff --git a/docs/docs/self-hosting/deploy/loadbalancing-example/loadbalancing-example.mdx b/docs/docs/self-hosting/deploy/loadbalancing-example/loadbalancing-example.mdx index d279686644..933404c3f2 100644 --- a/docs/docs/self-hosting/deploy/loadbalancing-example/loadbalancing-example.mdx +++ b/docs/docs/self-hosting/deploy/loadbalancing-example/loadbalancing-example.mdx @@ -69,4 +69,4 @@ This is the IAM admin users login according to your configuration in the [exampl - **username**: *root@my-org.my.domain* - **password**: *RootPassword1!* -Read more about [the login process](../../manuals/user-login). +Read more about [the login process](/guides/integrate/login-users). diff --git a/docs/docs/self-hosting/manage/configure/configure.mdx b/docs/docs/self-hosting/manage/configure/configure.mdx index 2637fd8c0c..21b9a84829 100644 --- a/docs/docs/self-hosting/manage/configure/configure.mdx +++ b/docs/docs/self-hosting/manage/configure/configure.mdx @@ -77,7 +77,7 @@ This is the IAM admin users login according to your configuration in the [exampl ## What's next -- Read more about [the login process](/manuals/user-login). +- Read more about [the login process](/guides/integrate/login-users). - If you want to run ZITADEL in production, you most certainly need to [customize your own domain](./custom-domain). - Check out all possible [runtime configuration properties and their defaults in the source code](https://github.com/zitadel/zitadel/blob/main/cmd/defaults.yaml) - Check out all possible [setup step configuration properties and their defaults in the source code](https://github.com/zitadel/zitadel/blob/main/cmd/setup/steps.yaml) diff --git a/docs/docs/guides/trainings/application.md b/docs/docs/support/trainings/application.md similarity index 100% rename from docs/docs/guides/trainings/application.md rename to docs/docs/support/trainings/application.md diff --git a/docs/docs/guides/trainings/introduction.md b/docs/docs/support/trainings/introduction.md similarity index 100% rename from docs/docs/guides/trainings/introduction.md rename to docs/docs/support/trainings/introduction.md diff --git a/docs/docs/guides/trainings/project.md b/docs/docs/support/trainings/project.md similarity index 100% rename from docs/docs/guides/trainings/project.md rename to docs/docs/support/trainings/project.md diff --git a/docs/docs/guides/trainings/recurring.md b/docs/docs/support/trainings/recurring.md similarity index 100% rename from docs/docs/guides/trainings/recurring.md rename to docs/docs/support/trainings/recurring.md diff --git a/docs/docs/manuals/troubleshooting.md b/docs/docs/support/troubleshooting.md similarity index 99% rename from docs/docs/manuals/troubleshooting.md rename to docs/docs/support/troubleshooting.md index 7af5d50ae4..c70d8109e1 100644 --- a/docs/docs/manuals/troubleshooting.md +++ b/docs/docs/support/troubleshooting.md @@ -16,8 +16,6 @@ ZITADEL uses some cookies to identify the browser/user agent of the user, so it We only found this issue with iPhone users, and it was dependent on the settings of the device. -### Solution - Go to the settings of the app Safari and check in the "Experimental WebKit Features" if SameSite strict enforcement (ITP) is disabled Also check if "block all cookies" is active. If so please disable this setting. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 4acfa8c8a4..43cfb96a2c 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -65,16 +65,10 @@ module.exports = { items: [ { type: "doc", - label: "Guides", + label: "Documentation", docId: "guides/overview", position: "left", - }, - { - type: "doc", - label: "Examples", - docId: "examples/introduction", - position: "left", - }, + }, { type: "doc", label: "APIs", @@ -87,23 +81,11 @@ module.exports = { docId: "self-hosting/deploy/overview", position: "left", }, - { - type: "doc", - docId: "concepts/introduction", - label: "Concepts", - position: "left", - }, - { - type: "doc", - docId: "manuals/introduction", - label: "Help", - position: "left", - }, { type: "doc", docId: "legal/introduction", label: "Legal", - position: "left", + position: "right", }, { type: "html", diff --git a/docs/package.json b/docs/package.json index 5aa8ae9538..849f44876a 100644 --- a/docs/package.json +++ b/docs/package.json @@ -4,7 +4,8 @@ "private": true, "scripts": { "docusaurus": "docusaurus", - "start": "yarn generate && docusaurus start", + "start": "docusaurus start", + "start:api": "yarn generate && docusaurus start", "build": "yarn generate && docusaurus build --no-minify", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", diff --git a/docs/sidebars.js b/docs/sidebars.js index 80345e1450..964cc6fd0a 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -1,40 +1,4 @@ module.exports = { - examples: [ - "examples/introduction", - { - type: "category", - label: "Integrate ZITADEL Login in your App", - items: [ - "examples/login/angular", - "examples/login/react", - "examples/login/flutter", - "examples/login/nextjs", - "examples/login/nextjs-b2b", - ], - collapsed: false, - }, - { - type: "category", - label: "Secure your API", - items: ["examples/secure-api/go", "examples/secure-api/python-flask", "examples/secure-api/dot-net"], - collapsed: false, - }, - { - type: "category", - label: "Call the ZITADEL API", - items: [ - "examples/call-zitadel-api/go", - "examples/call-zitadel-api/dot-net", - ], - collapsed: false, - }, - { - type: "category", - label: "Identity Aware Proxy", - items: ["examples/identity-proxy/oauth2-proxy"], - collapsed: false, - }, - ], guides: [ "guides/overview", { @@ -43,12 +7,52 @@ module.exports = { collapsed: false, items: [ "guides/start/quickstart", + { + type: "category", + label: "Frontend", + items: [ + "examples/login/angular", + "examples/login/react", + "examples/login/flutter", + "examples/login/nextjs", + ], + collapsed: true, + }, + { + type: "category", + label: "Backend", + items: [ + "examples/secure-api/go", + "examples/secure-api/python-flask", + "examples/secure-api/dot-net" + ], + collapsed: true, + }, ], }, + "examples/sdks", + { + type: "category", + label: "Example Applications", + items: [ + "examples/introduction", + { + type: 'link', + label: 'Frontend', // The link label + href: '/examples/introduction#frontend', // The internal path + }, + { + type: 'link', + label: 'Backend', // The link label + href: '/examples/introduction#backend', // The internal path + } + ], + collapsed: true, + }, { type: "category", label: "Manage", - collapsed: false, + collapsed: true, items: [ { type: "category", @@ -84,7 +88,6 @@ module.exports = { "guides/manage/customize/branding", "guides/manage/customize/texts", "guides/manage/customize/behavior", - "guides/manage/customize/user-metadata", ], }, { @@ -92,78 +95,171 @@ module.exports = { label: "Terraform", items: ["guides/manage/terraform/basics"], }, - "guides/manage/user/reg-create-user", + { + type: "category", + label: "Users", + items: [ + "guides/manage/user/reg-create-user", + "guides/manage/customize/user-metadata", + ], + }, ], }, { type: "category", label: "Integrate", - collapsed: false, + collapsed: true, + link: { + type: 'generated-index', + title: 'Overview', + slug: 'guides/integrate', + }, items: [ - "guides/integrate/login-users", - "guides/integrate/identity-brokering", + + { + type: "category", + label: "Authenticate Users", + collapsed: true, + items: [ + "guides/integrate/login-users", + "guides/integrate/oauth-recommended-flows", + "guides/integrate/logout", + ], + }, + { + type: "category", + label: "Configure Identity Providers", + collapsed: true, + items: [ + "guides/integrate/identity-providers/introduction", + "guides/integrate/identity-providers/google-oidc", + "guides/integrate/identity-providers/azuread-oidc", + ], + }, { type: "category", label: "Access ZITADEL APIs", - collapsed: false, + collapsed: true, items: [ - "guides/integrate/serviceusers", + { + type: "category", + label: "Authenticate Service Users", + collapsed: true, + items: [ + "guides/integrate/serviceusers", + "guides/integrate/client-credentials", + "guides/integrate/pat", + ], + }, "guides/integrate/access-zitadel-apis", - "guides/integrate/client-credentials", - "guides/integrate/pat", "guides/integrate/access-zitadel-system-api", - "guides/integrate/export-and-import", "guides/integrate/event-api", + "guides/integrate/export-and-import", + { + type: "category", + label: "Example Code", + items: [ + "examples/call-zitadel-api/go", + "examples/call-zitadel-api/dot-net", + ], + collapsed: true, + }, ], }, { type: "category", - label: "OpenID Connect 1.0 Clients", - collapsed: false, + label: "Services", + collapsed: true, + items: [ + "guides/integrate/services/gitlab-self-hosted", + "guides/integrate/services/aws-saml", + "guides/integrate/services/atlassian-saml", + "guides/integrate/services/gitlab-saml", + "guides/integrate/services/auth0-oidc", + "guides/integrate/services/auth0-saml", + "guides/integrate/services/pingidentity-saml", + ], + }, + { + type: "category", + label: "Tools", + collapsed: true, items: [ - "guides/integrate/oauth-recommended-flows", - "guides/integrate/auth0-oidc", - "guides/integrate/azuread-oidc", "guides/integrate/authenticated-mongodb-charts", - "guides/integrate/gitlab-self-hosted", + "examples/identity-proxy/oauth2-proxy" ], }, - { - type: "category", - label: "SAML 2.0 Clients", - collapsed: false, - items: [ - "guides/integrate/auth0-saml", - "guides/integrate/aws-saml", - "guides/integrate/pingidentity-saml", - "guides/integrate/atlassian-saml", - "guides/integrate/gitlab-saml", - ], - }, - "guides/integrate/logout", ], }, { type: "category", label: "Solution Scenarios", - collapsed: false, + collapsed: true, items: [ "guides/solution-scenarios/introduction", "guides/solution-scenarios/b2c", "guides/solution-scenarios/b2b", + "concepts/usecases/saas", "guides/solution-scenarios/configurations", ], }, { type: "category", - label: "Trainings", + label: "Concepts", collapsed: true, items: [ - "guides/trainings/introduction", - "guides/trainings/application", - "guides/trainings/recurring", - "guides/trainings/project", - ], + "concepts/introduction", + "concepts/structure/instance", + "concepts/structure/organizations", + "concepts/structure/projects", + "concepts/structure/applications", + "concepts/structure/granted_projects", + "concepts/structure/users", + "concepts/structure/managers", + "concepts/structure/policies", + "concepts/structure/jwt_idp", + "concepts/features/actions", + "concepts/features/selfservice", + ] + }, + { + type: "category", + label: "Architecture", + collapsed: true, + items: [ + "concepts/architecture/software", + "concepts/architecture/solution", + "concepts/architecture/secrets", + "concepts/principles", + { + type: "category", + label: "Eventstore", + collapsed: true, + items: [ + "concepts/eventstore/overview", + "concepts/eventstore/implementation", + ], + }, + ] + }, + { + type: "category", + label: "Support", + collapsed: true, + items: [ + "support/troubleshooting", + { + type: "category", + label: "Trainings", + collapsed: true, + items: [ + "support/trainings/introduction", + "support/trainings/application", + "support/trainings/recurring", + "support/trainings/project", + ], + }, + ] }, ], apis: [ @@ -322,66 +418,7 @@ module.exports = { ], }, ], - concepts: [ - "concepts/introduction", - "concepts/principles", - { - type: "category", - label: "Eventstore", - collapsed: false, - items: [ - "concepts/eventstore/overview", - "concepts/eventstore/implementation", - ], - }, - { - type: "category", - label: "Architecture", - collapsed: false, - items: [ - "concepts/architecture/software", - "concepts/architecture/solution", - "concepts/architecture/secrets", - ], - }, - { - type: "category", - label: "Structure", - collapsed: false, - items: [ - "concepts/structure/overview", - "concepts/structure/instance", - "concepts/structure/organizations", - "concepts/structure/projects", - "concepts/structure/applications", - "concepts/structure/granted_projects", - "concepts/structure/users", - "concepts/structure/managers", - "concepts/structure/policies", - "concepts/structure/jwt_idp", - ], - }, - { - type: "category", - label: "Use Cases", - collapsed: false, - items: ["concepts/usecases/saas"], - }, - { - type: "category", - label: "Features", - collapsed: false, - items: [ - "concepts/features/actions", - "concepts/features/selfservice" - ], - }, - ], - manuals: [ - "manuals/introduction", - "manuals/user-profile", - "manuals/user-login", - "manuals/troubleshooting", + support: [ ], legal: [ "legal/introduction", diff --git a/docs/src/components/list.jsx b/docs/src/components/list.jsx index 276b2ba280..585d214088 100644 --- a/docs/src/components/list.jsx +++ b/docs/src/components/list.jsx @@ -142,7 +142,15 @@ export function ListElement({ description, }) { return ( - + { + window.plausible("ListElement", { + props: { method: title }, + }); + }} + > {type ? type : iconClasses && ( diff --git a/docs/src/pages/index.js b/docs/src/pages/index.js index 3edd344940..695fd896b6 100644 --- a/docs/src/pages/index.js +++ b/docs/src/pages/index.js @@ -17,14 +17,13 @@ import styles from "./styles.module.css"; const features = [ { - title: "Guides", + title: "Documentation", // TODO: Plausible darkImageUrl: "img/index/Guides-dark.svg", lightImageUrl: "img/index/Guides-light.svg", link: "guides/overview", description: ( <> - Read our guides on how to manage your data and role associations in - ZITADEL and on what we recommend. + Read our documentation and learn how you can setup, customize, and integrate authentication and authorization to your project. ), content: ( @@ -37,27 +36,35 @@ const features = [ title="Get started" description="" /> - - - + + + + +
- + + -
@@ -89,43 +102,42 @@ const features = [ ), }, { - title: "Quickstarts", + title: "Get Started", darkImageUrl: "/docs/img/index/Quickstarts-dark.svg", lightImageUrl: "img/index/Quickstarts-light.svg", link: "examples/introduction", description: ( - <> - Learn how to integrate your applications and build secure workflows and - APIs with ZITADEL - + <>Learn how to integrate your applications and build secure workflows and + APIs with ZITADEL. ), content: ( -
- - - - +
+ + + + + +
), }, @@ -141,51 +153,82 @@ const features = [
+ + + title="OIDC Endpoints" + description="" + /> + + + +
), }, { - title: "Concepts", + title: "Self-hosting", darkImageUrl: "img/index/Concepts-dark.svg", lightImageUrl: "img/index/Concepts-light.svg", - link: "concepts/introduction", + link: "/docs/self-hosting/deploy/overview", description: ( <> - Learn more about engineering and design principles, ZITADELs - architecture and used technologies. + Everything you need to know about self-hosting ZITADEL. ), content: ( + ), diff --git a/docs/static/img/tech/java.svg b/docs/static/img/tech/java.svg new file mode 100644 index 0000000000..80260a726d --- /dev/null +++ b/docs/static/img/tech/java.svg @@ -0,0 +1,41 @@ + + + + + + + + + + + + + + + + + + diff --git a/docs/static/img/tech/nodejs.svg b/docs/static/img/tech/nodejs.svg new file mode 100644 index 0000000000..41d044ac6b --- /dev/null +++ b/docs/static/img/tech/nodejs.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/static/img/tech/php.svg b/docs/static/img/tech/php.svg new file mode 100644 index 0000000000..e4f137cb4c --- /dev/null +++ b/docs/static/img/tech/php.svg @@ -0,0 +1,96 @@ + + + Official PHP Logo + + + + image/svg+xml + + Official PHP Logo + + + Colin Viebrock + + + + + + + + + + + + Copyright Colin Viebrock 1997 - All rights reserved. + + + 1997 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file