sendnrw/netbird-docs
2
0
Fork 0
mirror of https://github.com/netbirdio/docs.git synced 2026-04-15 23:16:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into feature/switch_to_tailwind

Browse Source 
# Conflicts:
#	docs/integrations/identity-providers/self-hosted/available-integrations.md
#	public/img/getting-started/zitadel-create-user.png
#	public/img/getting-started/zitadel-service-account-role.png
#	public/img/getting-started/zitadel-service-user-secret.png
#	public/img/integrations/identity-providers/self-hosted/zitadel-create-user.png
#	public/img/integrations/identity-providers/self-hosted/zitadel-new-application-auth.png
#	public/img/integrations/identity-providers/self-hosted/zitadel-new-application-overview.png
#	public/img/integrations/identity-providers/self-hosted/zitadel-new-application-uri.png
#	public/img/integrations/identity-providers/self-hosted/zitadel-new-application.png
#	public/img/integrations/identity-providers/self-hosted/zitadel-new-project.png
#	public/img/integrations/identity-providers/self-hosted/zitadel-redirect-settings.png
#	public/img/integrations/identity-providers/self-hosted/zitadel-service-account-role.png
#	public/img/integrations/identity-providers/self-hosted/zitadel-service-user-secret.png
#	public/img/integrations/identity-providers/self-hosted/zitadel-token-settings.png
This commit is contained in:
braginini
2023-05-22 18:53:45 +02:00
parent 393143d083 1fd3ddfda4
commit d52e1eac68
2 changed files with 296 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
docs/getting-started/zitadel-quickstart.md Normal file
View File

