docs: add gitlab and auth0 (#3700)

* docs: add gitlab and auth0

* Apply suggestions from code review

* fix wrong domain

* Apply suggestions from code review

Co-authored-by: mffap <mpa@zitadel.com>

* fix redirect-uris

* typos

* replace image wip

* smaller typos

* Update docs/docs/guides/basics/applications.mdx

Co-authored-by: mffap <mpa@zitadel.com>

* Update docs/docs/guides/basics/applications.mdx

Co-authored-by: mffap <mpa@zitadel.com>

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>
Co-authored-by: mffap <mpa@zitadel.com>
Co-authored-by: Maximilian Panne <mpa@caos.ch>
Co-authored-by: Livio Spring <livio.a@gmail.com>

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';
+
+<table className="table-wrapper">
+  <tbody>
+      <tr>
+          <td>Description</td>
+          <td>Learn what applications are and how to use.</td>
+      </tr>
+      <tr>
+          <td>Learning Outcomes</td>
+          <td>
+              In this module you will:
+              <ul>
+                <li>Get an overview of application types</li>
+                <li>Learn which application type allows which authentication types</li>
+                <li>Learn why Redirect URIs make login processes more secure</li>
+              </ul>
+          </td>
+      </tr>
+      <tr>
+          <td>Prerequisites</td>
+          <td>
+              <ul>
+                  <li>ZITADEL <a href="./organizations">organization</a></li>
+                  <li>ZITADEL <a href="./projects">project</a></li>
+              </ul>
+          </td>
+      </tr>
+    </tbody>
+</table>
+
+## 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.
+
+<!-- TODO: oidc vs saml --->
+
+## 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).
+
+<ThemedImage
+  alt="Redirect URIs configuration"
+  sources={{
+    light: '/img/guides/app-types-light.png',
+    dark: '/img/guides/app-types-dark.png'
+  }}
+/>
+
+### 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:
+
+<AuthType appType="web"/>
+
+### 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.
+
+<AuthType appType="native"/>
+
+### 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:
+
+<AuthType appType="user-agent"/>
+
+### API
+
+Applications without human interaction. These applications are accessed by other applications, so called machine to machine communication.
+
+Following authentication types can be used:
+
+<AuthType appType="api"/>
+
+## Redirect URIs
+
+<RedirectURIs appType="web"/>
+
+## Review Configuration
+
+<ReviewConfig authType="code"/>
+
+## Generate key for private key JWT
+
+<GenerateKey appType="api"/>

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 (
+        <div>
+            <h3>Create the {props.appName ? props.appName + " app" : "application"}</h3>
+            <p>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.</p>
+            <ThemedImage
+                alt={"create " + props.appType + " preview"} 
+                sources={{
+                    light: '/img/guides/application/new-app-in-project-light.png',
+                    dark: '/img/guides/application/new-app-in-project-dark.png'
+                }}
+            />
+            <p>Create the app by setting a name and select the application type "Web"</p>
+            <ThemedImage
+                alt={"create " + props.appType + " preview"} 
+                sources={{
+                    light: '/img/guides/application/create-' + props.appType + '-app-light.png',
+                    dark: '/img/guides/application/create-' + props.appType + '-app-dark.png'
+                }}
+            />
+            <h3>Select the authentication method</h3>
+            <p>The authentication method defines the communication flow during a login</p>
+            <AuthType appType={props.appType} authType={props.authType}/>
+            <h3>Redirect URIs</h3>
+            <RedirectURIs appType={props.appType} redirectURI={props.redirectURI} postLogoutURI={props.postLogoutURI}/>
+            <h3>Review your configuration</h3>
+            <ReviewConfig appType={props.appType} authType={props.authType} />
+            <h3>Create key for private key JWT</h3>
+            <GenerateKey appType={props.appType} authType={props.authType} />
+        </div>
+    );
+}

docs/docs/guides/integrations/application/auth-type.mdx

