mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-23 02:46:35 +00:00
Merge remote-tracking branch 'upstream/main' into feat/okta-idp
This commit is contained in:
Bethuel
@@ -23,12 +23,9 @@ export default function App({ Component, pageProps }) {
|
||||
return (
|
||||
<>
|
||||
<Head>
|
||||
{router.pathname === '/' ? (
|
||||
<title>NetBird Docs</title>
|
||||
) : (
|
||||
router.pathname.startsWith('/docs') ?
|
||||
<title>{`${pageProps.title} - NetBird Docs`}</title> : <title>{`${pageProps.title} - NetBird API`}</title>
|
||||
)}
|
||||
{router.route.startsWith('/ipa') ?
|
||||
<title>{`${pageProps.title} - NetBird API`}</title> : <title>{`${pageProps.title} - NetBird Docs`}</title>
|
||||
}
|
||||
<meta name="description" content={pageProps.description} />
|
||||
</Head>
|
||||
<MDXProvider components={mdxComponents}>
|
||||
|
||||
@@ -40,6 +40,7 @@ export default function Document() {
|
||||
<Html lang="en">
|
||||
<Head>
|
||||
<script dangerouslySetInnerHTML={{ __html: modeScript }} />
|
||||
<link rel="shortcut icon" href="/docs-static/img/favicon.ico" />
|
||||
</Head>
|
||||
<body className="bg-white antialiased dark:bg-zinc-900">
|
||||
<Main />
|
||||
|
||||
@@ -8,7 +8,7 @@ export const title = 'FAQ'
|
||||
NetBird's agent doesn't require any incoming port to be open; It negotiates the connection with the support of the signal and relay services.
|
||||
### Outgoing ports
|
||||
NetBird usually won't need open ports, but sometimes you or your IT team needs to secure and verify
|
||||
all outgoing traffic, and that may affect how NetBird clients connect to the [control layer](/docs/about-netbird/how-netbird-works)
|
||||
all outgoing traffic, and that may affect how NetBird clients connect to the [control layer](/about-netbird/how-netbird-works)
|
||||
and negotiate the peer-to-peer connections.
|
||||
|
||||
Below is the list of NetBird hosted endpoints and ports they listen to:
|
||||
@@ -17,17 +17,17 @@ The combination of these elements ensures that direct point-to-point connections
|
||||
A **Peer** is a machine or any device that is connected to the network.
|
||||
It can be a Linux server running in the cloud or on-premises, a personal laptop, or even a Raspberry PI.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/high-level-dia.png" alt="high-level-dia" width="781" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
<p>
|
||||
<img src="/docs-static/img/architecture/high-level-dia.png" alt="high-level-dia" width="781" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
</p>
|
||||
|
||||
With NetBird clients installed and authorized on the Management service, machines form a mesh network connecting to each other directly via an encrypted point-to-point Wireguard tunnel.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/mesh.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
<p>
|
||||
<img src="/docs-static/img/architecture/mesh.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
While it is possible to create a full mesh network, it might be not a desirable outcome. In this case, [ACLs](/docs/how-to/restrict-access-to-peers) can be utilized to limit the access to certain machines.
|
||||
While it is possible to create a full mesh network, it might be not a desirable outcome. In this case, [ACLs](/how-to/manage-network-access) can be utilized to limit the access to certain machines.
|
||||
|
||||
Let's now take a closer look at each of NetBird's components.
|
||||
|
||||
@@ -39,7 +39,7 @@ It keeps the network state, public Wireguard keys of the peers, authenticates an
|
||||
The Management Service's responsibilities include:
|
||||
|
||||
* **Registering and authenticating new peers.** Every new machine has to register itself in the network in order to connect to other machines.
|
||||
After installation, NetBird client requires login that can be done through Identity Provider (IDP) or with a [setup key](/docs/how-to/register-peers-using-setup-keys).
|
||||
After installation, NetBird client requires login that can be done through Identity Provider (IDP) or with a [setup key](/how-to/register-machines-using-setup-keys).
|
||||
* **Keeping the network map.** The Management service stores information about all the registered peers including Wireguard public key that was sent during the registration process.
|
||||
* **Managing private IP addresses.** Each peer receives a unique private IP with which it can be identified in the network.
|
||||
We use [Carrier Grade NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT) address space with an allocated address block <em>100.64.0.0/10</em>.
|
||||
@@ -53,8 +53,8 @@ After that, they are able to establish a connection to the new peer.
|
||||
|
||||
The Management service runs in the cloud NetBird-managed. It can also be self-hosted.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/management.png" alt="management-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
<p>
|
||||
<img src="/docs-static/img/architecture/management.png" alt="management-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Client Application
|
||||
@@ -87,15 +87,15 @@ The only Signal's responsibility is:
|
||||
* **Serve as a notification mechanism for peers.** Before a connection can be established, peers need to find each other and exchange the most suitable connection candidates.
|
||||
This is done through Signal. After a connection has been established, Signal steps out.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/signal.png" alt="signal-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
<p>
|
||||
<img src="/docs-static/img/architecture/signal.png" alt="signal-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
Messages that are sent over Signal are **peer-to-peer encrypted**, so Signal can't see the contents.
|
||||
</Note>
|
||||
|
||||
NetBird Signal is very similar to the signaling servers used in [WebRTC](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling#the_signaling_server).
|
||||
NetBird Signal is very similar to the signaling servers used in [WebRTC](https://developer.mozilla.org/en-US/Web/API/WebRTC_API/Signaling_and_video_calling#the_signaling_server).
|
||||
It runs in the cloud NetBird-managed and can be self-hosted.
|
||||
|
||||
### Relay Service
|
||||
@@ -104,8 +104,8 @@ The Relay service is a [TURN server](https://webrtc.org/getting-started/turn-ser
|
||||
In fact, we use an open-source implementation called [Coturn](https://github.com/coturn/coturn).
|
||||
The purpose of this service is to be a "plan B" and relay traffic between peers in case a peer-to-peer connection isn't possible.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/relay.png" alt="relay-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}/>
|
||||
<p>
|
||||
<img src="/docs-static/img/architecture/relay.png" alt="relay-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
@@ -123,7 +123,7 @@ Below is a high level, step-by-step overview of the flow of communications withi
|
||||
|
||||
1. Administrator creates an account at [app.netbird.io](https://app.netbird.io/).
|
||||
2. The system automatically generates a new network with an allocated address block <em>100.64.0.0/10</em>.
|
||||
3. The system automatically generates 2 [setup keys](/docs/how-to/register-peers-using-setup-keys) that can be used for authenticating new machines.
|
||||
3. The system automatically generates 2 [setup keys](/how-to/register-machines-using-setup-keys) that can be used for authenticating new machines.
|
||||
4. Administrator (or a user) installs NetBird client and runs ```netbird up``` command providing one of the setup keys.
|
||||
5. NetBird client generates Wireguard private and public keys along with the initial configuration.
|
||||
6. NetBird client sends a registration request to the NetBird Management service calling Login gRPC endpoint, providing setup key, Wireguard public key and additional information about the machine.
|
||||
@@ -23,7 +23,7 @@ To achieve this, NetBird client applications employ signalling servers to find o
|
||||
These are similar to the signaling servers used in [WebRTC](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling#the_signaling_server)
|
||||
|
||||
Thanks to [NAT traversal techniques](https://en.wikipedia.org/wiki/NAT_traversal),
|
||||
outlined in the [Why Wireguard with NetBird](/docs/about-netbird/why-wireguard-with-netbird) section,
|
||||
outlined in the [Why Wireguard with NetBird](/about-netbird/why-wireguard-with-netbird) section,
|
||||
NetBird installation doesn't require complex network and firewall configuration.
|
||||
It just works, minimising the maintenance effort.
|
||||
|
||||
@@ -21,7 +21,7 @@ The goal of the task is to get familiar with the system by setting up a self-hos
|
||||
It is possible to set up multiple peers on the same machine. Find out how!
|
||||
</Note>
|
||||
4. Ping machines and make sure that they are reachable.
|
||||
5. We might ask you to provide a generated [setup key](/docs/how-to/setup-keys) so that we could test your setup.
|
||||
5. We might ask you to provide a generated [setup key](/how-to/setup-keys) so that we could test your setup.
|
||||
|
||||
Please reach out to us with any questions. We believe you will have some! :)
|
||||
|
||||
@@ -3,14 +3,14 @@
|
||||
|
||||
## Service Users
|
||||
|
||||
Service users are non-interactive accounts that are used to create tokens to access resources and perform actions within your organization's network using NetBird's public API.
|
||||
Service users are non-interactive accounts that are used to create tokens to access resources and perform actions within your organization's network using [NetBird's public API](/api).
|
||||
|
||||
Service users provide additional security by allowing you to limit the scope of access granted to the service user and void losing automated access to critical systems when employees leave the company.
|
||||
|
||||
### What can you use NetBird service users and access tokens for?
|
||||
|
||||
|
||||
Most network management operations administrators do in the NetBird dashboard (https://app.netbird.io) can also be done via NetBird API using service users' access tokens.
|
||||
Most network management operations administrators do in the [NetBird Dashboard](https://app.netbird.io) can also be done via NetBird API using service users' access tokens.
|
||||
|
||||
The most common usage scenarios:
|
||||
|
||||
@@ -21,15 +21,15 @@ The most common usage scenarios:
|
||||
### Creating a service user
|
||||
|
||||
To create a service user, you'll need to log in to your organization's account at https://app.netbird.io and navigate to the "Users" -> "Service Users" section of your account.
|
||||
<p align="center">
|
||||
<img src="/img/overview/service-user-overview.png" alt="service-user-overview" width="780" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/service-user-overview.png" alt="service-user-overview" width="780" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
From there, you can create a new service user and specify a role that the user should have.
|
||||
User role allows read-only access, use the admin for write access.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/service-user-creation.png" alt="service-user-creation-popup" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/service-user-creation.png" alt="service-user-creation-popup" width="400" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
@@ -40,21 +40,21 @@ User role allows read-only access, use the admin for write access.
|
||||
|
||||
To create an access token, you'll need to log in to your account and navigate to the "Users" section and look for your user or create a [service user](#service-users) to use for your API requests.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/personal-access-token-overview.png" alt="personal-access-token-overview" width="780" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/personal-access-token-overview.png" alt="personal-access-token-overview" width="780" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
From there, you can create a new token and specify expiration for the token. You won't be able to modify your token.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/personal-access-token-creation.png" alt="personal-access-creation-popup" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/personal-access-token-creation.png" alt="personal-access-creation-popup" width="400" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
After the token was generated successfully you will see a plain version of your token to copy and store in a secure place.
|
||||
Be aware that once you close the popup it is impossible to see the plain version of the token again as NetBird only stores a hashed version of the token.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/personal-access-token-example.png" alt="personal-access-token-example" width="400" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/personal-access-token-example.png" alt="personal-access-token-example" width="400" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
@@ -63,7 +63,7 @@ Be aware that once you close the popup it is impossible to see the plain version
|
||||
|
||||
### Using access tokens
|
||||
|
||||
Once you have created an access token, you can use it to authenticate API requests to NetBird. See [NetBird API](/ipa/introductions) documentation for detailed usage.
|
||||
Once you have created an access token, you can use it to authenticate API requests to NetBird. See [NetBird API](/api/introduction) documentation for detailed usage.
|
||||
|
||||
For example, if you were using the GitHub API, you might include your personal access token like this:
|
||||
|
||||
48
src/pages/how-to/add-machines-to-your-network.mdx
Normal file
48
src/pages/how-to/add-machines-to-your-network.mdx
Normal file
@@ -0,0 +1,48 @@
|
||||
|
||||
# Add machines to your NetBird network
|
||||
|
||||
Whether you have a network for personal use or manage your company's corporate network, you'd probably want to add machines
|
||||
(or peers in NetBird's terms) to your network.
|
||||
|
||||
NetBird peer is a machine that runs the [NetBird agent](/about-netbird/how-netbird-works#client-application)
|
||||
and is connected to the network. NetBird peer can be a virtual machine running in the cloud like AWS or Google Cloud,
|
||||
an Android or iOS device, a personal laptop, a single-board computer like Raspberry Pi, a docker container, or even a router.
|
||||
|
||||
## Use NetBird web UI to add new peers
|
||||
|
||||
To add a new peer to your network follow these steps:
|
||||
1. Sign-in you NetBird account at https://app.netbird.io/ and go to the Peers tab.
|
||||
2. Hit `Add new peer` button
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/add-new-peer-empty.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
3. Follow the instructions
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/add-new-peer-popup.png" alt="high-level-dia" width="700" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
4. Refresh the Peers tab, and it will display new machines
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/peer-list.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
|
||||
## What's next?
|
||||
|
||||
Here are a few links that might be handy as you venture further into NetBird:
|
||||
|
||||
- [Add users to your network](/how-to/add-users-to-your-network)
|
||||
- [Use setup keys to automate NetBird deployments](/how-to/register-machines-using-setup-keys)
|
||||
|
||||
<p float="center" >
|
||||
<Button name="button" className="button-5" onClick={() => window.open("https://netbird.io/pricing")}>Try NetBird</Button>
|
||||
</p>
|
||||
|
||||
- Make sure to [star us on GitHub](https://github.com/netbirdio/netbird)
|
||||
- Follow us [on Twitter](https://twitter.com/netbird)
|
||||
- Join our [Slack Channel](https://join.slack.com/t/netbirdio/shared_invite/zt-vrahf41g-ik1v7fV8du6t0RwxSrJ96A)
|
||||
- NetBird [latest release](https://github.com/netbirdio/netbird/releases) on GitHub
|
||||
@@ -33,8 +33,8 @@ A user window will pop up where you can specify the name and email address of th
|
||||
The invited users will receive an email invitation that they have to confirm.
|
||||
After logging in to the system, they will join your network automatically.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/user-invites.gif" alt="high-level-dia" width="800" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/user-invites.gif" alt="high-level-dia" width="800" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
@@ -26,8 +26,8 @@ Below is the list of global flags:
|
||||
--admin-url string Admin Panel URL [http|https]://[host]:[port] (default "https://app.netbird.io")
|
||||
-c, --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")
|
||||
-l, --log-level string sets Netbird log level (default "info")
|
||||
--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")
|
||||
-l, --log-level string sets NetBird log level (default "info")
|
||||
-m, --management-url string Management Service URL [http|https]://[host]:[port] (default "https://api.wiretrustee.com:443")
|
||||
-p, --preshared-key string Sets Wireguard PreSharedKey property. If set, then only peers that have the same key can communicate.
|
||||
-k, --setup-key string Setup key obtained from the Management Service Dashboard (used to register peer)
|
||||
@@ -1,17 +1,17 @@
|
||||
|
||||
# Configure periodic user authentication
|
||||
# Enforce periodic user authentication
|
||||
|
||||
To ensure a high level of security, NetBird offers a peer login expiration feature that requires users to periodically reauthenticate their devices.
|
||||
Every new network has this feature enabled, and the expiration period is set to 24 hours by default. You can disable this feature and configure the expiration period in the account settings in the web UI https://app.netbird.io/settings.
|
||||
|
||||
<Note>
|
||||
This feature is only applied to peers added with the [interactive SSO login feature](/getting-started/installation#running-netbird-with-sso-login). Peers, added with a setup key, won't be affected.
|
||||
This feature is only applied to peers added with the [interactive SSO login feature](/how-to/installation#running-net-bird-with-sso-login). Peers, added with a setup key, won't be affected.
|
||||
</Note>
|
||||
|
||||
Expired peers will appear in the peers' view with the status `needs login`.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/peer-needs-login.png" alt="peer-needs-login.png" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/peer-needs-login.png" alt="peer-needs-login.png" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
## Configure and disable expiration
|
||||
@@ -19,8 +19,8 @@ The expiration period can be set to anything between one hour and 180 days.
|
||||
Go to the Web UI Settings tab and set the desired period in the Authentication section.
|
||||
You can also disable the expiration for the whole network in the same section.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/peer-login-expiration.png" alt="peer-login-expiration" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/peer-login-expiration.png" alt="peer-login-expiration" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
|
||||
@@ -35,8 +35,8 @@ With NetBird you can disable login expiration per peer without disabling expirat
|
||||
In the Peers tab of the web UI click on the peer you want to disable expiration for and use the Login Expiration switch.
|
||||
Peers with `expiration disabled` will be marked with a corresponding label in the peers' table.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/individual-peer-login-expiration.png" alt="peer-login-expiration" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/individual-peer-login-expiration.png" alt="peer-login-expiration" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
## Get started
|
||||
@@ -3,8 +3,8 @@ export const title = 'Examples'
|
||||
|
||||
## NetBird Client on AWS ECS (Terraform)
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/examples/wiretrustee-on-aws-ecs.png" alt="high-level-dia" width="400"/>
|
||||
<p>
|
||||
<img src="/docs-static/img/examples/wiretrustee-on-aws-ecs.png" alt="high-level-dia" width="400"/>
|
||||
</p>
|
||||
|
||||
A common way to run containers in the AWS cloud is to use Elastic Container Service (ECS).
|
||||
@@ -100,7 +100,7 @@ One of the simplest ways of running NetBird client application is to use a pre-b
|
||||
* **NetBird account.**
|
||||
Register one at [app.netbird.io](https://app.netbird.io/).
|
||||
|
||||
You would need to obtain a [setup key](/docs/how-to/register-peers-using-setup-keys) to associate NetBird client with your account.
|
||||
You would need to obtain a [setup key](/how-to/register-machines-using-setup-keys) to associate NetBird client with your account.
|
||||
|
||||
The setup key could be found in the NetBird Management dashboard under the Setup Keys tab - [https://app.netbird.io/setup-keys](https://app.netbird.io/setup-keys).
|
||||
|
||||
@@ -6,39 +6,48 @@ export const title = 'Getting Started'
|
||||
|
||||
Step-by-step video guide on YouTube:
|
||||
|
||||
<div class="videowrapper">
|
||||
<div className="videowrapper">
|
||||
<iframe src="https://www.youtube.com/embed/HYlhvr_eu2U" allow="fullscreen;"></iframe>
|
||||
</div>
|
||||
<br/>
|
||||
This guide describes how to quickly get started with NetBird and create a secure private network with 2 connected machines.
|
||||
This guide describes how to quickly get started with NetBird and create a secure private network with two connected machines.
|
||||
|
||||
One machine is a Linux laptop, and the other one a EC2 node running on AWS.
|
||||
Both machines are running Linux but NetBird also works on Windows and MacOS.
|
||||
Both machines are running Linux but NetBird also works on Windows, MacOS nad popular mobile platforms like Android and iOS.
|
||||
|
||||
1. Sign-up at [https://app.netbird.io/](https://app.netbird.io/)
|
||||
|
||||
You can use your Google, GitHub or Microsoft account.
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/auth.png" alt="login-to-netbird" className="imagewrapper" />
|
||||
</p>
|
||||
|
||||
2. After a successful login you will be redirected to the ```Peers``` screen which is empty because you don't have any peers yet.
|
||||
|
||||
Click ```Add peer``` to add a new machine.
|
||||
The `Add peer` window should automatically pop up, but if it doesn't, click ```Add new peer``` to add a new machine.
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/empty-peers.png" alt="login-to-netbird" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
3. Choose your machine operating system (in our case it is ```Linux```) and proceed with the installation steps.
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/add-peer.png" alt="login-to-netbird" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
4. If you installed NetBird Desktop UI you can use it to connect to the network instead of running `netbird up` command. Look for `NetBird` in your application list, run it, and click `Connect`.
|
||||
>
|
||||
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/systray.png" alt="login-to-netbird" className="imagewrapper"/>
|
||||
</p>
|
||||
5. At this point a browser window pops up starting a device registration process. Click confirm and follow the steps if required.
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/device-confirmation.png" alt="login-to-netbird" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
6. On the EC2 node repeat the installation steps and run `netbird up` command.
|
||||
|
||||
@@ -47,11 +56,15 @@ sudo netbird up
|
||||
```
|
||||
7. Copy the verification URL from the terminal output and paste it in your browser. Repeat step #5
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/netbird-up.png" alt="login-to-netbird" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
8. Return to ```Peers``` and you should notice 2 new machines with status ```online```
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/peers.png" alt="login-to-netbird" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
9. To test the connection you could try pinging devices:
|
||||
|
||||
@@ -258,7 +271,7 @@ If you installed the Desktop UI client, you can launch it and click on Connect.
|
||||
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
|
||||
|
||||
<p>
|
||||
<img src="/img/getting-started/netbird-sso-login-ui.gif" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<img src="/docs-static/img/getting-started/netbird-sso-login-ui.gif" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
#### CLI
|
||||
@@ -269,7 +282,7 @@ Alternatively, you could use command line. Simply run
|
||||
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
|
||||
|
||||
<p>
|
||||
<img src="/img/getting-started/netbird-sso-login-cmd.gif" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<img src="/docs-static/img/getting-started/netbird-sso-login-cmd.gif" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Check connection status:
|
||||
@@ -278,10 +291,10 @@ Check connection status:
|
||||
```
|
||||
|
||||
### Running NetBird with a Setup Key
|
||||
In case you are activating a server peer, you can use a [setup key](/docs/how-to/register-peers-using-setup-keys) as described in the steps below.
|
||||
In case you are activating a server peer, you can use a [setup key](/how-to/register-machines-using-setup-keys) as described in the steps below.
|
||||
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
|
||||
|
||||
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/docs/how-to/register-peers-using-setup-keys)).
|
||||
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/how-to/register-machines-using-setup-keys)).
|
||||
|
||||
For all systems:
|
||||
```bash
|
||||
@@ -325,13 +338,13 @@ On **Windows**:
|
||||
|
||||
Set the ```NB_SETUP_KEY``` environment variable and run the command.
|
||||
<Note>
|
||||
You can pass other settings as environment variables. See [Environment variables](reference/netbird-commands.md#environment-variables) for details.
|
||||
You can pass other settings as environment variables. See [environment variables](/how-to/cli#environment-variables) for details.
|
||||
</Note>
|
||||
```bash
|
||||
docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:latest
|
||||
```
|
||||
|
||||
See [Docker example](examples/netbird-docker.md) for details.
|
||||
See [Docker example](/how-to/examples#net-bird-client-in-docker) for details.
|
||||
|
||||
### Troubleshooting
|
||||
1. If you are using self-hosted version and haven't specified `--management-url`, the client app will use the default URL
|
||||
287
src/pages/how-to/installation.mdx
Normal file
287
src/pages/how-to/installation.mdx
Normal file
@@ -0,0 +1,287 @@
|
||||
import {Note} from "@/components/mdx";
|
||||
|
||||
export const title = 'Installation'
|
||||
|
||||
## Installation
|
||||
|
||||
### Linux
|
||||
|
||||
**APT/Debian**
|
||||
1. Add the repository:
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install ca-certificates curl gnupg -y
|
||||
curl -sSL https://pkgs.wiretrustee.com/debian/public.key | sudo gpg --dearmor --output /usr/share/keyrings/wiretrustee-archive-keyring.gpg
|
||||
echo 'deb [signed-by=/usr/share/keyrings/wiretrustee-archive-keyring.gpg] https://pkgs.wiretrustee.com/debian stable main' | sudo tee /etc/apt/sources.list.d/wiretrustee.list
|
||||
```
|
||||
2. Update APT's cache
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
```
|
||||
3. Install the package
|
||||
|
||||
```bash
|
||||
# for CLI only
|
||||
sudo apt-get install netbird
|
||||
# for GUI package
|
||||
sudo apt-get install netbird-ui
|
||||
```
|
||||
|
||||
**RPM/Red hat**
|
||||
|
||||
1. Add the repository:
|
||||
```bash
|
||||
cat <<EOF | sudo tee /etc/yum.repos.d/wiretrustee.repo
|
||||
[Wiretrustee]
|
||||
name=Wiretrustee
|
||||
baseurl=https://pkgs.wiretrustee.com/yum/
|
||||
enabled=1
|
||||
gpgcheck=0
|
||||
gpgkey=https://pkgs.wiretrustee.com/yum/repodata/repomd.xml.key
|
||||
repo_gpgcheck=1
|
||||
EOF
|
||||
```
|
||||
2. Install the package
|
||||
```bash
|
||||
# for CLI only
|
||||
sudo yum install netbird
|
||||
# for GUI package
|
||||
sudo yum install netbird-ui
|
||||
```
|
||||
|
||||
**Fedora**
|
||||
|
||||
1. Create the repository file:
|
||||
```bash
|
||||
cat <<EOF | sudo tee /etc/yum.repos.d/wiretrustee.repo
|
||||
[Wiretrustee]
|
||||
name=Wiretrustee
|
||||
baseurl=https://pkgs.wiretrustee.com/yum/
|
||||
enabled=1
|
||||
gpgcheck=0
|
||||
gpgkey=https://pkgs.wiretrustee.com/yum/repodata/repomd.xml.key
|
||||
repo_gpgcheck=1
|
||||
EOF
|
||||
```
|
||||
2. Import the file
|
||||
```bash
|
||||
sudo dnf config-manager --add-repo /etc/yum.repos.d/wiretrustee.repo
|
||||
```
|
||||
3. Install the package
|
||||
```bash
|
||||
# for CLI only
|
||||
sudo dnf install netbird
|
||||
# for GUI package
|
||||
sudo dnf install netbird-ui
|
||||
```
|
||||
|
||||
|
||||
**NixOS 22.11+/unstable**
|
||||
|
||||
1. Edit your [`configuration.nix`](https://nixos.org/manual/nixos/stable/index.html#sec-changing-config)
|
||||
|
||||
```nix
|
||||
{ config, pkgs, ... }:
|
||||
{
|
||||
services.netbird.enable = true; # for netbird service & CLI
|
||||
environment.systemPackages = [ pkgs.netbird-ui ]; # for GUI
|
||||
}
|
||||
```
|
||||
2. Build and apply new configuration
|
||||
|
||||
```bash
|
||||
sudo nixos-rebuild switch
|
||||
```
|
||||
|
||||
### macOS
|
||||
**Homebrew install**
|
||||
1. Download and install homebrew at https://brew.sh/
|
||||
2. If wiretrustee was previously installed with homebrew, you will need to run:
|
||||
```bash
|
||||
# Stop and uninstall daemon service:
|
||||
sudo wiretrustee service stop
|
||||
sudo wiretrustee service uninstall
|
||||
# unlik the app
|
||||
brew unlink wiretrustee
|
||||
```
|
||||
> netbird will copy any existing configuration from the Wiretrustee's default configuration paths to the new NetBird's default location
|
||||
|
||||
3. Install the client
|
||||
```bash
|
||||
# for CLI only
|
||||
brew install netbirdio/tap/netbird
|
||||
# for GUI package
|
||||
brew install --cask netbirdio/tap/netbird-ui
|
||||
```
|
||||
4. If you installed CLI only, you need to install and start the client daemon service:
|
||||
```bash
|
||||
sudo netbird service install
|
||||
sudo netbird service start
|
||||
```
|
||||
|
||||
### Windows
|
||||
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
|
||||
2. Download the latest Windows release installer ```netbird_installer_<VERSION>_windows_amd64.exe``` (**Switch VERSION to the latest**):
|
||||
3. Proceed with the installation steps
|
||||
4. This will install the UI client in the C:\\Program Files\\NetBird and add the daemon service
|
||||
5. After installing, you can follow the steps from [Running NetBird with SSO Login](#Running-NetBird-with-SSO-Login) steps.
|
||||
> To uninstall the client and service, you can use Add/Remove programs
|
||||
|
||||
⚠️ In case of any issues with the connection on Windows check the firewall settings. With default Windows 11 firewall setup there could be connectivity issue related to egress traffic.
|
||||
|
||||
Recommended way is to add NetBird in firewall settings:
|
||||
|
||||
1. Go to "Control panel".
|
||||
2. Select "Windows Defender Firewall".
|
||||
3. Select "Advanced settings".
|
||||
4. Select "Outbound Rules" -> "New rule".
|
||||
5. In the new rule select "Program" and click "Next".
|
||||
6. Point to the NetBird installation exe file (usually in `C:\Program Files\NetBird\netbird.exe`) and click "Next".
|
||||
7. Select "Allow the connection" and click "Next".
|
||||
8. Select the network in which rule should be applied (Domain, Private, Public) according to your needs and click "Next".
|
||||
9. Provide rule name (e.g. "Netbird Egress Traffic") and click "Finish".
|
||||
10. Disconnect and connect to NetBird.
|
||||
|
||||
### Android
|
||||
|
||||
NetBird has an official Android application that you can download at Google Play Store:
|
||||
|
||||
<p>
|
||||
<a href="https://play.google.com/store/apps/details?id=io.netbird.client" target="_blank">
|
||||
<img src="/docs-static/img/how-to-guides/google-play-badge.png" width="200" alt="playstore" className="imagewrapper"/>
|
||||
</a>
|
||||
|
||||
</p>
|
||||
|
||||
### Binary Install
|
||||
**Installation from binary (CLI only)**
|
||||
|
||||
1. Checkout NetBird [releases](https://github.com/netbirdio/netbird/releases/latest)
|
||||
2. Download the latest release:
|
||||
```bash
|
||||
curl -L -o ./netbird_<VERSION>.tar.gz https://github.com/netbirdio/netbird/releases/download/v<VERSION>/netbird_<VERSION>_<OS>_<Arch>.tar.gz
|
||||
```
|
||||
|
||||
<Note>
|
||||
|
||||
You need to replace some variables from the URL above:
|
||||
|
||||
- Replace **VERSION** with the latest released verion.
|
||||
- Replace **OS** with "linux", "darwin" for MacOS or "windows"
|
||||
- Replace **Arch** with your target system CPU archtecture
|
||||
|
||||
</Note>
|
||||
|
||||
3. Decompress
|
||||
```bash
|
||||
tar xcf ./netbird_<VERSION>.tar.gz
|
||||
sudo mv netbird /usr/bin/netbird
|
||||
sudo chown root:root /usr/bin/netbird
|
||||
sudo chmod +x /usr/bin/netbird
|
||||
```
|
||||
After that you may need to add /usr/bin in your PATH environment variable:
|
||||
````bash
|
||||
export PATH=$PATH:/usr/bin
|
||||
````
|
||||
4. Install and run the service
|
||||
```bash
|
||||
sudo netbird service install
|
||||
sudo netbird service start
|
||||
```
|
||||
|
||||
### Running NetBird with SSO Login
|
||||
#### Desktop UI Application
|
||||
If you installed the Desktop UI client, you can launch it and click on Connect.
|
||||
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/netbird-sso-login-ui.gif" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
#### CLI
|
||||
Alternatively, you could use command line. Simply run
|
||||
```bash
|
||||
netbird up
|
||||
```
|
||||
> It will open your browser, and you will be prompt for email and password. Follow the instructions.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/getting-started/netbird-sso-login-cmd.gif" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Check connection status:
|
||||
```bash
|
||||
netbird status
|
||||
```
|
||||
|
||||
### Running NetBird with a Setup Key
|
||||
In case you are activating a server peer, you can use a [setup key](/how-to/register-machines-using-setup-keys) as described in the steps below.
|
||||
> This is especially helpful when you are running multiple server instances with infrastructure-as-code tools like ansible and terraform.
|
||||
|
||||
1. Login to the Management Service. You need to have a `setup key` in hand (see [setup keys](/how-to/register-machines-using-setup-keys)).
|
||||
|
||||
For all systems:
|
||||
```bash
|
||||
netbird up --setup-key <SETUP KEY>
|
||||
```
|
||||
|
||||
For **Docker**, you can run with the following command:
|
||||
```bash
|
||||
docker run --network host --privileged --rm -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:<TAG>
|
||||
```
|
||||
> TAG > 0.6.0 version
|
||||
|
||||
Alternatively, if you are hosting your own Management Service provide `--management-url` property pointing to your Management Service:
|
||||
```bash
|
||||
netbird up --setup-key <SETUP KEY> --management-url http://localhost:33073
|
||||
```
|
||||
|
||||
> You could also omit the `--setup-key` property. In this case, the tool will prompt for the key.
|
||||
|
||||
2. Check connection status:
|
||||
```bash
|
||||
netbird status
|
||||
```
|
||||
|
||||
3. Check your IP:
|
||||
|
||||
On **macOS** :
|
||||
````bash
|
||||
sudo ifconfig utun100
|
||||
````
|
||||
On **Linux**:
|
||||
```bash
|
||||
ip addr show wt0
|
||||
```
|
||||
On **Windows**:
|
||||
```bash
|
||||
netsh interface ip show config name="wt0"
|
||||
```
|
||||
|
||||
### Running NetBird in Docker
|
||||
|
||||
Set the ```NB_SETUP_KEY``` environment variable and run the command.
|
||||
<Note>
|
||||
You can pass other settings as environment variables. See [Environment variables](/how-to/cli#environment-variables) for details.
|
||||
</Note>
|
||||
```bash
|
||||
docker run --rm --name PEER_NAME --hostname PEER_NAME --cap-add=NET_ADMIN -d -e NB_SETUP_KEY=<SETUP KEY> -v netbird-client:/etc/netbird netbirdio/netbird:latest
|
||||
```
|
||||
|
||||
See [Docker example](/how-to/examples#net-bird-client-in-docker) for details.
|
||||
|
||||
### Troubleshooting
|
||||
1. If you are using self-hosted version and haven't specified `--management-url`, the client app will use the default URL
|
||||
which is ```https://api.wiretrustee.com:33073```.
|
||||
|
||||
2. If you have specified a wrong `--management-url` (e.g., just by mistake when self-hosting)
|
||||
to override it you can do the following:
|
||||
|
||||
```bash
|
||||
netbird down
|
||||
netbird up --management-url https://<CORRECT HOST:PORT>/
|
||||
```
|
||||
|
||||
To override it see the solution #1 above.
|
||||
@@ -1,7 +1,7 @@
|
||||
|
||||
# Manage DNS in your network
|
||||
|
||||
<div class="videowrapper">
|
||||
<div className="videowrapper">
|
||||
<iframe src="https://www.youtube.com/embed/xxQ_QeEMC0U" allow="fullscreen;"></iframe>
|
||||
</div>
|
||||
<br/><br/>
|
||||
@@ -18,10 +18,10 @@ Starting [v0.11.0](https://github.com/netbirdio/netbird/releases), NetBird autom
|
||||
to each peer in a private `netbird.cloud` space that can be used to access the machines. E.g., `my-server.netbird.cloud`.
|
||||
|
||||
Besides accessing machines by their domain names, you can configure NetBird to use your private nameservers,
|
||||
control what nameservers a specific [peer group](/docs/how-to/access-control#concepts) should use, and set up split DNS.
|
||||
control what nameservers a specific [peer group](/how-to/manage-network-access#groups) should use, and set up split DNS.
|
||||
|
||||
<Note>
|
||||
Nameservers is available for NetBird [v0.11.0](https://github.com/netbirdio/netbird/releases) or later.
|
||||
Nameservers feature is available in NetBird [v0.11.0](https://github.com/netbirdio/netbird/releases) or later.
|
||||
</Note>
|
||||
|
||||
## Concepts
|
||||
@@ -56,8 +56,8 @@ A nameserver group defines up to 2 nameservers to resolve DNS to a set of peers
|
||||
|
||||
### Creating a nameserver group
|
||||
Access the `DNS` tab and click the `Add Nameserver` button to create a new nameserver.
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-nameserver-add-button.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-nameserver-add-button.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
That will open a nameserver selection configuration screen where you can choose between using three predefined public
|
||||
nameservers or using a custom setup.
|
||||
@@ -67,14 +67,14 @@ If you choose a predefined public nameserver option, you can select the followin
|
||||
- [Google DNS servers](https://developers.google.com/speed/public-dns/docs/using)
|
||||
- [Cloudflare DNS servers](https://one.one.one.one/dns/)
|
||||
- [Quad9 DNS servers](https://www.quad9.net/)
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-nameserver-selection-view-open.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-nameserver-selection-view-open.png" alt="high-level-dia" width="300" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
After selecting one of the three options, you need to assign a peer group for which this nameserver will be effective.
|
||||
In the example below, we chose the "All" group:
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-nameserver-all-group.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-nameserver-all-group.png" alt="high-level-dia" width="300" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
#### Creating custom nameservers
|
||||
@@ -87,16 +87,16 @@ In the example below, we are creating a nameserver with the following informatio
|
||||
- Add at least one nameserver: `192.168.0.32` with port `53`
|
||||
- Match mode: `All domains`
|
||||
- Distribution group: `Remote developers`
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-nameserver-custom.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-nameserver-custom.png" alt="high-level-dia" width="300" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Creating a nameserver for specific domains
|
||||
Sometimes we want to forward DNS queries to specific nameservers but only for particular domains that match a setting.
|
||||
Taking the example of custom nameservers above, you could select a match mode for only domains listed there.
|
||||
Below you can see the same nameserver setup but only for the `berlinoffice.com` domain:
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-nameserver-remote-resolver.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-nameserver-remote-resolver.png" alt="high-level-dia" width="300" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
@@ -107,13 +107,13 @@ Below you can see the same nameserver setup but only for the `berlinoffice.com`
|
||||
You can select as many distribution groups as you want for your nameserver setup. Keep in mind to link them to peers and, if required, to add access control rules when using private nameservers.
|
||||
### Adding remote private DNS servers
|
||||
To add a private DNS server that is running behind routing peers, you need to create resources to ensure communication between your nameserver clients can communicate. In the Berlin office example from previous steps, we have a peer from the `Office network` that can route traffic to the `192.168.0.32` IP, so we need to ensure that a similar network route exists:
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-nameserver-remote-route.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-nameserver-remote-route.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Then we need to confirm that an access rule exists to connect `Remote developers` to `Office network` group:
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-nameserver-remote-rule.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-nameserver-remote-rule.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
## Testing configuration
|
||||
@@ -3,9 +3,9 @@
|
||||
NetBird allows administrators to restrict access to resources (peers) by creating access rules and
|
||||
defining what peer groups are permitted to establish connections with one another.
|
||||
|
||||
<div class="videowrapper">
|
||||
<div className="videowrapper">
|
||||
|
||||
<iframe src="https://www.youtube.com/embed/WvbkACjdsHA" allow="fullscreen;" width="800" height="500" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}></iframe>
|
||||
<iframe src="https://www.youtube.com/embed/WvbkACjdsHA" allow="accelerometer; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen;" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}}></iframe>
|
||||
|
||||
</div>
|
||||
|
||||
@@ -30,7 +30,7 @@ Some characteristics of groups:
|
||||
- There is a default group called `All`.
|
||||
|
||||
<Note>
|
||||
You can assign groups automatically with the [peer auto-grouping feature](/overview/setup-keys#peer-auto-grouping).
|
||||
You can assign groups automatically with the [peer auto-grouping feature](/how-to/register-machines-using-setup-keys#peer-auto-grouping).
|
||||
</Note>
|
||||
|
||||
### The All Group
|
||||
@@ -68,19 +68,19 @@ There is a `Default` rule, which configures a Default mesh connection between al
|
||||
After accessing the `Access Control` tab, you can click on the `Add Rule` button to create a new rule. This will open a screen
|
||||
where you need to name the rule, set its status, and add groups to the source and destination lists.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/create-rule.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/create-rule.png" alt="high-level-dia" width="300" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
If required, you can create new groups by simply entering new names in the input box for either source or destination lists.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/create-group-in-rule.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/create-group-in-rule.png" alt="high-level-dia" width="300" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Once you are done configuring the rule, click the `Create` button to save it. You will then see your new rule in the table.
|
||||
<p align="center">
|
||||
<img src="/img/overview/new-rule-list.png" alt="high-level-dia" width="600" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/new-rule-list.png" alt="high-level-dia" width="600" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
@@ -91,12 +91,12 @@ Once you are done configuring the rule, click the `Create` button to save it. Yo
|
||||
If you create a new group when defining a rule, you will need to associate peers with this group.
|
||||
You can do it by accessing the `Peers` tab and clicking the `Groups` column of any peer you want to associate with the new group.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/associate-peer-groups.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/associate-peer-groups.png" alt="high-level-dia" width="300" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
You can assign groups automatically with the [peer auto-grouping feature](/overview/setup-keys#peer-auto-grouping).
|
||||
You can assign groups automatically with the [peer auto-grouping feature](/how-to/register-machines-using-setup-keys#peer-auto-grouping).
|
||||
</Note>
|
||||
|
||||
### Updating Rules
|
||||
@@ -107,10 +107,10 @@ To disable a rule, you should follow the steps of [updating rules](#updating-rul
|
||||
### Deleting Rules
|
||||
To delete a rule, you should click on the rule's menu and choose `Delete`. A confirmation window will pop up.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/delete-rule-menu.png" alt="high-level-dia" width="600" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/delete-rule-menu.png" alt="high-level-dia" width="600" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/overview/delete-rule-popup.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/overview/delete-rule-popup.png" alt="high-level-dia" width="300" className="imagewrapper"/>
|
||||
</p>
|
||||
@@ -4,11 +4,13 @@
|
||||
The activity monitoring feature lets you quickly see what's happening with your network.
|
||||
Whether a new machine or user joined your network or the access control policy has been modified, the activity log allows you to track the changes to your network.
|
||||
|
||||
## Access activity monitoring view
|
||||
|
||||
Activity monitoring is enabled by default for every network, and you can access it in the web UI under the [Activity tab](https://app.netbird.io/activity).
|
||||
You can also use the search bar to filter events by activity type.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/activity-monitoring.png" alt="activity-monitoring" width="800" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/activity-monitoring.png" alt="activity-monitoring" width="800" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
@@ -23,8 +23,8 @@ Setup keys are available in the NetBird Management dashboard under the Setup Key
|
||||
|
||||
By default, we generate 2 setup keys right after account creation. You can easily add new or revoke keys.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/setup-keys.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/architecture/setup-keys.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
@@ -36,11 +36,11 @@ Setup keys are set to expire after 30 days. When expired, the setup key can't be
|
||||
|
||||
## Peer Auto-grouping
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/peer-auto-tagging-setupkey.gif" alt="high-level-dia" width="800" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/architecture/peer-auto-tagging-setupkey.gif" alt="high-level-dia" width="800" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
NetBird offers a powerful [Access Control feature](/docs/how-to/restrict-access-to-peers) that allows easy access management of your resources.
|
||||
NetBird offers a powerful [access control feature](/how-to/manage-network-access) that allows easy access management of your resources.
|
||||
In a basic scenario, you would create multiple groups of peers and create access rules to define what groups can access each other.
|
||||
Adding peers to groups might become time-consuming in large networks with dozens of machines.
|
||||
|
||||
@@ -51,8 +51,8 @@ to these groups. All the access control rules enabled for these groups will appl
|
||||
To add `Auto-assign groups`, open the `Setup Keys` tab and create or update any existing setup key.
|
||||
Then use this key to enroll new machine.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/architecture/netbird-peer-auto-tagging-newkey.png" alt="high-level-dia" width="500" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/architecture/netbird-peer-auto-tagging-newkey.png" alt="high-level-dia" width="500" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
@@ -1,7 +1,7 @@
|
||||
|
||||
# Routing traffic to private networks
|
||||
|
||||
<div class="videowrapper">
|
||||
<div className="videowrapper">
|
||||
<iframe src="https://www.youtube.com/embed/VQuPuBOAknQ" allow="fullscreen;"></iframe>
|
||||
</div>
|
||||
<br/><br/>
|
||||
@@ -14,8 +14,8 @@ NetBird provides fast and reliable end-to-end encryption between peers in your n
|
||||
|
||||
In these cases, you can configure network routes assigning routing peers to connect existing infrastructure. Routing peers will forward packets between your NetBird peers and your other networks; they can masquerade traffic going to your data centers or embedded devices, reducing the need for external route configuration and agent installation.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-network-routes.png" alt="high-level-dia" />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-network-routes.png" alt="high-level-dia" />
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
@@ -59,8 +59,8 @@ A network route describes a network you want to connect with your NetBird peers.
|
||||
### Creating a network route
|
||||
Access the `Network Routes` tab and click the `Add Route` button to create a new route.
|
||||
That will open a route configuration screen where you can add the information about the network you want to route:
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-network-routes-add-button.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-network-routes-add-button.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Now you can enter the details of your route.
|
||||
@@ -72,13 +72,13 @@ In the example below, we are creating a route with the following information:
|
||||
- Routing peer: `aws-nb-europe-router-az-a`
|
||||
- Distribution Groups: `All`
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-network-routes-create.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-network-routes-create.png" alt="high-level-dia" width="300" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Once you fill in the route information, you can click on the `Save` button to save your new route.
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-network-routes-saved-new.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-network-routes-saved-new.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
Done! Now every peer connected to your routing peer will be able to send traffic to your external network.
|
||||
|
||||
@@ -92,14 +92,14 @@ To enable high-available mode, you can click on `Configure` and select a new pee
|
||||
|
||||
In the following screenshot, we are adding the peer `aws-nb-europe-router-az-b` to the `aws-eu-central-1-vpc` route:
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-network-routes-create-ha.png" alt="high-level-dia" width="300" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-network-routes-create-ha.png" alt="high-level-dia" width="300" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
This way, nodes connected to both peer `aws-nb-europe-router-az-a` and peer `aws-nb-europe-router-az-b` would have a highly available connection with the network `172.31.0.0/16`.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-network-routes-saved-new-ha.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-network-routes-saved-new-ha.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
@@ -115,8 +115,8 @@ In this case, the routing peer won't hide any NetBird peer IP and will forward
|
||||
That will require a routing configuration on your external network router pointing your NetBird network back to your routing peer.
|
||||
This way, devices that don't have the agent installed can communicate with your NetBird peers.
|
||||
|
||||
<p align="center">
|
||||
<img src="/img/how-to-guides/netbird-network-routes-masquerading.png" alt="high-level-dia" style={{boxShadow: '0 4px 8px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19)'}} />
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-network-routes-masquerading.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
## Get started
|
||||
@@ -5,13 +5,13 @@ import {AboutNetbird} from "@/components/AboutNetbird"
|
||||
export const description =
|
||||
'Learn everything there is to know about NetBird.'
|
||||
|
||||
# NetBird Docs
|
||||
# Introduction to NetBird
|
||||
|
||||
NetBird is a simple and fast alternative to corporate VPNs built on top of [WireGuard®](https://www.wireguard.com/) making it easy to create secure private networks for your organization or home.
|
||||
It requires near zero configuration effort leaving behind the hassle of opening ports, complex firewall rules, vpn gateways, and so forth. {{ className: 'lead' }}
|
||||
|
||||
<Note>
|
||||
NetBird is an **open-source** project.
|
||||
NetBird is an **open-source** project and can be self-hosted
|
||||
</Note>
|
||||
|
||||
There is no centralized VPN server with NetBird - your computers, devices, machines, and servers connect to each other directly over a fast encrypted tunnel.
|
||||
@@ -19,10 +19,12 @@ NetBird can connect machines running anywhere in just a few clicks.
|
||||
It literally takes less than 5 minutes to deploy a secure peer-to-peer VPN with NetBird. {{ className: 'lead' }}
|
||||
|
||||
<div className="not-prose mb-16 mt-6 flex gap-3">
|
||||
<Button href="/docs/how-to/getting-started" arrow="right" children="Getting started" />
|
||||
<Button href="/how-to/getting-started" arrow="right" children="Getting started" />
|
||||
<Button href="https://github.com/netbirdio/netbird" variant="outline" children="Explore Github" />
|
||||
</div>
|
||||
|
||||
<AboutNetbird />
|
||||
|
||||
<HowToGuides />
|
||||
|
||||
<AboutNetbird />
|
||||
|
||||
@@ -3,7 +3,7 @@ export const description =
|
||||
|
||||
# Authentication
|
||||
|
||||
You'll need to authenticate your requests to access any of the endpoints in the NetBird API. In this guide, we'll look at how authentication works. Netbird offers two ways to authenticate your API requests: OAuth2 and personal access tokens (PAT). {{ className: 'lead' }}
|
||||
You'll need to authenticate your requests to access any of the endpoints in the NetBird API. In this guide, we'll look at how authentication works. NetBird offers two ways to authenticate your API requests: OAuth2 and personal access tokens (PAT). {{ className: 'lead' }}
|
||||
|
||||
## OAuth2 with bearer token
|
||||
|
||||
@@ -18,7 +18,7 @@ Always keep your token safe and reset it if you suspect it has been compromised.
|
||||
|
||||
## Using personal access tokens
|
||||
|
||||
When establishing a connection using [PATs](/docs/how-to/use-service-users-with-access-token#personal-access-tokens), you will need your access token — you can create one in the [Netbird dashboard](https://app.netbird.io/users) under User settings. It is recommended to use [service users](/docs/how-to/use-service-users-with-access-token#service-users) for all organization wide flows calling the API. Here's how to add the token to the request header using cURL:
|
||||
When establishing a connection using [PATs](/how-to/access-netbird-public-api), you will need your access token — you can create one in the [NetBird dashboard](https://app.netbird.io/users) under User settings. It is recommended to use [service users](/how-to/access-netbird-public-api) for all organization wide flows calling the API. Here's how to add the token to the request header using cURL:
|
||||
|
||||
```bash {{ title: 'Example request with personal access token' }}
|
||||
curl https://api.netbird.io/api/users \
|
||||
@@ -28,6 +28,6 @@ curl https://api.netbird.io/api/users \
|
||||
Always keep your token safe and reset it if you suspect it has been compromised.
|
||||
|
||||
<div className="not-prose mb-16 mt-6 flex gap-3">
|
||||
<Button href="/docs/how-netbird-works#personal-access-tokens" arrow="right" children="How to create tokens" />
|
||||
<Button href="/how-to/access-netbird-public-api#creating-an-access-token" arrow="right" children="How to create tokens" />
|
||||
</div>
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ For this guide, we'll be using cURL to make our first API request. If you don't
|
||||
|
||||
## Get an access token
|
||||
|
||||
Before making your first API request, you need to create an access token to authenticate requests to the API. You can create an access token in the [Netbird dashboard](https://app.netbird.io) under [Users » Me](https://app.netbird.io/users).
|
||||
Before making your first API request, you need to create an access token to authenticate requests to the API. You can create an access token in the [NetBird dashboard](https://app.netbird.io) under [Users » Me](https://app.netbird.io/users).
|
||||
After the token was created successfully make sure to store it as we need it for the next step.
|
||||
|
||||
## Making your first API request
|
||||
@@ -31,7 +31,7 @@ curl -X GET https://api.netbird.io/api/peers \
|
||||
|
||||
<div className="not-prose">
|
||||
<Button
|
||||
href="/peers"
|
||||
href="/api/resources/peers"
|
||||
variant="text"
|
||||
arrow="right"
|
||||
children="Read the docs for the peers endpoint"
|
||||
@@ -43,6 +43,6 @@ curl -X GET https://api.netbird.io/api/peers \
|
||||
|
||||
Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further into the NetBird API:
|
||||
|
||||
- [Read how to properly authenticate against the NetBird API](/authentication)
|
||||
- [Check out the users endpoint](/users)
|
||||
- [Learn about the different error types](/errors)
|
||||
- [Read how to properly authenticate against the NetBird API](/api/guides/authentication)
|
||||
- [Check out the users endpoint](/api/resources/users)
|
||||
- [Learn about the different error types](/api/guides/errors)
|
||||
|
||||
@@ -9,17 +9,17 @@ export const description =
|
||||
Use the NetBird Public API to manage users, peers, network rules and more from inside your application or scripts to automate the setup of your mesh network. {{ className: 'lead' }}
|
||||
|
||||
<div className="not-prose mb-16 mt-6 flex gap-3">
|
||||
<Button href="/ipa/guides/quickstart" arrow="right" children="Quickstart" />
|
||||
<Button href="/api/guides/quickstart" arrow="right" children="Quickstart" />
|
||||
</div>
|
||||
|
||||
## Getting started {{ anchor: false }}
|
||||
|
||||
To get started, it is recommended to create a [service user](/docs/how-to/use-service-users-with-access-token#service-users), that can later be used to communicate with the NetBird API.
|
||||
To be able to send requests to our API you need to [authenticate](/ipa/guides/authentication) on each request. This can be done either by Bearer token from your identity provider or by creating a [personal access token](/docs/how-to/use-service-users-with-access-token#personal-access-tokens) in the NetBird dashboard.{{ className: 'lead' }}
|
||||
To get started, it is recommended to create a [service user](/how-to/access-netbird-public-api#creating-a-service-user), that can later be used to communicate with the NetBird API.
|
||||
To be able to send requests to our API you need to [authenticate](/api/guides/authentication) on each request. This can be done either by Bearer token from your identity provider or by creating a [personal access token](/api/guides/authentication#using-personal-access-tokens) in the NetBird dashboard.{{ className: 'lead' }}
|
||||
|
||||
<div className="not-prose">
|
||||
<Button
|
||||
href="/docs/how-netbird-works#personal-access-tokens"
|
||||
href="/how-to/access-netbird-public-api#creating-an-access-token"
|
||||
variant="text"
|
||||
arrow="right"
|
||||
children="Get your personal access token"
|
||||
@@ -10,7 +10,7 @@ There are a few Identity Provider options that you can choose to run a self-host
|
||||
|
||||
## Auth0
|
||||
|
||||
This guide is a part of the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide) and explains how to integrate **self-hosted** NetBird with [Auth0](https://auth0.com/).
|
||||
This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) 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)
|
||||
@@ -61,8 +61,8 @@ This Auth0 API will be used to access NetBird Management Service API.
|
||||
|
||||
### Step 4: Enable Interactive SSO Login (Optional)
|
||||
|
||||
The [Interactive SSO Login feature](/getting-started/installation#running-netbird-with-sso-login) allows for machine
|
||||
authorization with your Identity Provider. This feature can be used as an alternative to [setup keys](docs/how-to/register-peers-using-setup-keys)
|
||||
The [Interactive SSO Login feature](/how-to/installation#running-net-bird-with-sso-login) allows for machine
|
||||
authorization with your Identity Provider. This feature can be used as an alternative to [setup keys](/how-to/register-machines-using-setup-keys)
|
||||
and is optional.
|
||||
|
||||
You can enable it by following these steps:
|
||||
@@ -74,26 +74,32 @@ You can enable it by following these steps:
|
||||
- Application type: `Native`
|
||||
- Click `Create`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/auth0-create-interactive-login-app.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Click `Settings` tab
|
||||
- Copy **`Client ID`** to `NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID` in the `setup.env` file
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/auth0-interactive-login-settings.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Scroll down to the `Advanced Settings` section
|
||||
- Enable **`Device Code`**
|
||||
- Click `Save Changes`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/auth0-grant-types.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
|
||||
### Step 4: Continue with the self-hosting guide
|
||||
You can now continue with the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide#step-3-configure-identity-provider).
|
||||
You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-3-configure-identity-provider).
|
||||
|
||||
## Keycloak
|
||||
|
||||
This guide is a part of the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide) and explains how to integrate
|
||||
This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate
|
||||
**self-hosted** NetBird with [Keycloak](https://www.keycloak.org/).
|
||||
|
||||
Keycloak is an open source software product to allow single sign-on with Identity and Access Management aimed at modern applications and services.
|
||||
@@ -109,10 +115,12 @@ The following guide is an adapted version of the original
|
||||
### Expected Result
|
||||
|
||||
After completing this guide, you can log in to your self-hosted NetBird Dashboard and add your machines
|
||||
to your network using the [Interactive SSO Login feature](/docs/how-to/getting-started#running-net-bird-with-sso-login)
|
||||
to your network using the [Interactive SSO Login feature](/how-to/getting-started#running-net-bird-with-sso-login)
|
||||
over Keycloak.
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-auth-grant.gif" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Step 1: Check your Keycloak Instance
|
||||
|
||||
@@ -133,8 +141,11 @@ To create a realm you need to:
|
||||
- Fill in the form with the following values:
|
||||
- Realm name: `netbird`
|
||||
- Click `Create`
|
||||
-
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-create-realm.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
|
||||
### Step 3: Create a user
|
||||
|
||||
@@ -148,7 +159,9 @@ In this step we will create a NetBird administrator user.
|
||||
- Username: `netbird`
|
||||
- Click `Create`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-create-user.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
The user will need an initial password set to be able to log in. To do this:
|
||||
- Click `Credentials` tab
|
||||
@@ -157,7 +170,9 @@ The user will need an initial password set to be able to log in. To do this:
|
||||
- Set the `Temporary` field to `Off` to prevent having to update password on first login
|
||||
- Click `Save`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-set-password.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Step 4: Create a NetBird client
|
||||
|
||||
@@ -172,11 +187,16 @@ In this step we will create NetBird application client and register with the Key
|
||||
- Client ID: `netbird-client`
|
||||
- Your newly client `netbird-client` will be used later to set `NETBIRD_AUTH_CLIENT_ID` in the `setup.env`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-create-client.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
|
||||
- Check the checkboxes as on the screenshot below and click Save
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-enable-auth.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Step 5: Adjust NetBird client access settings
|
||||
|
||||
@@ -194,7 +214,9 @@ In this step we will configure NetBird application client access with the NetBir
|
||||
- Web origins: `+`
|
||||
- Click `Save`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-access-settings.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Step 6: Create a NetBird client scope
|
||||
|
||||
@@ -210,13 +232,17 @@ In this step, we will create and configure the NetBird client audience for Keycl
|
||||
- Protocol: `OpenID Connect`
|
||||
- Click `Save`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-create-client-scope.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- While in the newly created Client Scope, switch to the `Mappers` tab
|
||||
- Click `Configure a new mapper`
|
||||
- Choose the `Audience` mapping
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-configure-audience-mapper.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Fill in the form with the following values:
|
||||
- Name: `Audience for NetBird Management API`
|
||||
@@ -224,7 +250,9 @@ In this step, we will create and configure the NetBird client audience for Keycl
|
||||
- Add to access token: `On`
|
||||
- Click `Save`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-configure-audience-mapper-2.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Step 7: Add client scope to NetBird client
|
||||
|
||||
@@ -238,7 +266,9 @@ In this step, we will create and configure the NetBird client audience for Keycl
|
||||
- Click `Add` choosing `Default`
|
||||
- The value `netbird-client` will be used as audience
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloack-add-client-scope.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Step 8: Create a NetBird-Backend client
|
||||
|
||||
@@ -253,17 +283,23 @@ In this step we will create NetBird backend client and register with the Keycloa
|
||||
- Client ID: `netbird-backend`
|
||||
- Your newly client `netbird-backend` will be used later to set `KeycloakClientCredentials` in the `management.json`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-create-backend-client.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Check the checkboxes as on the screenshot below and click Save
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-backend-client-auth.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
The client will need secret to authenticate. To do this:
|
||||
- Click `Credentials` tab
|
||||
- Copy `client secret` will be used later to set `ClientSecret` in the `management.json`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-backend-client-credentials.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Step 9: Add manage-users role to netbird-backend
|
||||
|
||||
@@ -275,11 +311,15 @@ The client will need secret to authenticate. To do this:
|
||||
- Click `Assign roles` button
|
||||
- Select `Filter by clients` and search for `manage-users`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-service-account-role.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Check the role checkbox and click assign
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/keycloak-add-role.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Your authority OIDC configuration will be available under:
|
||||
```
|
||||
@@ -294,9 +334,9 @@ https://<YOUR-KEYCLOAK-HOST-AND-PORT>/realms/netbird/.well-known/openid-configur
|
||||
- NETBIRD_AUTH_CLIENT_ID=`netbird-client`
|
||||
- NETBIRD_AUTH_AUDIENCE=`netbird-client`
|
||||
- NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID=`netbird-client`. Optional,
|
||||
it enables the [Interactive SSO Login feature](/docs/how-to/getting-started#running-net-bird-with-sso-login) (Oauth 2.0 Device Authorization Flow)
|
||||
it enables the [Interactive SSO Login feature](/how-to/getting-started#running-net-bird-with-sso-login) (Oauth 2.0 Device Authorization Flow)
|
||||
|
||||
- You can now continue with the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide#step-3-configure-identity-provider).
|
||||
- You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-3-configure-identity-provider).
|
||||
|
||||
- Set property `IdpManagerConfig` in the `management.json` file with:
|
||||
<Note>
|
||||
@@ -322,7 +362,7 @@ it enables the [Interactive SSO Login feature](/docs/how-to/getting-started#runn
|
||||
|
||||
## Azure AD
|
||||
|
||||
This guide is a part of the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide) and explains how to integrate **self-hosted** NetBird with [Azure AD](https://azure.microsoft.com/en-us/products/active-directory/).
|
||||
This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate **self-hosted** NetBird with [Azure AD](https://azure.microsoft.com/en-us/products/active-directory/).
|
||||
|
||||
Azure AD is a an enterprise identity service that provides single sign-on and multifactor authentication to your applications.
|
||||
It is a 3rd party managed service and can't be self-hosted.
|
||||
@@ -338,8 +378,8 @@ Before you start creating and configuring an Azure AD application, ensure that y
|
||||
- User account with appropriate permissions: You must have an Azure AD user account with the appropriate permissions to create and manage Azure AD applications. If you don't have the required permissions, ask your Azure AD administrator to grant them to you.
|
||||
|
||||
|
||||
### 1. Create and configure Azure AD application
|
||||
In this step, we will create and configure Netbird application in azure AD.
|
||||
### Step 1. Create and configure Azure AD application
|
||||
In this step, we will create and configure NetBird application in azure AD.
|
||||
- Navigate to [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview)
|
||||
- Click `App Registrations` in the left menu then click on the `+ New registration` button to create a new application.
|
||||
- Fill in the form with the following values and click Register
|
||||
@@ -347,46 +387,61 @@ In this step, we will create and configure Netbird application in azure AD.
|
||||
- Account Types: `Accounts in this organizational directory only (Default Directory only - Single tenant)`
|
||||
- Redirect URI: select `Single-page application (SPA)` and URI as `https://<yournetbirddomain.com>/silent-auth`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/azure-new-application.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### 2. Platform configurations
|
||||
### Step 2. Platform configurations
|
||||
- Click `Authentication` on the left side menu
|
||||
- Under the `Single-page application` Section, add another URI `https://<yournetbirddomain.com>/auth`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/azure-spa-uri-setup.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Scroll down and setup other options as on the screenshot below and click Save
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/azure-flows-setup.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### 3. Create a NetBird application scope
|
||||
### Step 3. Create a NetBird application scope
|
||||
- Click `Expose an API` on the left menu
|
||||
- Under `Application ID URI` click `Set` and then `Save`
|
||||
- Click `+ Add a Scope`
|
||||
- Fill in the form with the following values and click `Add scope`
|
||||
- Scope name: `api`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/azure-add-scope.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Under `Authorized client Applications`, click on `+ add a client application` and enter the following:
|
||||
- Fill in the form with the following values and click `Add application`
|
||||
- Client ID: same as your Application ID URI minus the `api://`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/azure-add-application-scope.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
|
||||
### 4. Add API permissions
|
||||
### Step 4. Add API permissions
|
||||
- Add `Netbird` permissions
|
||||
- Click `API permissions` on the left menu
|
||||
- Click `Add a permission`
|
||||
- Click `My APIs` tab, and select `Netbird`. Next check `api` permission checkbox and click `Add permissions`.
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/azure-netbird-api-permisssions.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Add `Delagated permissions` to Microsoft Graph
|
||||
- Click `Add a permission`
|
||||
- Click `Microsoft Graph` and then click `Delagated permissions` tab and check all permissions under the `OpenId permissions` section and click `Add permissions`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/azure-openid-permissions.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
|
||||
- Add `Application permissions` to Microsoft Graph
|
||||
@@ -394,29 +449,37 @@ In this step, we will create and configure Netbird application in azure AD.
|
||||
- Click `Microsoft Graph` and then click `Application permissions` tab
|
||||
- Search for `User.ReadWrite.All` and under `User` sections and check `User.ReadWrite.All` checkbox section
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/azure-user-permissions.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Search for `Application.ReadWrite.All` and under `Application` sections and check `Application.ReadWrite.All` checkbox section and click `Add permissions`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/azure-applications-permissions.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Click `Grant admin conset for Default Directory` and click `Yes`
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/azure-grant-admin-conset.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### 4. Update token version
|
||||
### Step 5. Update token version
|
||||
- Click `Manifest` on left menu
|
||||
- Search for `accessTokenAcceptedVersion` and change the value from `null` to `2`
|
||||
- Click `Save`
|
||||
|
||||
### 5. Generate client secret
|
||||
### Step 6. Generate client secret
|
||||
- Click `Certificates & secrets` on left menu
|
||||
- Click `New client secret`
|
||||
- Fill in the form with the following values and click `Add`
|
||||
- Description: `Netbird`
|
||||
- Copy `Value` and save it as it can be viewed only once after creation.
|
||||
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/azure-client-secret.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Your authority OIDC configuration will be available under:
|
||||
```
|
||||
@@ -438,7 +501,7 @@ NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
|
||||
NETBIRD_AUTH_USER_ID_CLAIM="oid"
|
||||
```
|
||||
|
||||
- You can now continue with the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide#step-3-configure-identity-provider/docs/selfhosted/selfhosted-guide#step-3-configure-identity-provider).
|
||||
- You can now continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-3-configure-identity-provider/selfhosted/selfhosted-guide#step-3-configure-identity-provider).
|
||||
|
||||
- Set property `IdpManagerConfig` in the `management.json` file with:
|
||||
<Note>
|
||||
@@ -463,6 +526,307 @@ NETBIRD_AUTH_USER_ID_CLAIM="oid"
|
||||
|
||||
- Modify `Scope` value in `DeviceAuthorizationFlow` within the `management.json` to `api://<application_id>/api`.
|
||||
|
||||
## Zitadel
|
||||
|
||||
This guide is a part of the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide) and explains how to integrate
|
||||
**self-hosted** NetBird with [Zitadel](https://zitadel.com).
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</Note>
|
||||
|
||||
### Step 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`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/zitadel-new-project.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
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`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/zitadel-new-application.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Fill in the form with the following values and click `Continue`
|
||||
- Authentication Method: `PKCE`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/zitadel-new-application-auth.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- 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 `+`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/zitadel-new-application-uri.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Verify applications details and Click `Create` and then click `Close`
|
||||
- Check `Refresh Token` checkbox and click `Save`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/zitadel-new-application-overview.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- 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`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/zitadel-token-settings.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### 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`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/zitadel-redirect-settings.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### 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`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/zitadel-create-user.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
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`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/zitadel-service-user-secret.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### 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`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/zitadel-service-account-role.png" alt="high-level-dia" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
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](/selfhosted/selfhosted-guide#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](/selfhosted/selfhosted-guide#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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Authentik
|
||||
|
||||
This guide is a part of the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide) and explains how to integrate
|
||||
**self-hosted** NetBird with [Authentik](https://goauthentik.io).
|
||||
|
||||
<Note>
|
||||
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).
|
||||
</Note>
|
||||
|
||||
### Step 1: Create OAuth2/OpenID Provider
|
||||
In this step, we will create OAuth2/OpenID Provider in Authentik.
|
||||
|
||||
- Navigate to authentik admin interface
|
||||
- Click `Applications` on the left menu, then click `Providers`
|
||||
- Click `Create` to create new provider
|
||||
- Fill in the form with the following values and click `Next`
|
||||
- type: `OAuth2/OpenID Provider`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/authentik-new-provider-type.png" alt="high-level-dia" class="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Fill in the form with the following values and click `Finish`
|
||||
- Name: `Netbird`
|
||||
- Authentication Flow: `default-authentication-flow (Welcome to authentik!)`
|
||||
- Authorization Flow: `default-provider-authorization-explicit-consent (Authorize Application)`
|
||||
- Protocal Settings:
|
||||
- Client type: `Public`
|
||||
- Redirect URIs/Origins (RegEx): `*`
|
||||
- Advanced protocol settings:
|
||||
- Subject mode: `Based on the User's ID`
|
||||
|
||||
Take note of `Client ID`, we will use it later
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/authentik-new-provider-config.png" alt="high-level-dia" class="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Step 2: Create external applications
|
||||
In this step, we will create external applications in Authentik.
|
||||
|
||||
- Navigate to authentik admin interface
|
||||
- Click `Applications` on the left menu, then click `Applications`
|
||||
- Click `Create` to create new application
|
||||
- Fill in the form with the following values and click `Create`
|
||||
- Name: `Netbird`
|
||||
- Slug: `netbird`
|
||||
- Provider: `Netbird`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/authentik-new-application.png" alt="high-level-dia" class="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Step 3: Create service account
|
||||
In this step, we will create service account.
|
||||
|
||||
- Navigate to authentik admin interface
|
||||
- Click `Directory` on the left menu, then click `Users`
|
||||
- Click `Create Service Account` to create service account
|
||||
- Fill in the form with the following values and click `Create`
|
||||
- Username: `Netbird`
|
||||
- Create Group: `Disable`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/authentik-new-service-account.png" alt="high-level-dia" class="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
- Take note of service account `username` and `password`, we will need it later
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/authentik-service-account-details.png" alt="high-level-dia" class="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### Step 4: Add service account to admin group
|
||||
In this step, we will add `Netbird` service account to `authentik Admins` group.
|
||||
|
||||
- Navigate to authentik admin interface
|
||||
- Click `Directory` on the left menu, then click `Groups`
|
||||
- Click `authentik Admins` from list of groups and select `Users` tab at the top
|
||||
- Click `Add existing user` and click `+` button to add user
|
||||
- Select `Netbird` and click `Add`
|
||||
- Disable `Hide service-accounts` and verify if user `Netbird` is added to the group
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/integrations/identity-providers/self-hosted/authentik-add-user-group.png" alt="high-level-dia" class="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Your authority OIDC configuration will be available under:
|
||||
```
|
||||
https://< YOUR-AUTHENTIK-HOST-AND-PORT >/application/o/netbird/.well-known/openid-configuration
|
||||
```
|
||||
<Note>
|
||||
Double-check if the endpoint returns a JSON response by calling it from your browser.
|
||||
</Note>
|
||||
|
||||
- Set properties in the `setup.env` file:
|
||||
```json
|
||||
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR-AUTHENTIK-HOST-AND-PORT>/application/o/netbird/.well-known/openid-configuration"
|
||||
NETBIRD_USE_AUTH0=false
|
||||
NETBIRD_AUTH_CLIENT_ID="<PROVIDER Client ID>"
|
||||
NETBIRD_AUTH_AUDIENCE="<PROVIDER Client ID>"
|
||||
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<PROVIDER Client ID>"
|
||||
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="<PROVIDER Client ID>"
|
||||
```
|
||||
|
||||
- You can now continue with the [NetBird Self-hosting Guide](/docs/selfhosted/selfhosted-guide#step-3-configure-identity-provider).
|
||||
|
||||
- Set property `IdpManagerConfig` in the `management.json` file with:
|
||||
<Note>
|
||||
The file management.json is created automatically. Please refer [here](/docs/selfhosted/selfhosted-guide#step-5-run-configuration-script) for more information.
|
||||
</Note>
|
||||
|
||||
```json
|
||||
{
|
||||
"ManagerType": "authentik",
|
||||
"ClientConfig": {
|
||||
"Issuer": "https://<YOUR-AUTHENTIK-HOST-AND-PORT>",
|
||||
"ClientID": "<PROVIDER Client ID>",
|
||||
"TokenEndpoint": "https://<YOUR-AUTHENTIK-HOST-AND-PORT>/application/o/token",
|
||||
"GrantType": "client_credentials"
|
||||
},
|
||||
"ExtraConfig": {
|
||||
"Username": "Netbird",
|
||||
"Password": "<SERVICE ACCOUNT PASSWORD>",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Okta
|
||||
|
||||
This guide is a part of the [NetBird Self-hosting Guide](/getting-started/self-hosting) and explains how to integrate
|
||||
@@ -483,7 +847,7 @@ In this step, we will create and configure Netbird single-page application in ok
|
||||
- Sign-in method: `OIDC - OpenID Connect`
|
||||
- Application type: `Single-Page Application`
|
||||
|
||||
|
||||
|
||||
|
||||
- Fill in the form with the following values and click `Save`
|
||||
- App integration name: `Netbird`
|
||||
@@ -492,7 +856,7 @@ In this step, we will create and configure Netbird single-page application in ok
|
||||
- Sign-out redirect URIs: `https://<yournetbirddomain.com>/`
|
||||
- Click `Save`
|
||||
|
||||
|
||||
|
||||
|
||||
- Navigate to Okta Admin Dashboard
|
||||
- Click `Applications` in the left menu and then click on `Applications`
|
||||
@@ -501,7 +865,7 @@ In this step, we will create and configure Netbird single-page application in ok
|
||||
- Under `OpenID Connect ID Token` section, click `Edit` and update `Issuer` to use the `Okta URL`
|
||||
- Click `Save`
|
||||
|
||||
|
||||
|
||||
|
||||
### Step 2. Create and configure Okta native application
|
||||
In this step, we will create and configure Netbird native application in okta.
|
||||
@@ -512,7 +876,7 @@ In this step, we will create and configure Netbird native application in okta.
|
||||
- Sign-in method: `OIDC - OpenID Connect`
|
||||
- Application type: `Native Application`
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
- Fill in the form with the following values and click `Save`
|
||||
@@ -520,7 +884,7 @@ In this step, we will create and configure Netbird native application in okta.
|
||||
- Grant type: `Device Authorization`
|
||||
- Click `Save`
|
||||
|
||||
|
||||
|
||||
|
||||
- Navigate to Okta Admin Dashboard
|
||||
- Click `Applications` in the left menu and then click on `Applications`
|
||||
@@ -529,7 +893,7 @@ In this step, we will create and configure Netbird native application in okta.
|
||||
- Under `OpenID Connect ID Token` section, click `Edit` and update `Issuer` to use the `Okta URL`
|
||||
- Click `Save`
|
||||
|
||||
|
||||
|
||||
|
||||
### Step 3. Generate api token
|
||||
In this step, we will generate netbird api token in okta for authorizing calls to user api.
|
||||
@@ -542,7 +906,7 @@ In this step, we will generate netbird api token in okta for authorizing calls t
|
||||
- Name: `Netbird`
|
||||
- Take note of token value and click `OK, got it`
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Your authority OIDC configuration will be available under:
|
||||
@@ -581,7 +945,12 @@ NETBIRD_AUTH_DEVICE_AUTH_USE_ID_TOKEN=true
|
||||
```json
|
||||
{
|
||||
"ManagerType": "okta",
|
||||
"OktaClientCredentials": {
|
||||
"ClientConfig": {
|
||||
"Issuer": "<ISSUER_URL>",
|
||||
"TokenEndpoint": "<ISSUER_URL>/oauth2/v1/token",
|
||||
"GrantType": "client_credentials"
|
||||
},
|
||||
"ExtraConfig": {
|
||||
"APIToken": "<api_token>",
|
||||
}
|
||||
}
|
||||
@@ -6,7 +6,7 @@ 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 an identity provider (available options will be listed later in this guide).
|
||||
|
||||
If you would like to learn more about the architecture please refer to the [Architecture section](/overview/architecture).
|
||||
If you would like to learn more about the architecture please refer to the [Architecture section](/about-netbird/how-netbird-works).
|
||||
|
||||
<Note>
|
||||
It might be a good idea to try NetBird before self-hosting.
|
||||
Reference in New Issue
Block a user