@@ -0,0 +1,133 @@
---
sidebar_position: 4
title: Zitadel Quickstart Guide
---
NetBird is open-source and can be self-hosted on your servers.
This guide describes how to quickly get started with a self-hosted NetBird instance with an auto-configured Zitadel identity provider. It explains the steps to set up and configure this configuration, enabling you to efficiently start using your own self-hosted NetBird instance.
### Step 1: Create Zitadel Service User
In this step we will create a `netbird` service user.
- Navigate to zitadel console
- Click `Users` in the top menu
- Select `Service Users` tab
- Click `New`
- Fill in the form with the following values:
- User Name: `netbird`
- Name: `netbird`
- Description: `Netbird Service User`
- Access Token Type: `JWT`
- Click `Create`
![](/img/getting-started/zitadel-create-user.png)
In this step we will generate `ClientSecret` for the `netbird` service user.
- Click `Actions` in the top right corner and click `Generate Client Secret`
- Copy `ClientSecret` from the dialog will be used later to set `ClientSecret` when prompted.
![](/img/getting-started/zitadel-service-user-secret.png)
### Step 2: Grant manage-organization role to netbird service user
In this step we will grant `Org User Manager` role to `netbird` service user.
- Click `Organization` in the top menu
- Click `+` in the top right corner
- Search for `netbird` service user
- Check `Org Owner` checkbox
- Click `Add`
![](/img/getting-started/zitadel-service-account-role.png)
### Step 3: Get the latest stable NetBird code
```bash
#!/bin/bash
REPO="https://github.com/netbirdio/netbird/"
# this command will fetch the latest release e.g. v0.19.0
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
echo $LATEST_TAG
# this comman will clone the latest tag
git clone --depth 1 --branch $LATEST_TAG $REPO
```
Then switch to the infra folder that contains docker-compose file:
```bash
cd netbird/infrastructure_files/
```
### Step 4: Prepare configuration files
To simplify the setup we have prepared a script to substitute required properties in the [docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl) and [management.json.zitadel.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/management.json.zitadel.tmpl) files.
The [setup.env.example](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/setup.env.example) file contains multiple properties that have to be filled. You need to copy the example file to `setup.env` before updating it.
```bash
# Dashboard domain. e.g. app.mydomain.com
NETBIRD_DOMAIN=""
# OIDC configuration e.g., https://example.eu.auth0.com/.well-known/openid-configuration
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR-ZITADEL-HOST-AND-PORT>/.well-known/openid-configuration"
# indicates whether to use Auth0 or not: true or false
NETBIRD_USE_AUTH0="false"
NETBIRD_IDP_PROVIDER="zitadel"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
# e.g. hello@mydomain.com
NETBIRD_LETSENCRYPT_EMAIL=""
```
- Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
- Configure ```NETBIRD_LETSENCRYPT_EMAIL``` property.
This can be any email address. [Let's Encrypt](https://letsencrypt.org/) will create an account while generating a new certificate.
:::tip
Let's Encrypt will notify you via this email when certificates are about to expire. NetBird supports automatic renewal by default.
:::
:::info
If you want to setup netbird with your own reverse-Proxy and without using the integrated letsencrypt, follow [this step here instead](self-hosting#advanced-running-netbird-behind-an-existing-reverse-proxy).
:::
### Step 5: Disable single account mode (optional)
NetBird Management service runs in a single account mode by default since version v0.10.1.
Management service was creating a separate account for each registered user before v0.10.1.
Single account mode ensures that all the users signing up for your self-hosted installation will join the same account/network.
In most cases, this is the desired behavior.
If you want to disable the single-account mode, set `--disable-single-account-mode` flag in the
[docker-compose.yml.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/docker-compose.yml.tmpl)
`command` section of the `management` service.
### Step 6: Run configuration script
Make sure all the required properties set in the ```setup.env``` file and run:
```bash
./configure.sh
```
This will export all the properties as environment variables and generate ```docker-compose.yml``` and ```management.json``` files substituting required variables.
### Step 7: Run docker compose:
```bash
docker-compose up -d
```
### Step 8: Check docker logs (Optional)
```bash
docker-compose logs signal
docker-compose logs management
docker-compose logs coturn
docker-compose logs dashboard
```

163
docs/integrations/identity-providers/self-hosted/zitadel.md Normal file
View File

@@ -0,0 +1,163 @@
---
id: using-netbird-with-zitadel
title: Using NetBird with Zitadel
sidebar_position: 5
tags:
- integrations
- idp
- zitadel
- oidc
- how-to
---
This guide is a part of the [NetBird Self-hosting Guide](/getting-started/self-hosting) and explains how to integrate
**self-hosted** NetBird with [Zitadel](https://zitadel.com).
:::tip managed idp
If you prefer not to self-host an Identity and Access Management solution, then you could use a managed alternative like
[Auth0](/integrations/identity-providers/self-hosted/using-netbird-with-auth0).
:::
### 1. Create and configure Zitadel application
In this step, we will create and configure Netbird application in zitadel.
Create new zitadel project
- Navigate to zitadel console
- Click `Projects` at the top menu, then click `Create New Project` to create a new project
- Fill in the form with the following values and click `Continue`
- Name: `NETBIRD`
![](/img/integrations/identity-providers/self-hosted/zitadel-new-project.png)
Create new zitadel application
- Click `Projects` in the top menu and select `NETBIRD` project from the list
- Click `New` in `APPLICATIONS` section to create a new application
- Fill in the form with the following values and click `Continue`
- Name: `netbird`
- TYPE OF APPLICATION: `User Agent`
![](/img/integrations/identity-providers/self-hosted/zitadel-new-application.png)
- Fill in the form with the following values and click `Continue`
- Authentication Method: `PKCE`
![](/img/integrations/identity-providers/self-hosted/zitadel-new-application-auth.png)
- Fill in the form with the following values and click `Continue`
- Redirect URIs: `https://<domain>/auth` and click `+`
- Post Logout URIs: `https://<domain>/silent-auth` and click `+`
![](/img/integrations/identity-providers/self-hosted/zitadel-new-application-uri.png)
- Verify applications details and Click `Create` and then click `Close`
- Check `Refresh Token` checkbox and click `Save`
![](/img/integrations/identity-providers/self-hosted/zitadel-new-application-overview.png)
- Copy `Client ID` will be used later in the `setup.env`
### Step 2: Application Token Configuration
To configure `netbird` application token you need to:
- Click `Projects` in the top menu and select `NETBIRD` project from the list
- Select `netbird` application from `APPLICATIONS` section
- Click `Token Settings` in the left menu
- Fill in the form with the following values:
- Auth Token Type: `JWT`
- Check `Add user roles to the access token` checkbox
- Click `Save`
![](/img/integrations/identity-providers/self-hosted/zitadel-token-settings.png)
### Step 3: Application Redirect Configuration
:::caution
This step is intended for setup running in development mode with no SSL
:::
To configure `netbird` application redirect you need to:
- Click `Projects` in the top menu and select `NETBIRD` project from the list
- Select `netbird` application from `APPLICATIONS` section
- Click `Redirect Settings` in the left menu
- Fill in the form with the following values:
- Toggle `Development Mode`
- Click `Save`
![](/img/integrations/identity-providers/self-hosted/zitadel-redirect-settings.png)
### Step 4: Create a Service User
In this step we will create a `netbird` service user.
- Click `Users` in the top menu
- Select `Service Users` tab
- Click `New`
- Fill in the form with the following values:
- User Name: `netbird`
- Name: `netbird`
- Description: `Netbird Service User`
- Access Token Type: `JWT`
- Click `Create`
![](/img/integrations/identity-providers/self-hosted/zitadel-create-user.png)
In this step we will generate `ClientSecret` for the `netbird` service user.
- Click `Actions` in the top right corner and click `Generate Client Secret`
- Copy `ClientSecret` from the dialog will be used later to set `ClientSecret` in the `management.json`
![](/img/integrations/identity-providers/self-hosted/zitadel-service-user-secret.png)
### Step 5: Grant manage-users role to netbird service user
In this step we will grant `Org User Manager` role to `netbird` service user.
- Click `Organization` in the top menu
- Click `+` in the top right corner
- Search for `netbird` service user
- Check `Org User Manager` checkbox
- Click `Add`
![](/img/integrations/identity-providers/self-hosted/zitadel-service-account-role.png)
Your authority OIDC configuration will be available under:
```
https://<YOUR-ZITADEL-HOST-AND-PORT>/.well-known/openid-configuration
```
:::caution
Double-check if the endpoint returns a JSON response by calling it from your browser.
:::
- Set properties in the `setup.env` file:
```json
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR-ZITADEL-HOST-AND-PORT>/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_CLIENT_ID="<Client ID>"
NETBIRD_AUTH_AUDIENCE="<Client ID>"
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<Client ID>"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
```
- You can now continue with the [NetBird Self-hosting Guide](/getting-started/self-hosting#step-3-configure-identity-provider).
- Set property `IdpManagerConfig` in the `management.json` file with:
:::caution
The file management.json is created automatically. Please refer [here](/getting-started/self-hosting#step-5-run-configuration-script) for more information.
:::
```json
{
"ManagerType": "zitadel",
"ZitadelClientCredentials": {
"ClientID": "netbird",
"ClientSecret": "<CLIENT SECRET>",
"GrantType": "client_credentials",
"TokenEndpoint": "https://<YOUR-ZITADEL-HOST-AND-PORT>/oauth/v2/token",
"ManagementEndpoint": "https://<YOUR-ZITADEL-HOST-AND-PORT>/management/v1"
}
}
```