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'; + + + + + + + + + + + + + + + + +
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 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" + ![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 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