mirror of
https://github.com/zitadel/zitadel.git
synced 2025-12-06 09:02:22 +00:00
feat: docs rehaul, fix missing context in console, quickstarts (#1212)
* onboarding components, routing, steps * onboarding component, toc * fix onboarding mixin * header * refactor docs * fix layout * cleanup routing * docs routing * fix conventions * de en routing * docs, guide contents, nav * rem i18n support * fix routing from docs * rollup onwarn changes, preload * update svelte plugin, update rollup config * move docs * revert img style, remove code table * rem de completely * rollup optim, template * angular quickstart, quickstart overview page, update deps * fix link * pack, slug * prefetch binding, hidden links * export log * guards route ch * fix homepage * angular docs * docs * resolve fsh * overview * docs * docs * packages fix race condition * nav, home link * add vue, aspnet * doc optimizations * embed status pal * angular guide * angular guide * dotnet, angular guide * viewbox * typo * block onboarding route for non iam writers * set links from component data * fix: fetch org context in guard, more main cnt (#1192) * change get started guide, fix code blockquotes, typos * flutter guide * h2 spacing * highlight strong * plus * rm start sublinks * add proxy quickstart * regex * prevent outside click, fix project grant write Co-authored-by: Florian Forster <florian@caos.ch> Co-authored-by: Livio Amstutz <livio.a@gmail.com>
This commit is contained in:
Max Peintner
16
site/docs/quickstarts/00-overview.md
Normal file
16
site/docs/quickstarts/00-overview.md
Normal file
@@ -0,0 +1,16 @@
|
||||
---
|
||||
title: Overview
|
||||
description: ...
|
||||
---
|
||||
|
||||
> All documentations are under active work and subject to change soon!
|
||||
|
||||
This Integration guide gives you recommendations on how to integrate different Clients with **ZITADEL**
|
||||
|
||||
- Single Page Application
|
||||
- Server Side Application
|
||||
- Mobile App
|
||||
- Native App
|
||||
- Reverse Proxy
|
||||
|
||||
For more details about how **ZITADEL** treats [scopes](architecture#Scopes) and [claims](architecture#Claims) see the [documentations](architecture).
|
||||
62
site/docs/quickstarts/01-singlepageapp.md
Normal file
62
site/docs/quickstarts/01-singlepageapp.md
Normal file
@@ -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](architecture#Authorization_Code) in combination with [Proof Key for Code Exchange](architecture#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;
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
10
site/docs/quickstarts/02-serverapp.md
Normal file
10
site/docs/quickstarts/02-serverapp.md
Normal file
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: Server Side Application
|
||||
description: ...
|
||||
---
|
||||
|
||||
### SSA Protocol and Flow recommendation
|
||||
|
||||
### ASP.net core example
|
||||
|
||||
> Link here
|
||||
14
site/docs/quickstarts/03-mobileapp.md
Normal file
14
site/docs/quickstarts/03-mobileapp.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Mobile Application
|
||||
description: ...
|
||||
---
|
||||
|
||||
### Mobile App Protocol and Flow recommendation
|
||||
|
||||
### Swift Example
|
||||
|
||||
> Link here
|
||||
|
||||
### Java Example
|
||||
|
||||
> Link here
|
||||
14
site/docs/quickstarts/04-nativeapp.md
Normal file
14
site/docs/quickstarts/04-nativeapp.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: Native Application
|
||||
description: ...
|
||||
---
|
||||
|
||||
### Native App Protocol and Flow recommendation
|
||||
|
||||
### Electron Example
|
||||
|
||||
> Link here
|
||||
|
||||
### c# Example
|
||||
|
||||
> Link here
|
||||
127
site/docs/quickstarts/05-proxy.md
Normal file
127
site/docs/quickstarts/05-proxy.md
Normal file
@@ -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
|
||||
12
site/docs/quickstarts/06-api.md
Normal file
12
site/docs/quickstarts/06-api.md
Normal file
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: API
|
||||
description: ...
|
||||
---
|
||||
|
||||
### API Protocol and Flow recommendation
|
||||
|
||||
### Go Example
|
||||
|
||||
### .net core Example
|
||||
|
||||
### node.js Example
|
||||
100
site/docs/quickstarts/07-products.md
Normal file
100
site/docs/quickstarts/07-products.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user