mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-20 01:16:36 +00:00
Move IdP Sync to a separate page (#215)
This commit is contained in:
Misha Bragin
@@ -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.
|
||||
|
||||
<Note>
|
||||
This feature is only available in the cloud version of NetBird.
|
||||
</Note>
|
||||
|
||||
### 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`
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/google-service-account-create.png" alt="service-account-create" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
#### 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
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/google-edit-service-account.png" alt="edit-service-account" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
- 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`
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/google-new-admin-role.png" alt="new-admin-role" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
- Scroll down to `Admin API privileges` and add the following privileges
|
||||
- Users: `Read`
|
||||
- Groups: `Read`
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/google-privileges-review.png" alt="privileges-review" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
- 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`
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/google-assign-service-account.png" alt="assign-service-account" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
- Click `ASSIGN ROLE` to assign service account to `User and Group Management ReadOnly` admin role
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/google-service-account-privileges.png" alt="service-account-privileges" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
- 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`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/azure-new-application.png" alt="azure-new-application" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
|
||||
#### 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`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/azure-openid-permissions.png" alt="azure-openid-permissions" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
- Click `Grant admin consent for Default Directory` and click `Yes`
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/azure-grant-admin-consent.png" alt="azure-grant-admin-consent" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
#### 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.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/azure-client-secret.png" alt="azure-client-secret" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
- 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`.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/okta-sso-configuration.png" alt="Okta SSO Configuration" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
##### 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`.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-idp-list.png" alt="NetBird Identity Provider List" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
- Follow the displayed instructions to link your Okta account. Ensure to note the `Authorization(Bearer) token` generated for use in the subsequent step.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/okta-scim-credentials.png" alt="Okta SCIM Credentials" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
##### 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`
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/okta-provisioning.png" alt="Okta Provisioning Configuration" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
- Opt to `Enable API integration` and insert previously noted `Authorization(Bearer) token` into the `API Token` field.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/okta-provisioning-enabled.png" alt="Enabling Okta Provisioning" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
- 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`.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/okta-to-app-configuration.png" alt="Okta to App Configuration" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
##### 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.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/okta-assign-users-by-group.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
#### Step 5. Sync groups to NetBird
|
||||
- Access the `Push Groups` tab
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/okta-push-groups.png" alt="high-level-dia" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
- 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.
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
## Supported Identity Providers
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/supported-identity-providers.png" alt="supported-identity-providers"
|
||||
className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
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)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user