diff --git a/docs/docs/guides/basics/applications.mdx b/docs/docs/guides/basics/applications.mdx
new file mode 100644
index 0000000000..3e5f21c06e
--- /dev/null
+++ b/docs/docs/guides/basics/applications.mdx
@@ -0,0 +1,103 @@
+---
+title: Applications
+---
+
+import ThemedImage from '@theme/ThemedImage';
+
+import AuthType from '../integrations/application/auth-type.mdx';
+import RedirectURIs from '../integrations/application/redirect-uris.mdx';
+import GenerateKey from '../integrations/application/generate-key.mdx';
+import ReviewConfig from '../integrations/application/review-config.mdx';
+
+
+
+
+ Description |
+ Learn what applications are and how to use. |
+
+
+ Learning Outcomes |
+
+ In this module you will:
+
+ - Get an overview of application types
+ - Learn which application type allows which authentication types
+ - Learn why Redirect URIs make login processes more secure
+
+ |
+
+
+ Prerequisites |
+
+
+ |
+
+
+
+
+## What is an application?
+
+Applications are the entry point to your project. Users either login into one of your clients and interact with them directly or use one of your API, maybe without even knowing. All applications share the roles and authorizations of their project.
+
+
+
+## Application types
+
+If you create a new application in ZITADEL Console you have to choose the type of your application. But which one do you have to choose?
+
+Detailed information about authentication types can be found [here](../authentication/login-users#create-application).
+
+
+
+### Web
+
+Server side rendered applications users interact with. For example if you develop an application using Thymeleaf in Java or Razor in .NET or want to enable SSO in Gitlab.
+
+Following authentication types can be used:
+
+
+
+### Native
+
+Applications installed on a thin client. For example on a smartphone or computer.
+
+These applications uses the Key file generated by ZITADEL to authenticate.
+
+
+
+### User Agent
+
+Applications that are executed in a web browser, for example single page applications executed in the browser developed with JavaScript frameworks like [Angular](../../quickstarts/login/angular) or [React](../../quickstarts/login/react)
+
+Following authentication types can be used:
+
+
+
+### API
+
+Applications without human interaction. These applications are accessed by other applications, so called machine to machine communication.
+
+Following authentication types can be used:
+
+
+
+## Redirect URIs
+
+
+
+## Review Configuration
+
+
+
+## Generate key for private key JWT
+
+
\ No newline at end of file
diff --git a/docs/docs/guides/integrations/application/application.mdx b/docs/docs/guides/integrations/application/application.mdx
new file mode 100644
index 0000000000..00cbbc75a7
--- /dev/null
+++ b/docs/docs/guides/integrations/application/application.mdx
@@ -0,0 +1,38 @@
+import ThemedImage from '@theme/ThemedImage';
+import AuthType from './auth-type.mdx';
+import RedirectURIs from './redirect-uris.mdx';
+import GenerateKey from './generate-key.mdx';
+import ReviewConfig from './review-config.mdx';
+
+export default function CreateApp(props) {
+ return (
+
+
Create the {props.appName ? props.appName + " app" : "application"}
+
Go to the detail page of your project and click the "+"-button in the application-section. This will lead you to the the creation wizard.
+
+
Create the app by setting a name and select the application type "Web"
+
+
Select the authentication method
+
The authentication method defines the communication flow during a login
+
+ Redirect URIs
+
+ Review your configuration
+
+ Create key for private key JWT
+
+
+ );
+}
\ No newline at end of file
diff --git a/docs/docs/guides/integrations/application/auth-type.mdx b/docs/docs/guides/integrations/application/auth-type.mdx
new file mode 100644
index 0000000000..df038e97c1
--- /dev/null
+++ b/docs/docs/guides/integrations/application/auth-type.mdx
@@ -0,0 +1,177 @@
+import ThemedImage from '@theme/ThemedImage';
+
+export default function AuthType(props) {
+ return (
+
+ {defaultAuthTypes(props.appType, props.authType)}
+
+ );
+}
+
+export function defaultAuthTypes(appType, authType) {
+ let rows;
+ switch (appType) {
+ case 'web':
+ rows = web(authType);
+ break;
+ case 'user-agent':
+ rows = userAgent(authType);
+ break;
+ break;
+ case 'api':
+ rows = api(authType);
+ break;
+ break;
+ case 'native':
+ rows = native();
+ break;
+ default:
+ return null
+ break;
+ }
+ return (
+
+
+ {rows.map((fn) => fn())}
+
+
+ );
+}
+
+export const web = (typ) => {
+ switch (typ) {
+ case 'pkce':
+ return [pkce];
+ case 'code':
+ return [code];
+ case 'jwt':
+ return [jwt];
+ case 'post':
+ return [post];
+ }
+ return [pkce, code, jwt, post]
+}
+
+export const userAgent = (typ) => {
+ switch (typ) {
+ case 'pkce':
+ return [pkce];
+ case 'implicit':
+ return [implicit];
+ }
+ return [pkce, implicit]
+}
+
+export const api = (typ) => {
+ switch (typ) {
+ case 'jwt':
+ return [jwt];
+ case 'basic':
+ return [basic];
+ }
+ return [jwt, basic]
+}
+
+export const native = () => {
+ return [() =>
+
+ Native only supports code authentication type, that's why you don't have to select any
+ |
+
]
+}
+
+export const pkce = () =>
+
+
+ |
+
+ PKCE
+ Recommended because it's the most secure.
+ |
+
+
+export const code = () =>
+
+
+ |
+
+ Code
+ Use if your application needs client id and client secret
+ |
+
+
+export const jwt = () =>
+
+
+ |
+
+ (Private Key) JWT
+ Key file to authorize your application. You can create keys after created the application see below
+ |
+
+
+export const post = () =>
+
+
+ |
+
+ Post
+ Only use if you have no other possibilities. Client id and client secret in request body
+ |
+
+
+export const implicit = () =>
+
+
+ |
+
+ Implicit
+ Only use if you have no other possibilities. The flow is objective to be removed.
+ |
+
+
+export const basic = () =>
+
+
+ |
+
+ Basic
+ The application sends username and password
+ |
+
\ No newline at end of file
diff --git a/docs/docs/guides/integrations/application/generate-key.mdx b/docs/docs/guides/integrations/application/generate-key.mdx
new file mode 100644
index 0000000000..a2439f0135
--- /dev/null
+++ b/docs/docs/guides/integrations/application/generate-key.mdx
@@ -0,0 +1,18 @@
+import ThemedImage from '@theme/ThemedImage';
+
+export default function GenerateKey(props) {
+ return (props.appType == 'api' || props.authType == 'jwt') ? (
+
+
+ After you successfully created your application with authentication type JWT your can create keys in the "KEYS" section of the app details like following video shows:
+
+
+
+ ) : null;
+}
\ No newline at end of file
diff --git a/docs/docs/guides/integrations/application/redirect-uris.mdx b/docs/docs/guides/integrations/application/redirect-uris.mdx
new file mode 100644
index 0000000000..fd19dcd763
--- /dev/null
+++ b/docs/docs/guides/integrations/application/redirect-uris.mdx
@@ -0,0 +1,38 @@
+import ThemedImage from '@theme/ThemedImage';
+import Admonition from '@theme/Admonition'
+
+export default function RedirectURIs(props) {
+ return ['web', 'native', 'user-agent'].includes(props.appType) ? (
+
+
+ During the login flow the application defines where a user is redirected to after login or logout.
+
+ ZITADEL verifies if the URL the user gets redirected to is valid by checking if one of the redirect URIs match.
+
+
+ - Redirect URIs are verified during the login process.
+ {
+ props.redirectURI ?
+ - The default redirect uri of your app is
{props.redirectURI}
+ : null
+ }
+ - Post Logout URIs are verified during the logout process.
+ {
+ props.postLogoutURI ?
+ - The default post logout uri of your app is
{props.postLogoutURI}
+ : null
+ }
+
+
+ The default redirect uri of your app is {props.redirectURI}
+
+
+
+ ) : null;
+}
diff --git a/docs/docs/guides/integrations/application/review-config.mdx b/docs/docs/guides/integrations/application/review-config.mdx
new file mode 100644
index 0000000000..0e758ce680
--- /dev/null
+++ b/docs/docs/guides/integrations/application/review-config.mdx
@@ -0,0 +1,33 @@
+import ThemedImage from '@theme/ThemedImage';
+
+export default function ReviewConfig(props) {
+ let clientObjects = []
+ if (clientID(props.appType, props.authType)) {
+ clientObjects.push('id')
+ }
+ if (clientSecret(props.appType, props.authType)) {
+ clientObjects.push('secret')
+ }
+ return clientObjects.length > 0 ? (
+
+
This page shows what will be created. After you have reviewed the configuration you can create the application.
+
Client information
+
Please make sure to safe the client {clientObjects.join(' and ')} for later user in the application.
+
+
+ ): null;
+}
+
+export function clientID(appType, authType) {
+ return ['pkce', 'code', 'jwt', 'post', 'implicit', 'basic'].includes(authType) || appType === 'native'
+}
+
+export function clientSecret(appType, authType) {
+ return ['code', 'post', 'basic'].includes(authType)
+}
\ No newline at end of file
diff --git a/docs/docs/guides/integrations/auth0.md b/docs/docs/guides/integrations/auth0.md
new file mode 100644
index 0000000000..b96bb7d5b6
--- /dev/null
+++ b/docs/docs/guides/integrations/auth0.md
@@ -0,0 +1,57 @@
+---
+title: Connect with Auth0
+---
+
+This guide shows how to enable login with ZITADEL on Auth0.
+
+It covers how to:
+
+- create and configure the application in your project
+- create and configure the connection in your Auth0 tenant
+
+Prerequisites:
+
+- existing ZITADEL organization, if not present follow [this guide](../../guides/basics/get-started#trying-out-zitadel-on-zitadelch)
+- existing project, if not present follow the first 3 steps [here](../../guides/basics/projects#exercise---create-a-simple-project)
+- 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.
+
+## **Auth0**: Create a new connection
+
+In Authentication > Enterprise
+
+1. Press the "+" button right to "OpenID Connect"
+ 
+2. Set a connection name for example "ZITADEL"
+3. The issuer url is `https:///.well-known/openid-configuration`
+4. Copy the callback URL (ending with `/login/callback`)
+
+The configuration should look like this:
+
+
+
+Next we have to switch to the ZITADEL console.
+
+## **ZITADEL**: Create the application
+
+First of all we create the application in your project.
+
+import CreateApp from "./application/application.mdx";
+
+
+
+## **Auth0**: Connect ZITADEL
+
+1. Copy the client id from ZITADEL and past it into the **Client ID** field
+2. Copy the client secret from ZITADEL and past it into the **Client Secret** field
+ 
+3. click Create
+4. To verify the connection go to the "Applications" tab and enable the Default App
+ [enable app](/img/oidc/auth0/auth0-enable-app.png)
+5. Click "Back to OpenID Connect"
+6. Click on the "..." button right to the newly created connection and click "Try"
+ 
+7. ZITADEL should open on a new tab and you can enter your login information
+8. After you logged in you should see the following:
+ 
diff --git a/docs/docs/guides/integrations/gitlab-self-hosted.md b/docs/docs/guides/integrations/gitlab-self-hosted.md
new file mode 100644
index 0000000000..2b058aed54
--- /dev/null
+++ b/docs/docs/guides/integrations/gitlab-self-hosted.md
@@ -0,0 +1,52 @@
+---
+title: Gitlab OmniAuth Provider
+---
+
+This guide shows how to enable login with ZITADEL on self-hosted Gitlab instances.
+
+It covers how to:
+
+- create and configure the application in your ZITADEL project
+- create and configure the connection in a self-hosted Gitlab instance
+
+Prerequisites:
+
+- existing ZITADEL organization, if not present follow [this guide](../../guides/basics/get-started#trying-out-zitadel-on-zitadelch)
+- existing project, if not present follow the first 3 steps [here](../../guides/basics/projects#exercise---create-a-simple-project)
+- running Gitlab instance see [installation guide](https://docs.gitlab.com/ee/install/)
+
+import CreateApp from "./application/application.mdx";
+
+
+
+## Gitlab configuration
+
+Follow [this guide](https://docs.gitlab.com/ee/administration/auth/oidc.html) of gitlab to configure the omniauth provider. Following is an example configuration with redacted secrets.
+
+Replace the values of the following fields:
+
+- `args.client_options.identifier` with the `ClientId` generated by ZITADEL in the last step of [Create application in ZITADEL])()
+- `args.client_options.secret` with the `ClientSecret` generated by ZITADEL in the last step of [Create application in ZITADEL])()
+- `args.client_options.redirect_uri` with the proper URL to your gitlab instance and callback
+
+```yaml
+gitlab_rails['omniauth_providers'] = [
+ {
+ name: "openid_connect",
+ label: "ZITADEL",
+ icon: "https:///ui/console/assets/icons/favicon-32x32.png",
+ args: {
+ name: "openid_connect",
+ scope: ["openid","profile","email"],
+ response_type: "code",
+ issuer: "https://",
+ discovery: true,
+ client_options: {
+ identifier: "",
+ secret: "",
+ redirect_uri: "https:///users/auth/openid_connect/callback"
+ }
+ }
+ }
+]
+```
diff --git a/docs/sidebars.js b/docs/sidebars.js
index 6c71dd12d3..59c4d4ba8c 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -46,6 +46,7 @@ module.exports = {
"guides/basics/instance",
"guides/basics/organizations",
"guides/basics/projects",
+ "guides/basics/applications",
],
},
{
@@ -54,6 +55,8 @@ module.exports = {
collapsed: false,
items: [
"guides/integrations/authenticated-mongodb-charts",
+ "guides/integrations/auth0",
+ "guides/integrations/gitlab-self-hosted",
],
},
{
diff --git a/docs/static/img/guides/app-types-dark.png b/docs/static/img/guides/app-types-dark.png
new file mode 100644
index 0000000000..b4eeda0104
Binary files /dev/null and b/docs/static/img/guides/app-types-dark.png differ
diff --git a/docs/static/img/guides/app-types-light.png b/docs/static/img/guides/app-types-light.png
new file mode 100644
index 0000000000..b4eeda0104
Binary files /dev/null and b/docs/static/img/guides/app-types-light.png differ
diff --git a/docs/static/img/guides/application/basic-logo-dark.png b/docs/static/img/guides/application/basic-logo-dark.png
new file mode 100644
index 0000000000..9cb70e0411
Binary files /dev/null and b/docs/static/img/guides/application/basic-logo-dark.png differ
diff --git a/docs/static/img/guides/application/basic-logo-light.png b/docs/static/img/guides/application/basic-logo-light.png
new file mode 100644
index 0000000000..758d400c9d
Binary files /dev/null and b/docs/static/img/guides/application/basic-logo-light.png differ
diff --git a/docs/static/img/guides/application/client-id-dark.png b/docs/static/img/guides/application/client-id-dark.png
new file mode 100644
index 0000000000..d8cde0ba08
Binary files /dev/null and b/docs/static/img/guides/application/client-id-dark.png differ
diff --git a/docs/static/img/guides/application/client-id-light.png b/docs/static/img/guides/application/client-id-light.png
new file mode 100644
index 0000000000..d1e875f9a2
Binary files /dev/null and b/docs/static/img/guides/application/client-id-light.png differ
diff --git a/docs/static/img/guides/application/client-id-secret-dark.png b/docs/static/img/guides/application/client-id-secret-dark.png
new file mode 100644
index 0000000000..3918f2d3b9
Binary files /dev/null and b/docs/static/img/guides/application/client-id-secret-dark.png differ
diff --git a/docs/static/img/guides/application/client-id-secret-light.png b/docs/static/img/guides/application/client-id-secret-light.png
new file mode 100644
index 0000000000..3e285d926f
Binary files /dev/null and b/docs/static/img/guides/application/client-id-secret-light.png differ
diff --git a/docs/static/img/guides/application/code-logo-dark.png b/docs/static/img/guides/application/code-logo-dark.png
new file mode 100644
index 0000000000..2912db2d6d
Binary files /dev/null and b/docs/static/img/guides/application/code-logo-dark.png differ
diff --git a/docs/static/img/guides/application/code-logo-light.png b/docs/static/img/guides/application/code-logo-light.png
new file mode 100644
index 0000000000..02fb07c468
Binary files /dev/null and b/docs/static/img/guides/application/code-logo-light.png differ
diff --git a/docs/static/img/guides/application/create-api-app-dark.png b/docs/static/img/guides/application/create-api-app-dark.png
new file mode 100644
index 0000000000..852d8c6caf
Binary files /dev/null and b/docs/static/img/guides/application/create-api-app-dark.png differ
diff --git a/docs/static/img/guides/application/create-api-app-light.png b/docs/static/img/guides/application/create-api-app-light.png
new file mode 100644
index 0000000000..6514032d3b
Binary files /dev/null and b/docs/static/img/guides/application/create-api-app-light.png differ
diff --git a/docs/static/img/guides/application/create-native-app-dark.png b/docs/static/img/guides/application/create-native-app-dark.png
new file mode 100644
index 0000000000..fa5ebffab2
Binary files /dev/null and b/docs/static/img/guides/application/create-native-app-dark.png differ
diff --git a/docs/static/img/guides/application/create-native-app-light.png b/docs/static/img/guides/application/create-native-app-light.png
new file mode 100644
index 0000000000..0d52b77c3a
Binary files /dev/null and b/docs/static/img/guides/application/create-native-app-light.png differ
diff --git a/docs/static/img/guides/application/create-user-agent-app-dark.png b/docs/static/img/guides/application/create-user-agent-app-dark.png
new file mode 100644
index 0000000000..0244302ffb
Binary files /dev/null and b/docs/static/img/guides/application/create-user-agent-app-dark.png differ
diff --git a/docs/static/img/guides/application/create-user-agent-app-light.png b/docs/static/img/guides/application/create-user-agent-app-light.png
new file mode 100644
index 0000000000..4c7950e01b
Binary files /dev/null and b/docs/static/img/guides/application/create-user-agent-app-light.png differ
diff --git a/docs/static/img/guides/application/create-web-app-dark.png b/docs/static/img/guides/application/create-web-app-dark.png
new file mode 100644
index 0000000000..4895ae36b6
Binary files /dev/null and b/docs/static/img/guides/application/create-web-app-dark.png differ
diff --git a/docs/static/img/guides/application/create-web-app-light.png b/docs/static/img/guides/application/create-web-app-light.png
new file mode 100644
index 0000000000..84f429cec1
Binary files /dev/null and b/docs/static/img/guides/application/create-web-app-light.png differ
diff --git a/docs/static/img/guides/application/generate-key-dark.gif b/docs/static/img/guides/application/generate-key-dark.gif
new file mode 100644
index 0000000000..498e5ae375
Binary files /dev/null and b/docs/static/img/guides/application/generate-key-dark.gif differ
diff --git a/docs/static/img/guides/application/generate-key-light.gif b/docs/static/img/guides/application/generate-key-light.gif
new file mode 100644
index 0000000000..30ac16eca7
Binary files /dev/null and b/docs/static/img/guides/application/generate-key-light.gif differ
diff --git a/docs/static/img/guides/application/implicit-logo-dark.png b/docs/static/img/guides/application/implicit-logo-dark.png
new file mode 100644
index 0000000000..ce96546f51
Binary files /dev/null and b/docs/static/img/guides/application/implicit-logo-dark.png differ
diff --git a/docs/static/img/guides/application/implicit-logo-light.png b/docs/static/img/guides/application/implicit-logo-light.png
new file mode 100644
index 0000000000..5a51787d2f
Binary files /dev/null and b/docs/static/img/guides/application/implicit-logo-light.png differ
diff --git a/docs/static/img/guides/application/jwt-logo-dark.png b/docs/static/img/guides/application/jwt-logo-dark.png
new file mode 100644
index 0000000000..7f40f8d149
Binary files /dev/null and b/docs/static/img/guides/application/jwt-logo-dark.png differ
diff --git a/docs/static/img/guides/application/jwt-logo-light.png b/docs/static/img/guides/application/jwt-logo-light.png
new file mode 100644
index 0000000000..51c35ecea6
Binary files /dev/null and b/docs/static/img/guides/application/jwt-logo-light.png differ
diff --git a/docs/static/img/guides/application/new-app-in-project-dark.png b/docs/static/img/guides/application/new-app-in-project-dark.png
new file mode 100644
index 0000000000..db24e9b0f5
Binary files /dev/null and b/docs/static/img/guides/application/new-app-in-project-dark.png differ
diff --git a/docs/static/img/guides/application/new-app-in-project-light.png b/docs/static/img/guides/application/new-app-in-project-light.png
new file mode 100644
index 0000000000..a7ce820247
Binary files /dev/null and b/docs/static/img/guides/application/new-app-in-project-light.png differ
diff --git a/docs/static/img/guides/application/pkce-logo-dark.png b/docs/static/img/guides/application/pkce-logo-dark.png
new file mode 100644
index 0000000000..5341433019
Binary files /dev/null and b/docs/static/img/guides/application/pkce-logo-dark.png differ
diff --git a/docs/static/img/guides/application/pkce-logo-light.png b/docs/static/img/guides/application/pkce-logo-light.png
new file mode 100644
index 0000000000..f4313fe1de
Binary files /dev/null and b/docs/static/img/guides/application/pkce-logo-light.png differ
diff --git a/docs/static/img/guides/application/post-logo-dark.png b/docs/static/img/guides/application/post-logo-dark.png
new file mode 100644
index 0000000000..9dd266761f
Binary files /dev/null and b/docs/static/img/guides/application/post-logo-dark.png differ
diff --git a/docs/static/img/guides/application/post-logo-light.png b/docs/static/img/guides/application/post-logo-light.png
new file mode 100644
index 0000000000..ecb597a013
Binary files /dev/null and b/docs/static/img/guides/application/post-logo-light.png differ
diff --git a/docs/static/img/guides/application/redirect-uris-dark.png b/docs/static/img/guides/application/redirect-uris-dark.png
new file mode 100644
index 0000000000..5634864ef6
Binary files /dev/null and b/docs/static/img/guides/application/redirect-uris-dark.png differ
diff --git a/docs/static/img/guides/application/redirect-uris-light.png b/docs/static/img/guides/application/redirect-uris-light.png
new file mode 100644
index 0000000000..21e76b30b5
Binary files /dev/null and b/docs/static/img/guides/application/redirect-uris-light.png differ
diff --git a/docs/static/img/oidc/auth0/auth0-create-app.png b/docs/static/img/oidc/auth0/auth0-create-app.png
new file mode 100644
index 0000000000..60e0d9224f
Binary files /dev/null and b/docs/static/img/oidc/auth0/auth0-create-app.png differ
diff --git a/docs/static/img/oidc/auth0/auth0-enable-app.png b/docs/static/img/oidc/auth0/auth0-enable-app.png
new file mode 100644
index 0000000000..e73da2cc75
Binary files /dev/null and b/docs/static/img/oidc/auth0/auth0-enable-app.png differ
diff --git a/docs/static/img/oidc/auth0/auth0-full.png b/docs/static/img/oidc/auth0/auth0-full.png
new file mode 100644
index 0000000000..499b94c7ef
Binary files /dev/null and b/docs/static/img/oidc/auth0/auth0-full.png differ
diff --git a/docs/static/img/oidc/auth0/auth0-init-app.png b/docs/static/img/oidc/auth0/auth0-init-app.png
new file mode 100644
index 0000000000..10bdfe3a3b
Binary files /dev/null and b/docs/static/img/oidc/auth0/auth0-init-app.png differ
diff --git a/docs/static/img/oidc/auth0/auth0-try.png b/docs/static/img/oidc/auth0/auth0-try.png
new file mode 100644
index 0000000000..940ff47dc7
Binary files /dev/null and b/docs/static/img/oidc/auth0/auth0-try.png differ
diff --git a/docs/static/img/oidc/auth0/auth0-works.png b/docs/static/img/oidc/auth0/auth0-works.png
new file mode 100644
index 0000000000..35b02e8c51
Binary files /dev/null and b/docs/static/img/oidc/auth0/auth0-works.png differ