docs: console guide (#4468)

* console guide

* org

* orgs, projects

* applications

* project, roles, authz

* users, roles

* app config, imgs

* policy imgs

* users, metadata, imgs

* actions, projects, structure

* css

* rm overview component

* rm manager from sidebar

* fix some broken links, update 🦖

* fix broken links

* fix img shadow

* Update docs/docs/concepts/structure/applications.md

Co-authored-by: Fabi <[email protected]>

* policy link

* link to projects guide

* Update docs/docs/guides/integrate/application/review-config.mdx

Co-authored-by: Fabi <[email protected]>

* add external org authz guide

* Update docs/docs/guides/manage/console/users.mdx

Co-authored-by: Fabi <[email protected]>

* link to example

* readd manager structure

* punto

* docs: domain settings email as username

* docs: links

* project, application settings, screenshots

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <[email protected]>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <[email protected]>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <[email protected]>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <[email protected]>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <[email protected]>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <[email protected]>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <[email protected]>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <[email protected]>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <[email protected]>

* Update docs/docs/guides/manage/console/organizations.mdx

Co-authored-by: Fabi <[email protected]>

* iam role

* Update docs/docs/guides/manage/console/managers.mdx

Co-authored-by: Fabi <[email protected]>

* Update docs/docs/guides/manage/console/managers.mdx

Co-authored-by: Fabi <[email protected]>

* change username text

* Update docs/docs/guides/manage/console/roles.mdx

Co-authored-by: Fabi <[email protected]>

* link example

* branding changes

* Update docs/docs/guides/manage/console/organizations.mdx

good point 👍

Co-authored-by: Fabi <[email protected]>

* docs: loginnames

Co-authored-by: Fabi <[email protected]>
Co-authored-by: Fabienne <[email protected]>
This commit is contained in:
Max Peintner
2022-10-06 16:22:46 +02:00
committed by GitHub
co-authored by Fabi Fabienne
parent c9870113f5
commit a4bbc756d8
138 changed files with 1296 additions and 779 deletions
+118 -30
View File
@@ -2,73 +2,161 @@
title: Applications
---
import ThemedImage from '@theme/ThemedImage';
import ThemedImage from "@theme/ThemedImage";
import AuthType from '../../integrate/application/auth-type.mdx';
import RedirectURIs from '../../integrate/application/redirect-uris.mdx';
import GenerateKey from '../../integrate/application/generate-key.mdx';
import ReviewConfig from '../../integrate/application/review-config.mdx';
import AuthType from "../../integrate/application/auth-type.mdx";
import RedirectURIs from "../../integrate/application/redirect-uris.mdx";
import GenerateKey from "../../integrate/application/generate-key.mdx";
import ReviewConfig from "../../integrate/application/review-config.mdx";
## What is an application?
# 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.
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 APIs.
All applications share the roles and authorizations of their project.
To access your applications, navigate to your project and select your application.
<img
alt="Granted project"
src="/img/guides/console/applications.png"
width="750px"
/>
<!-- TODO: oidc vs saml --->
## Application types
## Create application
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?
To add an application to your project, click on the add button and select your application type.
Detailed information about authentication types can be found [here](../../integrate/login-users#create-application).
<ThemedImage
alt="Redirect URIs configuration"
sources={{
light: '/img/guides/app-types-light.png',
dark: '/img/guides/app-types-dark.png'
}}
<img
alt="Add application"
src="/img/guides/console/addapplication.png"
width="120px"
/>
## Application Types
At the moment ZITADEL offers four client types:
- [**Web**](#web) (Server-side web applications such as java, .net, ...)
- [**Native**](#native) (native, mobile or desktop applications)
- [**User Agent**](#user-agent) (single page applications / SPA, generally JavaScript executed in the browser)
- [**API**](#api) (OAuth Resource Server)
The first three options (Web, Native and User Agent) require user interaction, the fourth option (API) has no direct user-interaction.
Depending on the app type, there are small differences in the possible settings.
To get a good understanding about user profiles and recommended flows, read the following [guide](../../integrate/oauth-recommended-flows.md#different-client-profiles).
### 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.
Web applications are **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.
Typical **React or Angular** apps **are not** a Web applications in this case.
A **NextJS** on the contrary would be because it allows you to implement server side code.
Following authentication types can be used:
<AuthType appType="web"/>
<AuthType appType="web" />
### Native
Applications installed on a thin client. For example on a smartphone or computer.
Native Applications installed on a thin client. For example on a smartphone or computer. This can for example be Android and iOS Applications.
These applications uses the Key file generated by ZITADEL to authenticate.
<AuthType appType="native"/>
<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](../../../examples/login/angular) or [React](../../../examples/login/react)
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](../../../examples/login/angular) or [React](../../../examples/login/react)
Following authentication types can be used:
Following **authentication methods** can be used:
<AuthType appType="user-agent"/>
<AuthType appType="user-agent" />
### API
Applications without human interaction. These applications are accessed by other applications, so called machine to machine communication.
These are 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"/>
<AuthType appType="api" />
After selecting your Apps Type and Authentication Method, you may need to specify redirect URIs.
## Redirect URIs
<RedirectURIs appType="web"/>
App Types with User interaction (Web, Native and User Agent) require redirect URIs.
Those redirects URIs are used to redirect the user back to your application on successful login.
These URIs are defined in your application code and are checked by ZITADEL if they correspond to your applications configuration.
Redirect URIs are checked during the login process.
Native applications can use a different protocol than http or https in order to redirect your user.
<img
alt="Redirect URIs"
src="/img/guides/console/redirecturis.png"
width="600px"
/>
In order to **develop locally** and due to the fact that any ZITADEL configuration is secure by default, ZITADEL requires you enable **dev mode** if you want to redirect users to URIs other than https://.
## Review Configuration
<ReviewConfig authType="code"/>
<ReviewConfig authType="code" />
## Generate key for private key JWT
## Application settings
<GenerateKey appType="api"/>
After creating the application, you can still change its configuration if you for example need a offline_access support (Refresh token).
You can easily change your authentication method via the colored toggle on top or directly change configuration via the input and dropdown fields.
> Note: Changing application type is not possible. In this case you have to create a new application.
<img
alt="Redirect URIs"
src="/img/guides/console/application.png"
width="800px"
/>
On the top of the page you can check if your application is OIDC compliant.
Tasks for completion are shown in the field.
<img
alt="OIDC Compliance"
src="/img/guides/console/oidc-compliance.png"
width="600px"
/>
### Token settings
In the token settings you can change the type from **Bearer Token** to **JWT**, and check some settings whether you need user roles and user information in the ID Token or not.
On the bottom you can optionally set a **ClockSkew** time which is added to the expiration time of the issued token.
<img
alt="Token settings"
src="/img/guides/console/app-token-settings.png"
width="600px"
/>
### Redirect settings
Like on creation, you can modify you redirect settings here.
Note that for local development you most likely have to enable development mode, as redirects to http:// are otherwise blocked.
<img
alt="Redirect URIs"
src="/img/guides/console/redirect-uris.png"
width="500px"
/>
### Additional origins
If you need to allow additional origins which should **NOT** be used as redirect you can specify them in the **Additional origins** section.
<img
alt="Additional origins"
src="/img/guides/console/additional-origins.png"
width="500px"
/>