diff --git a/site/docs/administrate/00-overview.en.md b/site/docs/administrate/00-overview.en.md index b8ac15bdf..74963982d 100644 --- a/site/docs/administrate/00-overview.en.md +++ b/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 diff --git a/site/docs/administrate/09-authorizations.de.md b/site/docs/administrate/09-authorizations.de.md new file mode 100644 index 000000000..42e58c92a --- /dev/null +++ b/site/docs/administrate/09-authorizations.de.md @@ -0,0 +1,5 @@ +--- +title: Authorizations +--- + +> This Language is not yet translated. Please consult the English version. diff --git a/site/docs/administrate/09-authorizations.en.md b/site/docs/administrate/09-authorizations.en.md new file mode 100644 index 000000000..9e4a26cf5 --- /dev/null +++ b/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 diff --git a/site/docs/documentation/00-introduction.de.md b/site/docs/documentation/00-introduction.de.md deleted file mode 100644 index 8a27b82a8..000000000 --- a/site/docs/documentation/00-introduction.de.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: Einführung ---- diff --git a/site/docs/documentation/00-introduction.en.md b/site/docs/documentation/00-introduction.en.md deleted file mode 100644 index c4ba3d591..000000000 --- a/site/docs/documentation/00-introduction.en.md +++ /dev/null @@ -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. diff --git a/site/docs/documentation/00-overview.de.md b/site/docs/documentation/00-overview.de.md new file mode 100644 index 000000000..6d9be1de6 --- /dev/null +++ b/site/docs/documentation/00-overview.de.md @@ -0,0 +1,5 @@ +--- +title: Übersicht +--- + +> This Language is not yet translated. Please consult the English version. \ No newline at end of file diff --git a/site/docs/documentation/00-overview.en.md b/site/docs/documentation/00-overview.en.md new file mode 100644 index 000000000..aab91c5df --- /dev/null +++ b/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. diff --git a/site/docs/integrate/00-overview.en.md b/site/docs/integrate/00-overview.en.md index 89dad2c4c..6dcc0a212 100644 --- a/site/docs/integrate/00-overview.en.md +++ b/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). diff --git a/site/docs/integrate/01-openidoauth.en.md b/site/docs/integrate/01-openidoauth.en.md deleted file mode 100644 index 48b251762..000000000 --- a/site/docs/integrate/01-openidoauth.en.md +++ /dev/null @@ -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). diff --git a/site/docs/integrate/01-singlepageapp.de.md b/site/docs/integrate/01-singlepageapp.de.md new file mode 100644 index 000000000..5766daed2 --- /dev/null +++ b/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. diff --git a/site/docs/integrate/01-singlepageapp.en.md b/site/docs/integrate/01-singlepageapp.en.md new file mode 100644 index 000000000..3df0882f9 --- /dev/null +++ b/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 { + return this.userManager.getUser(); + } + + public login(): Promise { + return this.userManager.signinRedirect(); + } + + public logout(): Promise { + return this.userManager.signoutRedirect(); + } + + public getAccessToken(): Promise { + return this.userManager.getUser().then((data: any) => { + return data.access_token; + }); + } +} +``` diff --git a/site/docs/integrate/02-serverapp.de.md b/site/docs/integrate/02-serverapp.de.md new file mode 100644 index 000000000..7fa851534 --- /dev/null +++ b/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. diff --git a/site/docs/integrate/02-serverapp.en.md b/site/docs/integrate/02-serverapp.en.md new file mode 100644 index 000000000..77e4e1ab7 --- /dev/null +++ b/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 diff --git a/site/docs/integrate/01-openidoauth.de.md b/site/docs/integrate/03-mobileapp.de.md similarity index 77% rename from site/docs/integrate/01-openidoauth.de.md rename to site/docs/integrate/03-mobileapp.de.md index 6f9f11f3a..085e060c0 100644 --- a/site/docs/integrate/01-openidoauth.de.md +++ b/site/docs/integrate/03-mobileapp.de.md @@ -1,5 +1,5 @@ --- -title: OpenID Connect & OAuth +title: Mobile Application description: ... --- diff --git a/site/docs/integrate/03-mobileapp.en.md b/site/docs/integrate/03-mobileapp.en.md new file mode 100644 index 000000000..cdd82f4c2 --- /dev/null +++ b/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 diff --git a/site/docs/integrate/04-nativeapp.de.md b/site/docs/integrate/04-nativeapp.de.md new file mode 100644 index 000000000..a96998467 --- /dev/null +++ b/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. diff --git a/site/docs/integrate/04-nativeapp.en.md b/site/docs/integrate/04-nativeapp.en.md new file mode 100644 index 000000000..8964f71bc --- /dev/null +++ b/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 diff --git a/site/docs/integrate/05-proxy.de.md b/site/docs/integrate/05-proxy.de.md new file mode 100644 index 000000000..5a605d796 --- /dev/null +++ b/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. diff --git a/site/docs/integrate/05-proxy.en.md b/site/docs/integrate/05-proxy.en.md new file mode 100644 index 000000000..727825c40 --- /dev/null +++ b/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 diff --git a/site/docs/integrate/06-api.de.md b/site/docs/integrate/06-api.de.md new file mode 100644 index 000000000..a4961d6a2 --- /dev/null +++ b/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. diff --git a/site/docs/integrate/06-api.en.md b/site/docs/integrate/06-api.en.md new file mode 100644 index 000000000..7125ece03 --- /dev/null +++ b/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 diff --git a/site/docs/integrate/07-products.de.md b/site/docs/integrate/07-products.de.md new file mode 100644 index 000000000..9eaf2a981 --- /dev/null +++ b/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. diff --git a/site/docs/integrate/07-products.en.md b/site/docs/integrate/07-products.en.md new file mode 100644 index 000000000..b0de8ba6c --- /dev/null +++ b/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 + +
+
+ + Client Settings for Grafana + +
Client Settings for Grafana
+
+
+ +#### 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' +... +``` + +
+
+ + Project Settings for Grafana + +
Project Settings for Grafana
+
+
+ + Authorization for Grafana Role in ZITADEL + +
Authorization for Grafana Role in ZITADEL
+
+
+ + Grafana Login + +
Grafana Login
+
+
+ + Grafana with Editor Role mapped from ZITADEL + +
Grafana with Editor Role mapped from ZITADEL
+
+
+ +> 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 diff --git a/site/static/img/grafana_client_settings.png b/site/static/img/grafana_client_settings.png new file mode 100644 index 000000000..b9de9a8e2 Binary files /dev/null and b/site/static/img/grafana_client_settings.png differ diff --git a/site/static/img/grafana_login_button.png b/site/static/img/grafana_login_button.png new file mode 100644 index 000000000..1cec6e2ef Binary files /dev/null and b/site/static/img/grafana_login_button.png differ diff --git a/site/static/img/grafana_profile_settings.png b/site/static/img/grafana_profile_settings.png new file mode 100644 index 000000000..6abaa028b Binary files /dev/null and b/site/static/img/grafana_profile_settings.png differ diff --git a/site/static/img/grafana_project_settings.png b/site/static/img/grafana_project_settings.png new file mode 100644 index 000000000..f3fd6b181 Binary files /dev/null and b/site/static/img/grafana_project_settings.png differ diff --git a/site/static/img/grafana_zitadel_authorization.png b/site/static/img/grafana_zitadel_authorization.png new file mode 100644 index 000000000..27bd669cf Binary files /dev/null and b/site/static/img/grafana_zitadel_authorization.png differ