mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-21 18:06:38 +00:00
Improve okta sync
This commit is contained in:
braginini
@@ -1,107 +1,220 @@
|
||||
import {
|
||||
Note
|
||||
} from "@/components/mdx";
|
||||
|
||||
# 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.
|
||||
Okta is a cloud-based identity and access management (IAM) platform that centralizes user and customer profiles to enhance
|
||||
security and streamline access. It offers features like multifactor authentication, single sign-on, and lifecycle
|
||||
management to help organizations manage user identities effectively.
|
||||
|
||||
Like with [other IdPs](/how-to/idp-sync), 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.
|
||||
NetBird's Okta integration enhances user management by allowing you to utilize Okta as your identity provider.
|
||||
This integration automates user authentication in your network, adds SSO and MFA support, and simplifies network access management
|
||||
to your applications and resources.
|
||||
|
||||
The integration process consists of two stages: first, you’ll set up OpenID Connect (OIDC) to enable Single Sign-On (SSO)
|
||||
from NetBird's login page using Okta credentials. Next, you’ll configure SCIM (System for Cross-domain Identity Management)
|
||||
to synchronize users and groups smoothly.
|
||||
|
||||
## 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 `Okta` 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.
|
||||
|
||||
|
||||
|
||||
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
|
||||
To set up SSO, go to `Integrations` in the NetBird admin console's left menu to access the Identity Provider integration page. Click the `Connect Okta` button to get started with the Okta-NetBird integration. This will open a pop-up window with detailed instructions on synchronizing NetBird and Okta.
|
||||
|
||||
|
||||
##### 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.
|
||||
## Prerequisites
|
||||
|
||||
#### 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`.
|
||||
Before you begin the integration process, ensure you have the [necessary permissions in Okta](https://help.okta.com/en-us/content/topics/security/administrators-admin-comparison.htm). You need an Okta user account with one of the following roles:
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/okta-sso-configuration.png" alt="Okta SSO Configuration" className="imagewrapper-big"/>
|
||||
</p>
|
||||
* Super Admin
|
||||
* Org Admin
|
||||
* Group Admin
|
||||
|
||||
##### 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`.
|
||||
To check your user permissions in Okta:
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/how-to-guides/netbird-idp-list.png" alt="NetBird Identity Provider List" className="imagewrapper-big"/>
|
||||
</p>
|
||||
* Log in to your Okta **admin** dashboard.
|
||||
* Expand `People` in the left menu.
|
||||
* Select your user.
|
||||
* Navigate to the `Admin roles` tab.
|
||||
|
||||
- Follow the displayed instructions to link your Okta account. Ensure to note the `Authorization(Bearer) token` generated for use in the subsequent step.
|
||||
Confirm that you have one of the required roles before proceeding with the integration.
|
||||
|
||||
<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>
|
||||
## Installing the NetBird Integration
|
||||
|
||||
- Opt to `Enable API integration` and insert previously noted `Authorization(Bearer) token` into the `API Token` field.
|
||||
Once you have the necessary permissions, you can set up the NetBird application. First, on NetBird, click `Continue →` to show a summary of the necessary steps.
|
||||
|
||||
<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>
|
||||
Let's go through them one by one:
|
||||
|
||||
##### 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.
|
||||
* In Okta’s admin dashboard, click `Applications` in the left menu.
|
||||
* Select `Applications` from the submenu.
|
||||
* Click the `Browse App Catalog` button.
|
||||
|
||||
<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.
|
||||
In the app catalog, enter "NetBird" in the search bar. Then, click the `Add Integration` button.
|
||||
|
||||
|
||||
|
||||
|
||||
Accept the default application name and click the `Done` button. On the next screen, click the `Assign` dropdown and select `Assign to People`.
|
||||
|
||||
|
||||
|
||||
|
||||
You will see a list of users. Find your user account, click `Assign`, and save the changes. Verify your user is assigned to the NetBird app and click `Done`.
|
||||
|
||||
|
||||
|
||||
|
||||
After that, you will see your user listed in the NetBird application.
|
||||
|
||||
|
||||
|
||||
|
||||
## Configuring SSO in Okta
|
||||
|
||||
The next step is to configure Okta-NetBird SSO integration.
|
||||
|
||||
In NetBird, click the `Continue →` button. A new wizard screen will appear, offering the instructions for retrieving Okta’s OpenID Connect credentials. You can click `Close` and navigate to Okta.
|
||||
|
||||
|
||||
|
||||
|
||||
* Click on the `Sign On` tab on Okta. Look for `OpenID Connect` under `Sign on methods` in the `Settings` section.
|
||||
* Copy the `Client ID` value.
|
||||
* Copy the `Client Secret` value.
|
||||
|
||||
Store these credentials securely, as you will need them soon.
|
||||
|
||||
|
||||
|
||||
|
||||
* Click `Edit` in the `Settings` section.
|
||||
* In `Credential Details`, change the `Application username format` from `Okta username` to `Email`.
|
||||
* Click the `Save` button
|
||||
|
||||
|
||||
|
||||
* On the top right, click on your username
|
||||
* Copy your [Okta account domain](https://developer.okta.com/docs/guides/find-your-domain/main/) as shown below:
|
||||
|
||||
|
||||
|
||||
The final step is to [send an email to the NetBird team](support@netbird.io) with the authentication information you just retrieved:
|
||||
|
||||
* Okta `Client ID`
|
||||
* Okta `Client secret`
|
||||
* Okta account domain
|
||||
* Okta primary email domain (usually your username)
|
||||
|
||||
You will receive an email once the NetBird team enables authentication for your account.
|
||||
|
||||
This completes the first stage, enabling Single Sign-On (SSO) from NetBird's login page using Okta credentials. Now, you can navigate to [app.netbird.io](app.netbird.io) and log in using [Okta Verify](https://help.okta.com/eu/en-us/content/topics/end-user/ov-overview.htm).
|
||||
|
||||
## Enabling Okta SCIM in NetBird
|
||||
|
||||
In NetBird, go to `Integrations > Identity Provider` and click on the `Connect to Okta` button.
|
||||
|
||||
|
||||
|
||||
You will see a reminder of the permissions your user will require in Okta. Click the `Get Started →` button to continue.
|
||||
|
||||
|
||||
|
||||
If you haven't already, you'll need to set up SSO in Okta. If you've completed the previous section, skip this step and click the `Continue →` button.
|
||||
|
||||
|
||||
|
||||
The next screen will show you how to enable NetBird API credentials in Okta. Copy the value of the `Authorization (Bearer)` token.
|
||||
|
||||
|
||||
|
||||
Navigate to the NetBird app in your Okta admin dashboard. Click the `Provisioning` tab, then select `Configure API Integration`.
|
||||
|
||||
|
||||
|
||||
Follow these steps:
|
||||
|
||||
* Check the box to enable API Integration.
|
||||
* Enter your NetBird API Token.
|
||||
* Click `Test API Credentials` to verify the SCIM connection.
|
||||
|
||||
|
||||
|
||||
If everything works as expected, you'll see the message: "NetBird was verified successfully!" as shown below. Click `Save` to continue.
|
||||
|
||||
|
||||
|
||||
## Configuring SCIM Provisioning to NetBird
|
||||
|
||||
On NetBird, click `Continue →`. You'll see instructions for configuring SCIM provisioning to NetBird.
|
||||
|
||||
|
||||
|
||||
Back to Okta, click `Edit` as shown below.
|
||||
|
||||
|
||||
|
||||
Enable Okta to create, update, and deactivate NetBird users by checking the corresponding boxes:
|
||||
|
||||
* Create Users
|
||||
* Update User Attibutes
|
||||
* Deactivate Users
|
||||
|
||||
When done, click `Save`.
|
||||
|
||||
|
||||
|
||||
## Assigning NetBird Application to Okta Groups
|
||||
|
||||
In NetBird, click `Continue →`, you'll see the steps for assigning the NetBird integration to Okta groups.
|
||||
|
||||
|
||||
|
||||
* Navigate to the `Assignments` tab.
|
||||
* Similar than before when you assigned your user to NetBird app, click the `Assign` button
|
||||
* This time, select `Assign to Groups`.
|
||||
* Select Okta groups that you want to assign to the NetBird app.
|
||||
|
||||
|
||||
|
||||
Once you assign the desired groups, click `Done`. You'll see the selected groups listed in Okta.
|
||||
|
||||
|
||||
|
||||
## Push Okta Groups to NetBird
|
||||
|
||||
One more time, go to NetBird and click `Continue →`. You'll see the final instructions to push Okta groups to NetBird.
|
||||
|
||||
|
||||
|
||||
* In Okta, navigate to `Push Groups` tab
|
||||
* Click the `Push Groups` buttom
|
||||
* Select `Find groups by name`
|
||||
* Search for specific groups to push to NetBird.
|
||||
|
||||
|
||||
|
||||
Once you finish, go back to NetBird and click `Finish Setup`. You can verify the syncronization by navigating to `Team > Users`
|
||||
|
||||
|
||||
|
||||
The users listed in NetBird should match those you created in Okta.
|
||||
|
||||
|
||||
|
||||
<Note>
|
||||
SCIM provisioning will manage only resources that are created through Okta. Any resources created directly in
|
||||
NetBird will not be managed by SCIM.
|
||||
SCIM provisioning will manage only resources that are created through Okta. Any resources created directly in NetBird will not be managed by SCIM.
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Synced groups will only be available for membership and will not change the role of user in NetBird.
|
||||
Synced groups will only be available for membership and will not change the role of user in NetBird
|
||||
</Note>
|
||||
|
||||
Reference in New Issue
Block a user