@@ -0,0 +1,177 @@
+import ThemedImage from '@theme/ThemedImage';
+
+export default function AuthType(props) {
+    return (
+        <div>
+            {defaultAuthTypes(props.appType, props.authType)}
+        </div>
+    );
+}
+
+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 (
+        <table>
+            <tbody>
+                {rows.map((fn) => fn())}
+            </tbody>
+        </table>
+    );
+}
+
+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 [() => <tr key="native">
+        <td>
+            Native only supports code authentication type, that's why you don't have to select any
+        </td>
+    </tr>]
+}
+
+export const pkce = () => <tr key="pkce">
+        <td>
+            <ThemedImage
+            alt="pkce preview"
+            sources={{
+                light: '/img/guides/application/pkce-logo-light.png',
+                dark: '/img/guides/application/pkce-logo-dark.png'
+            }}
+            />
+        </td>
+        <td>
+            <h4>PKCE</h4>
+            <p>Recommended because it's the most secure.</p>
+        </td>
+    </tr>
+
+export const code = () => <tr key="code">
+      <td>
+        <ThemedImage
+          alt="code preview"
+          sources={{
+            light: '/img/guides/application/code-logo-light.png',
+            dark: '/img/guides/application/code-logo-dark.png'
+          }}
+        />
+      </td>
+      <td>
+        <h4>Code</h4>
+        <p>Use if your application needs client id and client secret</p>
+      </td>
+    </tr>
+
+export const jwt = () => <tr key="jwt">
+      <td>
+        <ThemedImage
+          alt="jwt preview"
+          sources={{
+            light: '/img/guides/application/jwt-logo-light.png',
+            dark: '/img/guides/application/jwt-logo-dark.png'
+          }}
+        />
+      </td>
+      <td>
+        <h4>(Private Key) JWT</h4>
+        <p>Key file to authorize your application. You can create keys after created the application see <a href="#create-key-for-private-key-jwt">below</a></p>
+      </td>
+    </tr>
+
+export const post = () => <tr key="post">
+      <td>
+        <ThemedImage
+          alt="post preview"
+          sources={{
+            light: '/img/guides/application/post-logo-light.png',
+            dark: '/img/guides/application/post-logo-dark.png'
+          }}
+        />
+      </td>
+      <td>
+        <h4>Post</h4>
+        <p>Only use if you have no other possibilities. Client id and client secret in request body</p>
+      </td>
+    </tr>
+
+export const implicit = () => <tr key="implicit">
+      <td>
+        <ThemedImage
+          alt="implicit preview"
+          sources={{
+            light: '/img/guides/application/implicit-logo-light.png',
+            dark: '/img/guides/application/implicit-logo-dark.png'
+          }}
+        />
+      </td>
+      <td>
+        <h4>Implicit</h4>
+        <p>Only use if you have no other possibilities. The flow is objective to be removed.</p>
+      </td>
+    </tr>
+
+export const basic = () => <tr key="basic">
+      <td>
+        <ThemedImage
+          alt="basic preview"
+          sources={{
+            light: '/img/guides/application/basic-logo-light.png',
+            dark: '/img/guides/application/basic-logo-dark.png'
+          }}
+        />
+      </td>
+      <td>
+        <h4>Basic</h4>
+        <p>The application sends username and password</p>
+      </td>
+    </tr>

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') ? (
+        <div>
+            <p>
+                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:
+            </p>
+            <ThemedImage
+                alt="Generate key preview"
+                sources={{
+                    light: '/img/guides/application/generate-key-light.gif',
+                    dark: '/img/guides/application/generate-key-dark.gif'
+                }}
+            />
+        </div>
+    ) : null;
+}

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) ? (
+        <div>
+            <p>
+                During the login flow the application defines where a user is redirected to after login or logout.
+                <br/>
+                ZITADEL verifies if the URL the user gets redirected to is valid by checking if one of the redirect URIs match.
+            </p>
+            <ul>
+                <li><b>Redirect URIs</b> are verified during the login process.</li>
+                {
+                    props.redirectURI ?
+                        <ul><li>The default redirect uri of your app is <code>{props.redirectURI}</code></li></ul>
+                        : null
+                }
+                <li><b>Post Logout URIs</b> are verified during the logout process.</li>
+                {
+                    props.postLogoutURI ?
+                        <ul><li>The default post logout uri of your app is <code>{props.postLogoutURI}</code></li></ul>
+                        : null
+                }
+            </ul>
+            <Admonition type="note">
+                <p>The default redirect uri of your app is <code>{props.redirectURI}</code></p>
+            </Admonition>
+            <ThemedImage
+                alt="Redirect URIs configuration"
+                sources={{
+                    light: '/img/guides/application/redirect-uris-light.png',
+                    dark: '/img/guides/application/redirect-uris-dark.png'
+                }}
+            />
+        </div>
+    ) : null;
+}

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 ? (
+        <div>
+            <p>This page shows what will be created. After you have reviewed the configuration you can create the application.</p>
+            <h3>Client information</h3>
+            <p>Please make sure to safe the <b>client {clientObjects.join(' and ')}</b> for later user in the application.</p>
+            <ThemedImage
+                alt="client infos"
+                sources={{
+                    light: '/img/guides/application/client-' + clientObjects.join('-') + '-light.png',
+                    dark: '/img/guides/application/client-' + clientObjects.join('-') + '-dark.png'
+                }}
+            />
+        </div>
+    ): 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)
+}

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"  
+  ![Create new connection](/img/oidc/auth0/auth0-create-app.png)
+2. Set a connection name for example "ZITADEL"
+3. The issuer url is `https://<YOUR_DOMAIN>/.well-known/openid-configuration`
+4. Copy the callback URL (ending with `/login/callback`)
+
+The configuration should look like this:
+
+![initial connection configuration](/img/oidc/auth0/auth0-init-app.png)
+
+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";
+
+<CreateApp appType="web" authType="code" appName="Auth0" redirectURI="https://<TENANT>.<REGION>.auth0.com/login/callback"/>
+
+## **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
+   ![full configuration](/img/oidc/auth0/auth0-full.png)
+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"
+   ![click try](/img/oidc/auth0/auth0-try.png)
+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:
+   ![full configuration](/img/oidc/auth0/auth0-works.png)

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";
+
+<CreateApp appType="web" authType="code" appName="Gitlab" redirectURI="https://<your_gitlab_url>/users/auth/openid_connect/callback"/>
+
+## 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://<YOUR_DOMAIN>/ui/console/assets/icons/favicon-32x32.png",
+    args: {
+      name: "openid_connect",
+      scope: ["openid","profile","email"],
+      response_type: "code",
+      issuer: "https://<YOUR_DOMAIN>",
+      discovery: true,
+      client_options: {
+        identifier: "<CLIENT ID from ZITADEL>",
+        secret: "<CLIENT SECRET from ZITADEL>",
+        redirect_uri: "https://<YOUR_GITLAB_URL>/users/auth/openid_connect/callback"
+      }
+    }
+  }
+]
+```

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",
       ],
     },
     {