docs(intergration): examples (#939)

* rename to overview

* wip

* wip

* wip

* wip

* wip

* wip

* examples

* ts example

* wip with grafana

* add grafana tutorial

* screenshots and grafana

* figure out oauth proxy

* authz oauth proxy

* move img

* merge from master

* Apply suggestions from code review

Co-authored-by: Florian Forster <florian@caos.ch>

Co-authored-by: mffap <max@mffap.org>

site/docs/administrate/00-overview.en.md

@@ -17,11 +17,11 @@ title: Overview
   - Mobile Clients
     - Android
     - iOS / iPadOS
-- Bearer Tokens to use with APIs
+- Bearer Tokens (JWT and opaque) to use with APIs
   - REST
   - GRPC
   - GraphQL
-- Role Based Access Control
+- Role Based Access Control (RBAC) with delegation to let organisations manage authorisations on their own
 - OpenID Connect 1.0 (OIDC) support
 - OAuth 2.0 support
 - Identity Brokering
@@ -30,6 +30,9 @@ title: Overview
 - Management Console for central management of your data
 - Multi-factor Authentication
   - Support for TOTP/HOTP with any app, like authy, google authenticator, ...
+  - U2F (CTAP1)
+- Passwordless Authentication
+  - WebAuthN (FIDO2 / CTAP2)
 - User self-registration, recover password, email and phone verification, etc.
 - Organisation self-registration, domain verification, policy management
 - API's for easy integration in your application

site/docs/administrate/09-authorizations.de.md

@@ -0,0 +1,5 @@
+---
+title: Authorizations
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/09-authorizations.en.md

@@ -0,0 +1,50 @@
+---
+title: Authorizations
+---
+
+### ZITADEL's management Roles
+
+ZITADEL's own role model is built around the IAM resource. The roles have some hierarchies to them. For example a IAM_OWNER can view and edit every resource of the system. ORG_OWNERS can only manage their resources included within their organisation. This includes projects, clients, users, and so on.
+
+#### How to give a user ZITADEL Roles
+
+
+> Screenshots
+
+#### System Roles
+
+IAM_OWNER
+
+IAM_OWNER_VIEWER
+
+#### Organisation Roles
+
+ORG_OWNER
+
+ORG_OWNER_VIEWER
+
+ORG_USER_PERMISSION_EDITOR
+
+ORG_PROJECT_PERMISSION_EDITOR
+
+ORG_PROJECT_CREATOR
+
+#### Owned Project Roles
+
+PROJECT_OWNER
+
+PROJECT_OWNER_VIEWER
+
+PROJECT_OWNER_GLOBAL
+
+PROJECT_OWNER_VIEWER_GLOBAL
+
+#### Granted Project Roles
+
+PROJECT_GRANT_OWNER
+
+PROJECT_GRANT_OWNER_VIEWER
+
+### Project Roles Management
+
+> Explain Project Authorization

site/docs/documentation/00-introduction.de.md

@@ -1,3 +0,0 @@
----
-title: Einführung
----

site/docs/documentation/00-introduction.en.md

@@ -1,13 +0,0 @@
----
-title: Introduction
-description: This is the place for all things ZITADEL. Whether you are a developer, an integrator or a user of ZITADEL, then the following pages are written for your referral.
----
-
-> All documentations are under active work and subject to change soon!
-
-The documentation for ZITADEL comprises two major subject areas:
-
-1. Manuals for users, support organisations and administrators.
-2. Technical resources for developers and integrators.
-
-Please be reminded that ZITADEL is open source — and so is the documentation. Should you happen to stumble over an incorrectness, a spelling mistake, a hard-to-understand text passage, please don’t hesitate to leave a comment or propose a corresponding change.

site/docs/documentation/00-overview.de.md

@@ -0,0 +1,5 @@
+---
+title: Übersicht
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/documentation/00-overview.en.md

@@ -0,0 +1,13 @@
+---
+title: Overview
+---
+
+> All documentations are under active work and subject to change soon!
+
+This part of the **ZITADEL** documentation comprises three major subject areas:
+
+1. Principles
+2. Architecture
+3. Protocols
+
+Please be reminded that ZITADEL is open source — and so is the documentation. Should you happen to stumble over an incorrectness, a spelling mistake, a hard-to-understand text passage, please don’t hesitate to leave a comment or propose a corresponding change.

site/docs/integrate/00-overview.en.md

@@ -5,6 +5,12 @@ description: ...
 
 > All documentations are under active work and subject to change soon!
 
-### Application Integration
+This Integration guide gives you recommendations on how to integrate different Clients with **ZITADEL**
 
-### Service Integration
+- Single Page Application
+- Server Side Application
+- Mobile App
+- Native App
+- Reverse Proxy
+
+For more details about how **ZITADEL** treats [scopes](documentation#Scopes) and [claims](documentation#Claims) see the [documentations](documentation).

site/docs/integrate/01-openidoauth.en.md

@@ -1,46 +0,0 @@
----
-title:  OpenID Connect & OAuth
-description: ...
----
-
-### Client Types / Profiles
-
-#### Single Page Application
-
-If your [client](administrate#Clients) is a single page application (SPA) we recommend that you use [Authorization Code](documentation#Authorization_Code) in combination with [Proof Key for Code Exchange](documentation#Proof_Key_for_Code_Exchange).
-
-This flow has great support with most modern languages and frameworks and is the recommended default.
-
-> In the OIDC and OAuth world this **client profile** is called "user-agent-based application"
-
-#### Server Side Application
-
-In the OIDC and OAuth world this client profile is called "web application"
-
-#### Mobile App / Native App
-
-In the OIDC and OAuth world this client profile is called "native application"
-
-### How to consume authorizations in your application or service
-
----
-
-With ZITADEL you can manage the [roles](administrate#Roles) a [project](administrate#Projects) supplies to your users in the form of authorizations.
-On the [project](administrate#Projects) it can be configured how **project roles** are supplied to the [clients](administrate#Clients).
-By default ZITADEL asserts the claim **urn:zitadel:iam:org:project:roles** to the [Userinfo Endpoint](documentation#userinfo_endpoint)
-
-- Assert the claim **urn:zitadel:iam:org:project:roles** to **access_token**
-- Assert the claim **urn:zitadel:iam:org:project:roles** to **id_token**
-
-```JSON
- "urn:zitadel:iam:org:project:roles": {
-    "user": {
-      "id1": "acme.zitadel.ch",
-      "id2": "caos.ch",
-    }
-  }
-```
-
----
-
-For more details about how **ZITADEL** treats [scopes](documentation#Scopes) and [claims](documentation#Claims) see the [documentations](documentation).

site/docs/integrate/01-singlepageapp.de.md

@@ -0,0 +1,6 @@
+---
+title: Single Page Application
+description: ...
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/integrate/01-singlepageapp.en.md

@@ -0,0 +1,62 @@
+---
+title:  Single Page Application
+description: ...
+---
+
+### SPA Protocol and Flow recommendation
+
+If your [client](administrate#Clients) is a single page application (SPA) we recommend that you use [Authorization Code](documentation#Authorization_Code) in combination with [Proof Key for Code Exchange](documentation#Proof_Key_for_Code_Exchange).
+
+This flow has great support with most modern languages and frameworks and is the recommended default.
+
+> In the OIDC and OAuth world this **client profile** is called "user-agent-based application"
+
+### Typescript Example
+
+#### Typescript Authentication Example
+
+If you use a framework like Angular, Vue, React, ... you can use this code snippet here to integrate **ZITADEL** into you application
+
+Library used for this example [https://github.com/IdentityModel/oidc-client-js](https://github.com/IdentityModel/oidc-client-js)
+
+```ts
+import { UserManager, WebStorageStateStore, User } from 'oidc-client';
+
+export default class AuthService {
+    private userManager: UserManager;
+
+    constructor() {
+        const ZITADEL_ISSUER_DOMAIN: string = "https://issuer.zitadel.ch";
+
+        const settings: any = {
+            userStore: new WebStorageStateStore({ store: window.localStorage }),
+            authority: ZITADEL_ISSUER_DOMAIN,
+            client_id: 'YOUR_ZITADEL_CLIENT_ID',
+            redirect_uri: 'http://localhost:44444/callback.html',
+            response_type: 'code',
+            scope: 'openid profile',
+            post_logout_redirect_uri: 'http://localhost:44444/',
+        };
+
+        this.userManager = new UserManager(settings);
+    }
+
+    public getUser(): Promise<User | null> {
+        return this.userManager.getUser();
+    }
+
+    public login(): Promise<void> {
+        return this.userManager.signinRedirect();
+    }
+
+    public logout(): Promise<void> {
+        return this.userManager.signoutRedirect();
+    }
+
+    public getAccessToken(): Promise<string> {
+        return this.userManager.getUser().then((data: any) => {
+            return data.access_token;
+        });
+    }
+}
+```

site/docs/integrate/02-serverapp.de.md

@@ -0,0 +1,6 @@
+---
+title:  Server Side Application
+description: ...
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/integrate/02-serverapp.en.md

@@ -0,0 +1,10 @@
+---
+title:  Server Side Application
+description: ...
+---
+
+### SSA Protocol and Flow recommendation
+
+### ASP.net core example
+
+> Link here

site/docs/integrate/03-mobileapp.de.md

@@ -1,5 +1,5 @@
 ---
-title: OpenID Connect & OAuth
+title:  Mobile Application
 description: ...
 ---
 

site/docs/integrate/03-mobileapp.en.md

@@ -0,0 +1,14 @@
+---
+title:  Mobile Application
+description: ...
+---
+
+### Mobile App Protocol and Flow recommendation
+
+### Swift Example
+
+> Link here
+
+### Java Example
+
+> Link here

site/docs/integrate/04-nativeapp.de.md

@@ -0,0 +1,6 @@
+---
+title:  Native Application
+description: ...
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/integrate/04-nativeapp.en.md

@@ -0,0 +1,14 @@
+---
+title:  Native Application
+description: ...
+---
+
+### Native App Protocol and Flow recommendation
+
+### Electron Example
+
+> Link here
+
+### c# Example
+
+> Link here

site/docs/integrate/05-proxy.de.md

@@ -0,0 +1,6 @@
+---
+title:  Proxy / WAF
+description: ...
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/integrate/05-proxy.en.md

@@ -0,0 +1,127 @@
+---
+title:  Proxy / WAF
+description: ...
+---
+
+### Proxy Protocol and Flow recommendation
+
+### Ambassador Example
+
+According to [https://www.getambassador.io/docs/latest/](https://www.getambassador.io/docs/latest/) Ambassador is a:
+
+>The Ambassador Edge Stack is a comprehensive, self-service edge stack and API Gateway for Kubernetes built on Envoy Proxy. The shift to Kubernetes and microservices has profound consequences for the capabilities you need at the edge, as well as how you manage the edge. The Ambassador Edge Stack has been engineered with this world in mind.
+
+You can use **ZITADEL** for Authentication and Authorization with **Ambassador**.
+
+> The redirect URI is `https://{AMBASSADOR_URL}/.ambassador/oauth2/redirection-endpoint`
+
+#### Use Ambassador to Authenticate with ZITADEL
+
+With this you can use Ambassador to initiate the Authorization Code Flow.
+
+```yaml
+apiVersion: getambassador.io/v2
+kind: Filter
+metadata:
+  name: zitadel-filter
+  namespace: default
+spec:
+  OAuth2:
+    authorizationURL: https://accounts.zitadel.ch/oauth/v2/authorize
+    clientID: {ZITADEL_GENERATED_CLIENT_ID}
+    secret: {ZITADEL_GENERATED_CLIENT_SECRET}
+    protectedOrigins:
+    - origin: https://{PROTECTED_URL}
+```
+
+```yaml
+apiVersion: getambassador.io/v2
+kind: FilterPolicy
+metadata:
+  name: zitadel-policy
+  namespace: default
+spec:
+  rules:
+    - host: "*"
+      path: /backend/get-quote/
+      filters:
+        - name: zitadel-filter
+```
+
+#### Use Ambassador to check JWT Bearer Tokens
+
+If you would like **Ambassador** to verify a JWT token from the authorization header you can do so by configuring **ZITADEL's** endpoints.
+
+> Make sure that in your client settings of **ZITADEL** the "AuthToken Options" is **JWT** by default **ZITADEL** will use opaque tokens!
+
+```yaml
+apiVersion: getambassador.io/v2
+kind: Filter
+metadata:
+  name: zitadel-filter
+  namespace: default
+spec:
+  JWT:
+    jwksURI:            "https://api.zitadel.ch/oauth/v2/keys"
+    validAlgorithms:
+    - "RS256"
+    issuer:             "https://issuer.zitadel.ch"
+    requireIssuer:      true
+```
+
+```yaml
+apiVersion: getambassador.io/v2
+kind: FilterPolicy
+metadata:
+  name: zitadel-policy
+  namespace: default
+spec:
+  rules:
+    - host: "*"
+      path: /backend/get-quote/
+      filters:
+        - name: zitadel-filter
+```
+
+> Additional Infos can be found with [Ambassadors Documentation](https://www.getambassador.io/docs/latest/howtos/oauth-oidc-auth/)
+
+### OAuth2 Proxy Example
+
+[OAuth2-proxy](https://github.com/oauth2-proxy/oauth2-proxy) is a project which allows services to delegate the authentication flow to a IDP, for example **ZITADEL**
+
+#### OAuth2 Proxy Authentication Example
+
+```toml
+provider = "oidc"
+user_id_claim = "sub" #uses the subject as ID instead of the email
+provider_display_name "ZITADEL"
+redirect_url = "http://127.0.0.1:4180/oauth2/callback"
+oidc_issuer_url = "https://issuer.zitadel.ch"
+upstreams = [
+    "https://example.corp.com"
+]
+email_domains = [
+    "*"
+]
+client_id = "{ZITADEL_GENERATED_CLIENT_ID}"
+client_secret = "{ZITADEL_GENERATED_CLIENT_SECRET}"
+pass_access_token = true
+cookie_secret = "{SUPPLY_SOME_SECRET_HERE}"
+skip_provider_button = true
+cookie_secure = false #localdev only false
+http_address = "127.0.0.1:4180" #localdev only
+```
+
+> This was tested with version `oauth2-proxy v6.1.1 (built with go1.14.2)`
+
+#### OAuth2 Proxy Authorization Example
+
+> Not yet supported but with the work of [https://github.com/oauth2-proxy/oauth2-proxy/pull/797](https://github.com/oauth2-proxy/oauth2-proxy/pull/797) it should be possible in the future
+
+### Cloudflare Access Example
+
+> TODO
+
+### NGINX Example
+
+> TODO

site/docs/integrate/06-api.de.md

@@ -0,0 +1,6 @@
+---
+title:  API
+description: ...
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/integrate/06-api.en.md

@@ -0,0 +1,12 @@
+---
+title:  API
+description: ...
+---
+
+### API Protocol and Flow recommendation
+
+### Go Example
+
+### .net core Example
+
+### node.js Example

site/docs/integrate/07-products.de.md

@@ -0,0 +1,6 @@
+---
+title:  Products
+description: ...
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/integrate/07-products.en.md

@@ -0,0 +1,100 @@
+---
+title:  Products
+description: ...
+---
+
+### Grafana Example
+
+**Grafana** defines itself as "The open-source platform for monitoring and observability."
+
+The source code is provided on [Grafana's Github Repository](https://github.com/grafana/grafana)
+
+#### Authenticate Grafana with ZITADEL
+
+To authenticate **Grafana** with ZITADEL you can use the provided **Generic OAuth** plugin.
+
+> We do not recommend that you rely on `allowed_domain` as means of authorizing subjects, but instead use **ZITADEL's** RBAC Assertion
+
+1. Create a new project or use an existing one
+2. Add OpenID Connect / OAuth 2.0 client to the project (See screenshot for settings)
+3. Add config to your **Grafana** instance and restart it
+4. Login to **Grafana**
+
+```ini
+[auth.generic_oauth]
+enabled = true
+name= ZITADEL
+client_id = {ZITADEL_GENERATED_CLIENT_ID}
+client_secret = {ZITADEL_GENERATED_CLIENT_SECRET}
+scopes = openid profile email
+auth_url = https://accounts.zitadel.ch/oauth/v2/authorize
+token_url = https://api.zitadel.ch/oauth/v2/token
+api_url = https://api.zitadel.ch/oauth/v2/userinfo
+allow_sign_up = true
+```
+
+> Grafanas's redirect is URI https://yourdomain.tld/login/generic_oauth
+
+<div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/grafana_client_settings.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/grafana_client_settings.png" itemprop="thumbnail" alt="Client Settings for Grafana" />
+        </a>
+        <figcaption itemprop="caption description">Client Settings for Grafana</figcaption>
+    </figure>
+</div>
+
+#### Authorizes Users with Roles in Grafana
+
+**ZITADEL** provides projects with the option to provide Grafana with the users role.
+
+1. Create Roles (Admin, Editor, Viewer) in **ZITADEL's** project which contains **Grafana**
+2. Enable "Assert Roles on Authentication" so that the roles are asserted to the userinfo endpoint
+3. (Optional) Enable "Check roles on Authentication", this will prevent that someone without any role to login **Grafana** via **ZITADEL**
+4. Append the config below to your **Grafana** instance and reload
+5. Authorize the necessary users
+
+```ini
+[auth.generic_oauth]
+...
+role_attribute_path =  keys("urn:zitadel:iam:org:project:roles") | contains(@, 'Admin') && 'Admin' || contains(@, 'Editor') && 'Editor' || 'Viewer'
+...
+```
+
+<div class="zitadel-gallery" itemscope itemtype="http://schema.org/ImageGallery">
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/grafana_project_settings.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/grafana_project_settings.png" itemprop="thumbnail" alt="Project Settings for Grafana" />
+        </a>
+        <figcaption itemprop="caption description">Project Settings for Grafana</figcaption>
+    </figure>
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/grafana_zitadel_authorization.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/grafana_zitadel_authorization.png" itemprop="thumbnail" alt="Authorization for Grafana Role in ZITADEL" />
+        </a>
+        <figcaption itemprop="caption description">Authorization for Grafana Role in ZITADEL</figcaption>
+    </figure>
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/grafana_login_button.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/grafana_login_button.png" itemprop="thumbnail" alt="Grafana Login" />
+        </a>
+        <figcaption itemprop="caption description">Grafana Login</figcaption>
+    </figure>
+    <figure itemprop="associatedMedia" itemscope itemtype="http://schema.org/ImageObject">
+        <a href="img/grafana_profile_settings.png" itemprop="contentUrl" data-size="1920x1080">
+            <img src="img/grafana_profile_settings.png" itemprop="thumbnail" alt="Grafana with Editor Role mapped from ZITADEL" />
+        </a>
+        <figcaption itemprop="caption description">Grafana with Editor Role mapped from ZITADEL</figcaption>
+    </figure>
+</div>
+
+> Grafana can not directly use ZITADEL delegation feature but normal RBAC works fine
+> Additional infos can be found in the [Grafana generic OAuth 2.0 documentation](https://grafana.com/docs/grafana/latest/auth/generic-oauth/)
+
+### ArgoCD Example
+
+> TODO
+
+### Kubernetes Example
+
+> TODO