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

Add IDP integrations for self-hosted Netbird

Browse Source
This commit is contained in:
braginini
2022-08-16 11:39:44 +02:00
parent 69324bab12
commit ec5e278f82
10 changed files with 562 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/examples/_category_.json
View File

@@ -1,4 +1,4 @@
{
"label": "Examples",
"position": 4
"position": 5
}

130
docs/getting-started/self-hosting.md
View File

@@ -7,22 +7,11 @@ sidebar_position: 2
NetBird is open-source and can be self-hosted on your servers.
It relies on components developed by NetBird Authors [Management Service](https://github.com/netbirdio/netbird/tree/main/management), [Management UI Dashboard](https://github.com/netbirdio/dashboard), [Signal Service](https://github.com/netbirdio/netbird/tree/main/signal),
a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn) and a 3rd party service [Auth0](https://auth0.com/).
:::info auth0
All the components can be self-hosted except for the Auth0 service.
This service offers excellent support for multiple features that we need, and it saved us lots of time.
We couldn't find any suitable open-source solution that would be a good combination of effort and benefit.
There is a free plan that can fulfill most of the personal use-cases.
There were a few discussions about alternatives on [GitHub](https://github.com/netbirdio/dashboard/issues/9).
We'd greatly appreciate any help on integrating one of the open-source Auth0 alternatives.
:::
a 3rd party open-source STUN/TURN service [Coturn](https://github.com/coturn/coturn), and an identity provider (available options will be listed later in this guide).
:::tip architecture
If you would like to learn more about the architecture please refer to the [Architecture section](/overview/architecture).
:::
### Requirements
@@ -34,89 +23,76 @@ If you would like to learn more about the architecture please refer to the [Arch
- Coturn is used for relay using the STUN/TURN protocols. It requires a listening port, UDP 3478, and range of ports, UDP 49152-65535, for dynamic relay connections. These are set as defaults in setup file, but can be configured to your requirements.
- Maybe a cup of coffee or tea :)
### Step-by-step guide
For this tutorial we will be using domain ```demo.netbird.io``` which points to our Ubuntu 22.04 machine hosted at Hetzner.
1. Create Auth0 account at [auth0.com](https://auth0.com/).
2. Get latest released NetBird code:
### Step 1: 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.6.1
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
```
```bash
#!/bin/bash
REPO="https://github.com/netbirdio/netbird/"
# this command will fetch the latest release e.g. v0.8.7
LATEST_TAG=$(basename $(curl -fs -o/dev/null -w %{redirect_url} ${REPO}releases/latest))
echo $LATEST_TAG
and switch to the infra folder that contains docker-compose file:
# this comman will clone the latest tag
git clone --depth 1 --branch $LATEST_TAG $REPO
```
```bash
cd netbird/infrastructure_files/
```
3. Prepare configuration files.
Then switch to the infra folder that contains docker-compose file:
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.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/management.json.tmpl) files.
```bash
cd netbird/infrastructure_files/
```
### Step 2: Prepare configuration 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.
:::tip
You need to fill only the first 5 properties, the rest will be filled automatically at a later step.
:::
```bash
# Dashboard domain. e.g. app.mydomain.com
NETBIRD_DOMAIN=""
# e.g. dev-24vkclam.us.auth0.com
NETBIRD_AUTH0_DOMAIN=""
# e.g. 61u3JMXRO0oOevc7gCkZLCwePQvT4lL0
NETBIRD_AUTH0_CLIENT_ID=""
# e.g. https://app.mydomain.com/ or https://app.mydomain.com,
# Make sure you used the exact same value for Identifier
# you used when creating your Auth0 API
NETBIRD_AUTH0_AUDIENCE=""
# e.g. hello@mydomain.com
NETBIRD_LETSENCRYPT_EMAIL=""
```
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.tmpl](https://github.com/netbirdio/netbird/tree/main/infrastructure_files/management.json.tmpl) files.
Please follow the steps to get the values.
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.
4. Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
```bash
# Dashboard domain. e.g. app.mydomain.com
NETBIRD_DOMAIN=""
# e.g. dev-24vkclam.us.auth0.com
NETBIRD_AUTH0_DOMAIN=""
# e.g. 61u3JMXRO0oOevc7gCkZLCwePQvT4lL0
NETBIRD_AUTH0_CLIENT_ID=""
# e.g. https://app.mydomain.com/ or https://app.mydomain.com,
# Make sure you used the exact same value for Identifier
# you used when creating your Auth0 API
NETBIRD_AUTH0_AUDIENCE=""
# e.g. hello@mydomain.com
NETBIRD_LETSENCRYPT_EMAIL=""
```
5. Configure Auth0 ```NETBIRD_AUTH0_DOMAIN``` ```NETBIRD_AUTH0_CLIENT_ID``` properties.
Please follow the steps to get the values.
* To obtain these, please use [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0) up until "Install the Auth0 React SDK".
- Set ```NETBIRD_DOMAIN``` to your domain, e.g. `demo.netbird.io`
- Configure ```NETBIRD_LETSENCRYPT_EMAIL``` property:
> Use ```https://YOUR DOMAIN``` as ````Allowed Callback URLs````, ```Allowed Logout URLs```, ```Allowed Web Origins``` and ```Allowed Origins (CORS)```
* set the variables in the ```setup.env```
* :warning: Make sure that `Token Endpoint Authentication Method` is set to `None` in your Auth0 Default Application
6. Configure ```NETBIRD_AUTH0_AUDIENCE``` property.
This can be any email address. [Let's Encrypt](https://letsencrypt.org/) will create an account while generating a new certificate.
* Check [Auth0 Create An API](https://auth0.com/docs/quickstart/backend/golang#create-an-api) section to obtain AuthAudience.
* set the property in the ```setup.env``` file.
7. Configure ```NETBIRD_LETSENCRYPT_EMAIL``` property.
:::tip
Let's Encrypt will notify you via this email when certificates are about to expire. NetBird supports automatic renewal by default.
:::
This can be any email address. [Let's Encrypt](https://letsencrypt.org/) will create an account while generating a new certificate.
### Step 3: Configure Identity Provider
:::tip
Let's Encrypt will notify you via this email when certificates are about to expire. NetBird supports automatic renewal by default.
:::
8. Make sure all the required properties set in the ```setup.env``` file and run:
### Step 4: Run configuration script
Make sure all the required properties set in the ```setup.env``` file and run:
```bash
./configure.sh
```
```bash
./configure.sh
```
This will export all the properties as environment variables and generate ```docker-compose.yml``` and ```management.json``` files substituting required variables.
This will export all the properties as environment variables and generate ```docker-compose.yml``` and ```management.json``` files substituting required variables.
9. Run docker compose:
### Step 5: Run docker compose:
```bash
docker-compose up -d
```
10. Optionally check the logs by running:
```bash
docker-compose up -d
```
### Step 5: Check docker logs (Optional)
```bash
docker-compose logs signal

4
docs/integrations/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Integrations",
"position": 4
}

4
docs/integrations/identity-providers/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Identity Providers",
"position": 4
}

4
docs/integrations/identity-providers/self-hosted/_category_.json Normal file
View File

@@ -0,0 +1,4 @@
{
"label": "Self-Hosted NetBird",
"position": 4
}

41
docs/integrations/identity-providers/self-hosted/auth0.md Normal file
View File

@@ -0,0 +1,41 @@
---
id: using-netbird-with-auth0
title: Using NetBird with Auth0
sidebar_position: 1
tags:
- integrations
- idp
- auth0
- 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 [Auth0](https://auth0.com/).
Auth0 is a flexible, drop-in solution to add authentication and authorization services to your applications.
It is a 3rd party managed service and can't be self-hosted. Auth0 is the right choice if you don't want to manage an Identity Provider (IDP)
instance on your own.
:::tip self-hosted idp
If you prefer to have full control over authentication and authorization of your NetBird network, there are good
self-hosted alternatives to the managed Auth0 service like [Keycloak](/integrations/identity-providers/self-hosted/using-netbird-with-keycloak).
:::
### Step 1: Create Auth0 account
To create an Auth0 account, sign up at [https://auth0.com](https://auth0.com/).
### Step 2: Configure Auth0 properties in the setup.env file
1. Configure ```NETBIRD_AUTH0_DOMAIN``` and ```NETBIRD_AUTH0_CLIENT_ID``` properties.
* To obtain these, please use [Auth0 React SDK Guide](https://auth0.com/docs/quickstart/spa/react/01-login#configure-auth0) up until "Install the Auth0 React SDK".
> Use ```https://YOUR DOMAIN``` as ````Allowed Callback URLs````, ```Allowed Logout URLs```, ```Allowed Web Origins``` and ```Allowed Origins (CORS)```
* set the variables in the ```setup.env```
* :warning: Make sure that `Token Endpoint Authentication Method` is set to `None` in your Auth0 Default Application
2. Configure ```NETBIRD_AUTH0_AUDIENCE``` property.
* Check [Auth0 Create An API](https://auth0.com/docs/quickstart/backend/golang#create-an-api) section to obtain AuthAudience.
* set the property in the ```setup.env``` file.
### Step 3: Continue with the self-hosting guide
You can now continue with the [NetBird Self-hosting Guide](/getting-started/self-hosting).

341
docs/integrations/identity-providers/self-hosted/keycloak.md Normal file
View File

@@ -0,0 +1,341 @@
---
id: using-netbird-with-keycloak
title: Using NetBird with Keycloak
sidebar_position: 1
tags:
- integrations
- idp
- oidc
- how-to
---
The NetBird client installation adds a binary called `netbird` to your system. This binary runs as a daemon service to connect
your computer or server to the NetBirt network as a peer. But it can also be used as a client to control the daemon service.
This section will explore the commands available in `netbird`.
## Syntax
Use the following syntax to run `netbird` commands from your terminal window:
```shell
netbird [command] [subcommand] [flags]
```
* `command`: Specifies the operation that you want to perform or a top-level command: `up`, `login`, `down`, `status`, `ssh`, `version`, and `service`
* `subcommand`: Specifies the operation to be executed for a top-level command like `service`: `install`, `uninstall`, `start`, and `stop`
* `flags`: Specifies optional flags. For example, you can use the `--setup-key` flag to specify the setup key to be used in the commands `login` and `up`
:::info Help
To see detailed command information, use the flag `--help` after each command
:::
## Global flags
`netbird` has a set of global flags that are available in every command. They specify settings that are core or shared between two or more commands, e.g. `--setup-key` is used by `login` and `up` to authenticate the client against a management service.
Below is the list of global flags:
```shell
--admin-url string Admin Panel URL [http|https]://[host]:[port] (default "https://app.netbird.io")
--config string Netbird config file location (default "/etc/netbird/config.json")
--daemon-addr string Daemon service address to serve CLI requests [unix|tcp]://[path|host:port] (default "unix:///var/run/netbird.sock")
--log-file string sets Netbird log path. If console is specified the the log will be output to stdout (default "/var/log/netbird/client.log")
--log-level string sets Netbird log level (default "info")
--management-url string Management Service URL [http|https]://[host]:[port] (default "https://api.wiretrustee.com:33073")
--preshared-key string Sets Wireguard PreSharedKey property. If set, then only peers that have the same key can communicate.
--setup-key string Setup key obtained from the Management Service Dashboard (used to register peer)
```
## Environment Variables
Every flag of a `netbird` command can be passed as an environment variable. We are using the following rule for the environment variables composition:
* `PREFIX_FLAGNAME` and for flags with multiple parts: `PREFIX_FLAGNAMEPART1_FLAGNAMEPART2`
* The prefix is always **NB**
* The flag parts are separated by a dash ("-") when passing as flags and with an underscore ("_") when passing as an environment variable
For example, let's check how we can pass `--config` and `--management-url` as environment variables:
```shell
export NB_CONFIG="/opt/netbird/config.json"
export NB_MANAGEMENT_URL="https://api.self-hosted.com:33073"
netbird up
```
The `up` command would process the variables, read the configuration file on `/opt/netbird/config.json` and attempt to connect to the management service running at `https://api.self-hosted.com:33073`.
## Commands
### up
Single command to log in and start the NetBird client. It can send a signal to the daemon service or run in the foreground with the flag `--log-file` set as `console`.
The command will check if the peer is logged in and connect to the management service. If the peer is not logged in, by default, it will attempt to initiate an SSO login flow.
#### Usage
The minimal form of running the command is:
```shell
netbird up
```
If you are running on a self-hosted environment, you can pass your management url by running the following:
```shell
netbird up --management-url https://api.self-hosted.com:33073
```
if you want to run in the foreground, you can use "console" as the value for `--log-file` and run the command with sudo:
```shell
sudo netbird up --log-file console
```
:::info
On Windows, you may need to run the command from an elevated terminal session.
:::
In case you need to use a setup key, use the `--setup-key` flag :
```shell
netbird up --setup-key AAAA-BBB-CCC-DDDDDD
```
### login
Command to authenticate the NetBird client to a management service. If the peer is not logged in, by default, it will attempt to initiate an SSO login flow.
#### Usage
The minimal form of running the command is:
```shell
netbird login
```
If you are running on a self-hosted environment, you can pass your management url by running the following:
```shell
netbird login --management-url https://api.self-hosted.com:33073
```
In case you need to use a setup key, use the `--setup-key` flag:
```shell
netbird login --setup-key AAAA-BBB-CCC-DDDDDD
```
Passing a management url and a setup key:
```shell
netbird login --setup-key AAAA-BBB-CCC-DDDDDD --management-url https://api.self-hosted.com:33073
```
### down
Command to stop a connection with the management service and other peers in a NetBird network. After running this command, the daemon service will enter an `Idle` state.
#### Usage
The minimal form of running the command is:
```shell
netbird down
```
### status
Retrieves the peer status from the daemon service.
#### Flags
```shell
-d, --detail display detailed status information
--filter-by-ips strings filters the detailed output by a list of one or more IPs, e.g. --filter-by-ips 100.64.0.100,100.64.0.200
--filter-by-status string filters the detailed output by connection status(connected|disconnected), e.g. --filter-by-status connected
```
#### Usage
The minimal form of running the command is:
```shell
netbird status
```
This will output:
```shell
Daemon status: Connected
Management: Connected
Signal: Connected
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Peers count: 2/3 Connected
```
If you want to see more details about the peer connections, you can use the `--detail` or `-d` flag:
```shell
netbird status -d
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.85.4
Public key: 2lI3F+fDUWh58g5oRN+y7lPHpNcEVWhiDv/wr1/jiF8=
Status: Disconnected
-- detail --
Connection type: -
Direct: false
ICE candidate (Local/Remote): -/-
Last connection update: 2022-07-07 12:21:31
Peer:
NetBird IP: 100.119.201.225
Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
Last connection update: 2022-07-07 12:21:32
Peer:
NetBird IP: 100.119.230.104
Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
Last connection update: 2022-07-07 12:21:33
Daemon status: Connected
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Peers count: 2/3 Connected
```
To filter the peers' output by connection status, you can use the `--filter-by-status` flag with either "connected" or "disconnected" as value:
```shell
netbird status -d --filter-by-status connected
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.201.225
Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
Last connection update: 2022-07-07 12:21:32
Peer:
NetBird IP: 100.119.230.104
Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
Last connection update: 2022-07-07 12:21:33
Daemon status: Connected
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Peers count: 2/3 Connected
```
To filter the peers' output by peer IP addresses, you can use the `--filter-by-ips` flag with one or more IPs separated by a comma as a value:
```shell
netbird status -d --filter-by-ips 100.119.201.225
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.201.225
Public key: +jkH8cs/Fo83qdB6dWG16+kAQmGTKYoBYSAdLtSOV10=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
Last connection update: 2022-07-07 12:21:32
Daemon status: Connected
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Peers count: 2/3 Connected
```
You can combine both filters and get the peers that are both connected and with specific IPs:
```shell
netbird status -d --filter-by-status connected --filter-by-ips 100.119.85.4,100.119.230.104
```
This will output:
```shell
Peers detail:
Peer:
NetBird IP: 100.119.230.104
Public key: R7olj0S8jiYMLfOWK+wDto+j3pE4vR54tLGrEQKgBSw=
Status: Connected
-- detail --
Connection type: P2P
Direct: true
ICE candidate (Local/Remote): host/host
Last connection update: 2022-07-07 12:21:33
Daemon status: Connected
Management: Connected to https://api.netbird.io:33073
Signal: Connected to https://signal2.wiretrustee.com:10000
NetBird IP: 100.119.62.6/16
Interface type: Kernel
Peers count: 2/3 Connected
```
:::info Filtered
The peer with IP `100.119.85.4` wasn't returned because it was not connected
:::
### ssh
Command to connect using ssh to a remote peer in your NetBird network.
You should run the ssh command with elevated permissions.
#### Flags
```shell
-p, --port int Sets remote SSH port. Defaults to 44338 (default 44338)
```
#### Arguments
The ssh command accepts one argument, `user@host`; this argument indicates the remote host to connect:
* `user`: indicates the remote user to login
* `host`: indicates the remote peer host IP address
#### Usage
The minimal form of running the command is:
```shell
sudo netbird ssh user@100.119.230.104
```
If you the remote peer agent is running the ssh service on a different port, you can use the `--port` or `-p` flag:
```shell
sudo netbird ssh -p 3434 user@100.119.230.104
```
### version
Outputs the `netbird` command version.
#### Usage
The minimal form of running the command is:
```shell
netbird version
```
This will output:
```shell
0.8.2
```
### service
The service command is a top-level command with subcommands to perform operations related to the daemon service.
You should run the service command with elevated permissions.
### service install
The install installs the daemon service on the system.
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service install
```
You can use the global flags to configure the daemon service. For instance, you can set a debug log level with the flag `--log-level`
```shell
sudo netbird service install --log-level debug
```
You can set a custom configuration path with the flag `--config`
```shell
sudo netbird service install --config /opt/netbird/config.json
```
### service uninstall
The uninstall uninstalls the daemon service from the system.
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service uninstall
```
### service start
Starts the daemon service
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service start
```
### service stop
Stops the daemon service
#### Usage
The minimal form of running the command is:
```shell
sudo netbird service stop
```

2
docs/other/_category_.json
View File

@@ -1,4 +1,4 @@
{
"label": "Other",
"position": 7
"position": 8
}

2
docs/reference/_category_.json
View File

@@ -1,4 +1,4 @@
{
"label": "Reference",
"position": 5
"position": 6
}