diff --git a/public/docs-static/img/how-to-guides/idp-sync-reference.png b/public/docs-static/img/how-to-guides/idp-sync-reference.png new file mode 100644 index 00000000..50d75c4d Binary files /dev/null and b/public/docs-static/img/how-to-guides/idp-sync-reference.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/0A98Xm9.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/0A98Xm9.png new file mode 100644 index 00000000..a1e06f72 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/0A98Xm9.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/1t8qbfK.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/1t8qbfK.png new file mode 100644 index 00000000..919fbd36 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/1t8qbfK.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/6yiGCtY.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/6yiGCtY.png new file mode 100644 index 00000000..ad66c213 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/6yiGCtY.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/7WYZMW6.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/7WYZMW6.png new file mode 100644 index 00000000..8f08acc9 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/7WYZMW6.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/DH5hxFK.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/DH5hxFK.png new file mode 100644 index 00000000..150be793 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/DH5hxFK.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/FkdC8BV.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/FkdC8BV.png new file mode 100644 index 00000000..4eb76d33 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/FkdC8BV.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/KHGbhqe.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/KHGbhqe.png new file mode 100644 index 00000000..606766e7 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/KHGbhqe.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/LimVmGI.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/LimVmGI.png new file mode 100644 index 00000000..234f7e83 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/LimVmGI.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/OGWQWVH.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/OGWQWVH.png new file mode 100644 index 00000000..4fd00c6b Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/OGWQWVH.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/Qy9lDMF.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/Qy9lDMF.png new file mode 100644 index 00000000..17a8a015 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/Qy9lDMF.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/V0aRf7f.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/V0aRf7f.png new file mode 100644 index 00000000..436379ae Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/V0aRf7f.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/WIercn5.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/WIercn5.png new file mode 100644 index 00000000..66f79d93 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/WIercn5.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/XDl3b7u.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/XDl3b7u.png new file mode 100644 index 00000000..f2b4a47c Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/XDl3b7u.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/Yxxktk6.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/Yxxktk6.png new file mode 100644 index 00000000..e1c7f73c Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/Yxxktk6.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/bHb8HVZ.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/bHb8HVZ.png new file mode 100644 index 00000000..e6d6a6f1 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/bHb8HVZ.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/bpwW1Bn.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/bpwW1Bn.png new file mode 100644 index 00000000..b6a2e58a Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/bpwW1Bn.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/lDyaAeV.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/lDyaAeV.png new file mode 100644 index 00000000..391075fa Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/lDyaAeV.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/oI0Pjai.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/oI0Pjai.png new file mode 100644 index 00000000..67d693e2 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/oI0Pjai.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/qlNlfgV.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/qlNlfgV.png new file mode 100644 index 00000000..78ce1c7a Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/qlNlfgV.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/tP7WqXO.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/tP7WqXO.png new file mode 100644 index 00000000..5d7b582f Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/tP7WqXO.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/xvLskEg.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/xvLskEg.png new file mode 100644 index 00000000..299dd367 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/xvLskEg.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/xyLPzxH.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/xyLPzxH.png new file mode 100644 index 00000000..0988ad46 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/xyLPzxH.png differ diff --git a/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/zSkSGAm.png b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/zSkSGAm.png new file mode 100644 index 00000000..c4fb24f3 Binary files /dev/null and b/public/docs-static/img/how-to-guides/microsoft-entra-id-sync/zSkSGAm.png differ diff --git a/public/docs-static/img/how-to-guides/supported-identity-providers.png b/public/docs-static/img/how-to-guides/supported-identity-providers.png new file mode 100644 index 00000000..0d8c1e38 Binary files /dev/null and b/public/docs-static/img/how-to-guides/supported-identity-providers.png differ diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 0266a952..61426eed 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -54,7 +54,7 @@ export const docsNavigation = [ title: 'Access Control', isOpen: false, links: [ - { title: 'Manage Network Access', href: '/how-to/manage-network-access' }, + { title: 'Groups & Policies', href: '/how-to/manage-network-access' }, { title: 'Posture Checks', href: '/how-to/manage-posture-checks' }, ] }, @@ -79,7 +79,16 @@ export const docsNavigation = [ isOpen: false, links: [ { title: 'Add users to your network', href: '/how-to/add-users-to-your-network' }, - + { + title: 'Provision Users & Groups from Identity Provider', + href: '/how-to/provision-users-and-groups-from-idp', + isOpen: false, + links: [ + { title: 'Microsoft Entra ID', href: '/how-to/microsoft-entra-id-sync' }, + { title: 'Okta', href: '/how-to/okta-sync' }, + { title: 'Google Workspace', href: '/how-to/google-workspace-sync'}, + ] + }, ] }, { diff --git a/src/pages/how-to/add-users-to-your-network.mdx b/src/pages/how-to/add-users-to-your-network.mdx index c09adb0e..575b1602 100644 --- a/src/pages/how-to/add-users-to-your-network.mdx +++ b/src/pages/how-to/add-users-to-your-network.mdx @@ -4,7 +4,7 @@ Whether you have a network for personal use or manage your company's corporate network, you'd probably want to invite people to your account and join your NetBird network. -There are two ways of adding users to a NetBird account - indirect and direct. +There are three ways of adding users to a NetBird account - indirect, direct, and via IdP (Identity Provider) sync. ## Indirect user invites This way of adding users is managed by the NetBird system and doesn't require administrator input. @@ -47,6 +47,18 @@ After logging in to the system, they will join your network automatically. This is a limitation that is likely to be removed in future versions. +## Identity Provider (IdP) Sync + +NetBird's IdP-Sync automates user access management by integrating with your IdP and automatically +provisioning users and groups. You can enable this feature from the `Users` tab by clicking the `Identity Provider Sync` +button. + +

+ idp-sync-reference +

+ +See the [Provision Users and Groups From Your Identity Provider](/how-to/provision-users-and-groups-from-idp) section for more details. + ## Manage user roles NetBird has three user roles - `Owner`, `Admin`, and `User`. The roles allow you to control the level of access to the management API of your account. diff --git a/src/pages/how-to/google-workspace-sync.mdx b/src/pages/how-to/google-workspace-sync.mdx new file mode 100644 index 00000000..2beb7406 --- /dev/null +++ b/src/pages/how-to/google-workspace-sync.mdx @@ -0,0 +1,83 @@ +# Provision Users and Groups From Google Workspace + +[Google Workspace Identity](https://cloud.google.com/architecture/identity/overview-google-authentication) +is the system within Google Workspace that manages user authentication and access, +ensuring secure login and integration with other identity providers for Single Sign-On (SSO) and multi-factor authentication. + +NetBird's Google Workspace integration allows you to synchronize users and groups from Google Workspace to NetBird and +automate network access management. With this integration, any changes to users and groups in Google Workspace are mirrored in NetBird, +granting new employees network access while immediately revoking access for former employees. + +## Get Started with NetBird-Google Workspace Integration + +To begin, go to [Integrations](https://app.netbird.io/integrations) from the left-hand menu, which will direct you to the `Identity Provider` section. +Select the `Google Workspace` option. A pop-up window will appear, launching an intuitive wizard that will lead you through the steps to synchronize +NetBird with Google Workspace. + +![NetBird Get Started IdP](/docs-static/img/how-to-guides/microsoft-entra-id-sync/FkdC8BV.png) + +## Prerequisites + +Before you start creating and configuring an Google Workspace application, ensure that you have the following: +- User account with admin permissions: You must have an Google Workspace user account with the admin permissions to create and manage Google Workspace applications. If you don't have the required permissions, ask your workspace administrator to grant them to you. +- Create new `NetBird` project in Google cloud console https://console.cloud.google.com. +- Enable `Admin SDK API` for `Netbird` project at https://console.cloud.google.com/apis/library/admin.googleapis.com. + +## Create a Service Account +- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page +- Click `CREATE CREDENTIALS` at the top and select `Service account` +- Fill in the form with the following values and click `CREATE` +- Service account name: `NetBird` +- Service account ID: `netbird` +- Click `DONE` +

+ service-account-create +

+ +## Create Service Account Keys +- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page +- Under `Service Accounts` click the `NetBird` to edit the service account +

+ edit-service-account +

+ +- Take note of service account email address, you will use it in next steps +- Click the `Keys` tab +- Click the `Add key` drop-down menu, then select `Create new key` +- Select `JSON` as the Key type and click `Create` + +>When you create a service account key by using the Google Cloud console, most browsers immediately download the new key and save it in a download folder on your computer. +Read how to manage and secure your service keys [here](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys#temp-locations) + +## Grant a User Management Admin Role to a Service Account +- Navigate to [Admin Console](https://admin.google.com/ac/home) page +- Select `Account` on the left menu and then click `Admin Roles` +- Click `Create new role` +- Fill in the form with the following values and click `CREATE` +- name: `User and Group Management ReadOnly` +- description: `User and Group Management ReadOnly` +- Click `CONTINUE` +

+ new-admin-role +

+ +- Scroll down to `Admin API privileges` and add the following privileges +- Users: `Read` +- Groups: `Read` +

+ privileges-review +

+ +- Verify preview of assigned Admin API privileges to ensure that everything is properly configured, and then click `CREATE ROLE` + +- Click `Assign service accounts`, add service account email address and then click `ADD` +

+ assign-service-account +

+ +- Click `ASSIGN ROLE` to assign service account to `User and Group Management ReadOnly` admin role +

+ service-account-privileges +

+ +- Navigate to [Account Settings](https://admin.google.com/ac/accountsettings/profile?hl=en_US) page and take note of `Customer ID` \ No newline at end of file diff --git a/src/pages/how-to/idp-sync.mdx b/src/pages/how-to/idp-sync.mdx index e564cf74..c07583a5 100644 --- a/src/pages/how-to/idp-sync.mdx +++ b/src/pages/how-to/idp-sync.mdx @@ -1,219 +1,37 @@ -export const title = 'Identity Provider synchronization' +# Provision Users and Groups From Your Identity Provider -## Identity Provider synchronization +Managing user access to a private network in a business environment is a critical yet often cumbersome task. +As companies grow and evolve, the manual process of granting network access for new employees and revoking it for +departing ones becomes increasingly time-consuming and error-prone. This challenge strains IT resources, poses significant +security risks, and impacts productivity. -Welcome to our comprehensive guide on configuring Identity Provider (IdP) for users and groups synchronization. This document provides step-by-step instructions and best practices for setting up and managing your synchronization processes effectively. +NetBird's IdP-Sync automates user access management by integrating with your identity provider (IdP) and automatically +provisioning users and groups. This integration ensures that changes to groups and users are +synchronized from your identity provider to NetBird, granting appropriate network access to new users and immediately revoking access for +departing employees. + +NetBird allows you to use synchronized groups to create [access policies](/how-to/manage-network-access#creating-policies), +or update network configurations like [DNS](/how-to/manage-dns-in-your-network#distribution-groups), +eliminating the need for manual grouping. - This feature is only available in the cloud version of NetBird. - - -### Google WorkSpace - -Before you start creating and configuring an Google Workspace application, ensure that you have the following: -- User account with admin permissions: You must have an Google Workspace user account with the admin permissions to create and manage Google Workspace applications. If you don't have the required permissions, ask your workspace administrator to grant them to you. -- Create new `NetBird` project in Google cloud console https://console.cloud.google.com. -- Enable `Admin SDK API` for `Netbird` project at https://console.cloud.google.com/apis/library/admin.googleapis.com. - -#### Step 1: Create a service account -- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page -- Click `CREATE CREDENTIALS` at the top and select `Service account` -- Fill in the form with the following values and click `CREATE` - - Service account name: `NetBird` - - Service account ID: `netbird` -- Click `DONE` -

- service-account-create -

- -#### Step 2: Create service account keys -- Navigate to [API Credentials](https://console.cloud.google.com/apis/credentials) page -- Under `Service Accounts` click the `NetBird` to edit the service account -

- edit-service-account -

- -- Take note of service account email address, you will use it in next steps -- Click the `Keys` tab -- Click the `Add key` drop-down menu, then select `Create new key` -- Select `JSON` as the Key type and click `Create` - ->When you create a service account key by using the Google Cloud console, most browsers immediately download the new key and save it in a download folder on your computer. -Read how to manage and secure your service keys [here](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys#temp-locations) - -#### Step 3: Grant a user management admin role to a service account -- Navigate to [Admin Console](https://admin.google.com/ac/home) page -- Select `Account` on the left menu and then click `Admin Roles` -- Click `Create new role` -- Fill in the form with the following values and click `CREATE` - - name: `User and Group Management ReadOnly` - - description: `User and Group Management ReadOnly` -- Click `CONTINUE` -

- new-admin-role -

- -- Scroll down to `Admin API privileges` and add the following privileges - - Users: `Read` - - Groups: `Read` -

- privileges-review -

- -- Verify preview of assigned Admin API privileges to ensure that everything is properly configured, and then click `CREATE ROLE` - -- Click `Assign service accounts`, add service account email address and then click `ADD` -

- assign-service-account -

- -- Click `ASSIGN ROLE` to assign service account to `User and Group Management ReadOnly` admin role -

- service-account-privileges -

- -- Navigate to [Account Settings](https://admin.google.com/ac/accountsettings/profile?hl=en_US) page and take note of `Customer ID` - - -### Azure AD - -Before you start creating and configuring an Azure AD application, ensure that you have the following: -- User account with admin 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. - -#### Step 1. Create and configure Azure AD application -- 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` - - Name: `NetBird` - -

- azure-new-application -

- - -#### Step 2. Add API permissions - -- Click `API permissions` on the left menu -- Click `Add a permission` -- Click `Microsoft Graph` and then click `Application permissions` tab -- In `Select permissions` select `User.Read.All` and `Group.Read.All` and click `Add permissions` - -

- azure-openid-permissions -

- -- Click `Grant admin consent for Default Directory` and click `Yes` - -

- azure-grant-admin-consent -

- -#### Step 3. 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. - -

- azure-client-secret -

- -- Navigate to [Owner applications](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps). -- Select `NetBird` application in overview page, take note of `Application (client) ID` and `Directory (tenant) ID`. - - -### Okta - -If your organization relies on Okta for managing employee access, automating access to NetBird via Okta's `Provisioning` feature can streamline your operations. This integration leverages `SCIM` (System for Cross-domain Identity Management) to ensure smooth synchronization of users and groups. For comprehensive insights into Okta's SCIM capabilities, please consult this [article](https://www.okta.com/blog/2017/01/what-is-scim/). - -#### Prerequisites -- Begin by installing the NetBird application from the [Okta Integration Network](https://www.okta.com/integrations/netbird) -- Following installation, reach out to support to activate Okta SSO for your [support](mailto:support@netbird.io). - -#### Supported Features - - -##### OIDC Features -- **SP-initiated SSO (Single Sign-On)**: Users must start authentication from NetBird's [login page](https://app.netbird.io/) -by entering their Okta email and clicking `Continue`. - -##### SCIM Features -- **Create Users**: Users added through Okta will automatically be created in NetBird. -- **Update User Attributes**: Any changes to user attributes in Okta will be synchronized with NetBird. -- **Deactivate Users**: Deactivating a user in Okta will also deactivate them in NetBird. -- **Group Push**: Groups created in Okta will be synchronized to NetBird. - -#### Configuration Steps -##### Step 1: Configure SSO in Okta -- Access the Okta dashboard and navigate to `Applications > Applications`, selecting the previously installed `NetBird` application. -- Go to `Sign On > Settings` and select `Edit`. -- In the `Credentials Details` section, change the `Application username format` to `Email` and select `Save`. - -

- Okta SSO Configuration -

- -##### Step 2: Enable Okta SCIM in NetBird -- Log into [NetBird](https://app.netbird.io/). -- Proceed to [Integrations > Identity Provider](https://app.netbird.io/integrations?tab=identity-provider) and select `Connect Okta`. - -

- NetBird Identity Provider List -

- -- Follow the displayed instructions to link your Okta account. Ensure to note the `Authorization(Bearer) token` generated for use in the subsequent step. - -

- Okta SCIM Credentials -

- -##### Step 3: Enable Provisioning in Okta - -- From the Okta dashboard, navigate to `Applications > Applications` and select the `NetBird` application. -- Under the` Provisioning` tab, choose `Integration`, then select `Configure API Integration` -

- Okta Provisioning Configuration -

- -- Opt to `Enable API integration` and insert previously noted `Authorization(Bearer) token` into the `API Token` field. - -

- Enabling Okta Provisioning -

- -- Click `Test API Credentials` to verify the SCIM connection, then select `Save`. -- Navigate to `Provisioning > Settings > To App`, click `Edit`, enable `Create Users`, `Update User Attributes`, and `Deactivate Users`, then select `Save`. - -

- Okta to App Configuration -

- -##### Step 4: Sync Users to NetBird -- Access the `Assignments` tab, click `Assign`, then `Assign to Groups`. -- Choose the groups for provisioning, select `Assign` and then `Save and Go Back`. -- Click `Done` to conclude the group assignment process. - -

- high-level-dia -

- -#### Step 5. Sync groups to NetBird -- Access the `Push Groups` tab -

- high-level-dia -

- -- Select the `Push Groups` and then `Find groups by name` -- Search groups to push and then click `Save` -- The selected groups will then be synced to NetBird. - - - SCIM provisioning will manage only resources that are created through Okta. Any resources created directly in - NetBird will not be managed by SCIM. + NetBird's IdP-Sync is available from the Team plan and above. - Synced groups will only be available for membership and will not change the role of user in NetBird. + This feature is not available in the self-hosted version of NetBird. +## Supported Identity Providers + +

+ supported-identity-providers +

+ +NetBird provides native support for syncing with the most popular identify providers. +For detailed setup and configuration steps, select an IdP from the section below: + +* [Entra ID (Azure AD)](/how-to/microsoft-entra-id-sync) +* [Okta](/how-to/okta-sync) +* [Google Workspace](/how-to/google-workspace-sync) + diff --git a/src/pages/how-to/manage-network-access.mdx b/src/pages/how-to/manage-network-access.mdx index aaf8c2bc..a24eb391 100644 --- a/src/pages/how-to/manage-network-access.mdx +++ b/src/pages/how-to/manage-network-access.mdx @@ -1,6 +1,10 @@ -# Manage network access -NetBird enables administrators to oversee and manage access between resources (peers) through access policies. These policies specify which peers and peer groups are permitted to connect to each other, detail the protocols and ports for these connections, and offer the option to include posture checks to apply zero trust principles, helping to adapt access control to specific contexts. +# Managing Access with NetBird: Groups and Access Policies +NetBird empowers administrators to effectively manage and control access between resources (referred to as peers) using groups and access policies. +These access policies define which peers or peer groups are allowed to connect, specify the protocols and ports available +for these connections, and optionally incorporate posture checks. By integrating posture checks, NetBird enforces +zero-trust principles, enabling dynamic and context-aware access control that adapts to the specific security needs of +your environment. Watch our Access Control video on YouTube: diff --git a/src/pages/how-to/microsoft-entra-id-sync.mdx b/src/pages/how-to/microsoft-entra-id-sync.mdx new file mode 100644 index 00000000..6658540e --- /dev/null +++ b/src/pages/how-to/microsoft-entra-id-sync.mdx @@ -0,0 +1,184 @@ +# Provision Users and Groups From Microsoft Entra ID + +[Microsoft Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id), +formerly known as Azure Active Directory (Azure AD), is a cloud-based identity and access management service that +provide secure authentication, single sign-on, and user management capabilities for organizations. + +NetBird's Microsoft Entra ID integration allows you to synchronize users and groups from Entra ID to NetBird. +You can then use these synchronized groups to create access policies, configure network, and automate onboarding and offboarding processes. + +## Get Started with NetBird-Entra ID Integration + +To get started, navigate to [Integrations](https://app.netbird.io/integrations) in the left menu, which will take you to the +`Identity Provider` integration. Click the `Enter ID (Azure AD)` button. This action will trigger a pop-up window that will +present you with a user-friendly wizard, guiding you through the synchronization process between NetBird and Azure AD. + +![NetBird Get Started IdP](/docs-static/img/how-to-guides/microsoft-entra-id-sync/FkdC8BV.png) + +## Prerequisites + +Before starting the integration process, verify that you have the required permissions in Microsoft Entra ID (Azure AD). +Specifically, you will need an Azure user account with at least one of these roles: + +* Application Administrator +* Cloud Application Administrator +* Global Administrator + +To check your permissions: + +* Log in to the [Azure portal](portal.azure.com). +* Navigate to Manage Microsoft Entra ID and click `View`. +* Expand the `Manage` tab and click on `Roles and administrators` in the left menu. +* Look for your username and verify if you're assigned any of the above roles. + +![EntraID Roles](/docs-static/img/how-to-guides/microsoft-entra-id-sync/lDyaAeV.png) + +If you don't have the required permissions, contact your Azure AD administrator to grant you the appropriate role before proceeding with the NetBird integration. + +## Create and Configure a Microsoft Entra ID Application for NetBird Integration + +Now that you have the required permissions, return to the NetBird dashboard. Click on the `Get Started` button to initiate the integration process. + +A new wizard screen will appear, offering step-by-step instructions for creating and configuring your Microsoft Entra ID application. To simplify the process, the wizard also provides quick-copy buttons for essential information: + +* Name +* Account Type +* Redirect Type +* Redirect URI + +![NetBird Create Application](/docs-static/img/how-to-guides/microsoft-entra-id-sync/oI0Pjai.png) + +For convenience, click on [Azure Active Directory](https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/Overview) (step 1). That will open the Azure dashboard. Navigate to `App registrations` in the left menu and then click `+New registration` as indicated below: + +![EntraID App Registration](/docs-static/img/how-to-guides/microsoft-entra-id-sync/Yxxktk6.png) + +Fill in the required information: + +![EntraID Register an App](/docs-static/img/how-to-guides/microsoft-entra-id-sync/1t8qbfK.png) + +After entering all required information, click the `Register` button at the bottom of the form to finalize the application registration process. + +Upon successful registration, you'll be redirected to a confirmation screen similar to the following: + +![EntraID App Registered](/docs-static/img/how-to-guides/microsoft-entra-id-sync/7WYZMW6.png) + +Copy and securely store the generated `Application (client) ID` and `Directory (tenant) ID` as you will need them shortly. + +## Configure API Permissions for NetBird-Entra ID Integration + +On the NetBird dashboard click the `Continue →` button. A new wizard screen will appear, this time, offering step-by-step instructions for setting up API permissions. + +![NetBird Add API Permissions](/docs-static/img/how-to-guides/microsoft-entra-id-sync/0A98Xm9.png) + +Back to Azure, in the `App registrations` screen, click on `Manage` in the left menu to expand it and then click on `API permissions`: + +![EntraID API Permissions](/docs-static/img/how-to-guides/microsoft-entra-id-sync/V0aRf7f.png) + +Look for the `+ Add a permission` button, located near the top of the permissions list and click on it. + +![EntraID API Permissions Screen](/docs-static/img/how-to-guides/microsoft-entra-id-sync/Qy9lDMF.png) + +A new pop-up window will appear, asking you to select an API. Click on `Microsoft Graph`. + +![EntraID Microsoft Graph](/docs-static/img/how-to-guides/microsoft-entra-id-sync/tP7WqXO.png) + +On the next screen, click on the `Application permissions` button, which will let you select the appropriate permissions for NetBird to function correctly with your Microsoft Entra ID environment. + +![EntraID Request API Permissions](/docs-static/img/how-to-guides/microsoft-entra-id-sync/zSkSGAm.png) + +To assign user permissions: + +* Locate the search bar at the top. Type `User.Read.All` into the search bar and press `Enter`. +* In the search results, click on the `User` tab to expand it and view the available permissions. +* Click on the checkbox to select and enable the `User.Read.All` permission. + +![EntraID UserReadAll](/docs-static/img/how-to-guides/microsoft-entra-id-sync/KHGbhqe.png) + +The `User.Read.All` permission allows NetBird to read the full set of profile properties, group memberships, and reports of the signed-in user and other users in your organization. + +Next, repeat the procedure. This time, search for `Group.Read.All` and click on the checkbox to enable it as shown below: + +![EntraID GroupReadAll](/docs-static/img/how-to-guides/microsoft-entra-id-sync/XDl3b7u.png) + +Once done, click the `Add permissions` button. You will see a few warnings: + +![EntraID API Permissions Warnings](/docs-static/img/how-to-guides/microsoft-entra-id-sync/OGWQWVH.png) + +Locate the `Grant admin consent for [Your Organization Name]` button (you’ll find it next to `+Add a permission` button). Click on it to grant the required permissions. + +A confirmation dialog will appear, asking you to verify this action. Review the permissions listed in the dialog and click `Yes` to confirm. Wait for the process to complete, this may take a few seconds. + +Once finished, the status of the permissions should change to `Granted for [Your Organization Name]`. Verify that all selected permissions now show a green checkmark, indicating they've been successfully granted: + +![EntraID API Permissions Granted](/docs-static/img/how-to-guides/microsoft-entra-id-sync/bHb8HVZ.png) + +## Create a Client Secret for Secure NetBird-Entra ID Authentication + +Back to the NetBird dashboard, click the `Continue →` button. A new wizard screen will appear, showing instructions for generating a client secret in Entra ID. + +![NetBird Generate Client Secret](/docs-static/img/how-to-guides/microsoft-entra-id-sync/xvLskEg.png) + +On Azure, click on the `Certificates & secrets` button in the left menu to open the management page. Click on `+New client secret` as shown below. Choose an expiration time that suits your security needs and click the `Add` button. + +![EntraID Add a Client Secret](/docs-static/img/how-to-guides/microsoft-entra-id-sync/WIercn5.png) + +A new client secret will be generated and displayed on the screen. Copy and securely store the `Value` field immediately, as you will needed in the next step. + +![EntraID Client Secret Value](/docs-static/img/how-to-guides/microsoft-entra-id-sync/LimVmGI.png) + +## Enter Application ID and Directory ID in NetBird + +Paste the secret `Value` from the previous step into NetBird and click the `Continue →` button. A new wizard screen will appear, asking for the `Application (client) ID` and the `Directory (tenant) ID` credentials generated previously. + +Paste the values and click the `Continue →` button. + +![NetBird Application ID and Directory](/docs-static/img/how-to-guides/microsoft-entra-id-sync/6yiGCtY.png) + +## Choose Groups to Synchronize from Entra ID +At this stage, NetBird is set to synchronize all groups from your Microsoft Entra ID by default. You have two options: + +* If you want to synchronize all groups, simply click the `Continue →` button. +* To synchronize only specific groups, click the `+ Add group filter` button, which will open a new panel where you can set criteria to include or exclude groups. + +![NetBird Group Sync](/docs-static/img/how-to-guides/microsoft-entra-id-sync/xyLPzxH.png) + +## Choose Users to Synchronize from Entra ID +After configuring group synchronization, you'll now set up user synchronization. Similar than before, NetBird is configured to synchronize all users from your Microsoft Entra ID by default. + +* If you want to synchronize all users, you don't need to take any action, simply click the `Continue →` button. +* To synchronize only specific users, click the `+ Add user filter` button. This opens a new panel where you can set criteria to include or exclude users. + + + You can modify these synchronization settings later if necessary. + + +![NetBird Users Sync](/docs-static/img/how-to-guides/microsoft-entra-id-sync/bpwW1Bn.png) + +After configuring user and group synchronization, the setup wizard will finalize the process and you'll automatically return to the main Identity Provider screen. + +On this screen, you'll see two key indicators of successful integration: + +* The Microsoft Entra ID toggle will be switched on (enabled). +* Next to the toggle, you'll see a button with a status message saying `Synced a few seconds ago`. + +These indicators confirm that: + +* The integration between NetBird and Microsoft Entra ID is active. +* The initial synchronization has been completed successfully. +* NetBird will now automatically sync with your Microsoft Entra ID at regular intervals. + + + You can manually trigger a sync or adjust settings by clicking on the Microsoft Entra ID section in the Identity Provider screen + + +![NetBird Identity Provider Synchronized](/docs-static/img/how-to-guides/microsoft-entra-id-sync/DH5hxFK.png) + +## Verify the Integration + +To verify the synchronization, navigate to `Teams > Users` in the left menu. +You should see all the users and groups from your Microsoft Entra ID environment listed in the NetBird dashboard. + +![NetBird Checking Integration](/docs-static/img/how-to-guides/microsoft-entra-id-sync/qlNlfgV.png) + +You can now proceed to configure [access control policies](/how-to/manage-network-access#creating-policies) using the synchronized groups to allow or deny access to the +synchronized users. \ No newline at end of file diff --git a/src/pages/how-to/okta-sync.mdx b/src/pages/how-to/okta-sync.mdx new file mode 100644 index 00000000..ad654f5e --- /dev/null +++ b/src/pages/how-to/okta-sync.mdx @@ -0,0 +1,107 @@ +# Provision Users and Groups From Okta + +[Okta](https://www.okta.com/) is a cloud-based identity management service that enables organizations to manage user authentication, +authorization, and access across a wide range of applications and services. + +Like with [other IdPs](/how-to/provision-users-and-groups-from-idp), NetBird's IdP-Sync feature automates user access management by integrating with Okta and automatically +provisioning users and groups. This integration syncs changes from Okta to NetBird, ensuring that new users receive the +correct network access and that employees leaving the organization have their access immediately revoked. + +## Get Started with NetBird-Okta Integration + +To get started, navigate to [Integrations](https://app.netbird.io/integrations) in the left menu, which will take you to the `Identity Provider` integration. +Click the `Enter ID (Azure AD)` button. This action will trigger a pop-up window that will present you with a user-friendly +wizard, guiding you through the synchronization process between NetBird and Azure AD. + +![NetBird Get Started IdP](/docs-static/img/how-to-guides/microsoft-entra-id-sync/FkdC8BV.png) + +If your organization relies on Okta for managing employee access, automating access to NetBird via Okta's `Provisioning` feature can streamline your operations. This integration leverages `SCIM` (System for Cross-domain Identity Management) to ensure smooth synchronization of users and groups. For comprehensive insights into Okta's SCIM capabilities, please consult this [article](https://www.okta.com/blog/2017/01/what-is-scim/). + +#### Prerequisites +- Begin by installing the NetBird application from the [Okta Integration Network](https://www.okta.com/integrations/netbird) +- Following installation, reach out to support to activate Okta SSO for your [support](mailto:support@netbird.io). + +#### Supported Features + + +##### OIDC Features +- **SP-initiated SSO (Single Sign-On)**: Users must start authentication from NetBird's [login page](https://app.netbird.io/) +by entering their Okta email and clicking `Continue`. + +##### SCIM Features +- **Create Users**: Users added through Okta will automatically be created in NetBird. +- **Update User Attributes**: Any changes to user attributes in Okta will be synchronized with NetBird. +- **Deactivate Users**: Deactivating a user in Okta will also deactivate them in NetBird. +- **Group Push**: Groups created in Okta will be synchronized to NetBird. + +#### Configuration Steps +##### Step 1: Configure SSO in Okta +- Access the Okta dashboard and navigate to `Applications > Applications`, selecting the previously installed `NetBird` application. +- Go to `Sign On > Settings` and select `Edit`. +- In the `Credentials Details` section, change the `Application username format` to `Email` and select `Save`. + +

+ Okta SSO Configuration +

+ +##### Step 2: Enable Okta SCIM in NetBird +- Log into [NetBird](https://app.netbird.io/). +- Proceed to [Integrations > Identity Provider](https://app.netbird.io/integrations?tab=identity-provider) and select `Connect Okta`. + +

+ NetBird Identity Provider List +

+ +- Follow the displayed instructions to link your Okta account. Ensure to note the `Authorization(Bearer) token` generated for use in the subsequent step. + +

+ Okta SCIM Credentials +

+ +##### Step 3: Enable Provisioning in Okta + +- From the Okta dashboard, navigate to `Applications > Applications` and select the `NetBird` application. +- Under the` Provisioning` tab, choose `Integration`, then select `Configure API Integration` +

+ Okta Provisioning Configuration +

+ +- Opt to `Enable API integration` and insert previously noted `Authorization(Bearer) token` into the `API Token` field. + +

+ Enabling Okta Provisioning +

+ +- Click `Test API Credentials` to verify the SCIM connection, then select `Save`. +- Navigate to `Provisioning > Settings > To App`, click `Edit`, enable `Create Users`, `Update User Attributes`, and `Deactivate Users`, then select `Save`. + +

+ Okta to App Configuration +

+ +##### Step 4: Sync Users to NetBird +- Access the `Assignments` tab, click `Assign`, then `Assign to Groups`. +- Choose the groups for provisioning, select `Assign` and then `Save and Go Back`. +- Click `Done` to conclude the group assignment process. + +

+ high-level-dia +

+ +#### Step 5. Sync groups to NetBird +- Access the `Push Groups` tab +

+ high-level-dia +

+ +- Select the `Push Groups` and then `Find groups by name` +- Search groups to push and then click `Save` +- The selected groups will then be synced to NetBird. + + + SCIM provisioning will manage only resources that are created through Okta. Any resources created directly in + NetBird will not be managed by SCIM. + + + Synced groups will only be available for membership and will not change the role of user in NetBird. + \ No newline at end of file