diff --git a/docs/docs/guides/basics/applications.mdx b/docs/docs/guides/basics/applications.mdx new file mode 100644 index 000000000..3e5f21c06 --- /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'; + + + + + + + + + + + + + + + + +
DescriptionLearn 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 000000000..00cbbc75a --- /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 000000000..df038e97c --- /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 000000000..a2439f013 --- /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 000000000..fd19dcd76 --- /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 000000000..0e758ce68 --- /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 000000000..b96bb7d5b --- /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" + ![Create new connection](/img/oidc/auth0/auth0-create-app.png) +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: + +![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"; + + + +## **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) 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 000000000..2b058aed5 --- /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 6c71dd12d..59c4d4ba8 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 000000000..b4eeda010 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 000000000..b4eeda010 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 000000000..9cb70e041 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 000000000..758d400c9 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 000000000..d8cde0ba0 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 000000000..d1e875f9a 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 000000000..3918f2d3b 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 000000000..3e285d926 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 000000000..2912db2d6 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 000000000..02fb07c46 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 000000000..852d8c6ca 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 000000000..6514032d3 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 000000000..fa5ebffab 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 000000000..0d52b77c3 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 000000000..0244302ff 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 000000000..4c7950e01 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 000000000..4895ae36b 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 000000000..84f429cec 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 000000000..498e5ae37 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 000000000..30ac16eca 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 000000000..ce96546f5 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 000000000..5a51787d2 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 000000000..7f40f8d14 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 000000000..51c35ecea 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 000000000..db24e9b0f 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 000000000..a7ce82024 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 000000000..534143301 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 000000000..f4313fe1d 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 000000000..9dd266761 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 000000000..ecb597a01 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 000000000..5634864ef 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 000000000..21e76b30b 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 000000000..60e0d9224 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 000000000..e73da2cc7 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 000000000..499b94c7e 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 000000000..10bdfe3a3 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 000000000..940ff47dc 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 000000000..35b02e8c5 Binary files /dev/null and b/docs/static/img/oidc/auth0/auth0-works.png differ