Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
36 changes: 22 additions & 14 deletions src/pages/manage/team/idp-sync/okta-sync.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,7 @@ to synchronize users and groups smoothly.

## Get Started with NetBird-Okta Integration

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.

![The Okta card on the Identity Provider Sync tab with its Connect Okta button](/docs-static/img/manage/team/idp-sync/okta-sync/nwutb3Z.png)
To set up SSO, open `Integrations` in the NetBird admin console's left menu and select the `Single Sign-On` tab. On the Okta card, click `Connect Okta`. This opens the `Connect NetBird with Okta SSO` wizard, which walks you through the rest of the SSO setup. Its first screen lists the Okta permissions you need, covered in the prerequisites below. You set up SCIM later, from the `Identity Provider Sync` tab.

## Prerequisites

Expand All @@ -41,7 +39,7 @@ Confirm that you have one of the required roles before proceeding with the integ

## Installing the NetBird Integration

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.
Once you have the necessary permissions, you can set up the NetBird application. In the NetBird wizard, click `Get Started →`. The wizard shows the `Install NetBird application for Okta` steps.

Let's go through them one by one:

Expand All @@ -57,15 +55,15 @@ You will see a list of users. Find your user account, click `Assign`, and save t

## Configuring SSO in Okta

The next step is to configure Okta-NetBird SSO integration.
The next step is to collect Okta's OpenID Connect details and enter them in NetBird. SSO setup is self-service: you don't need to send these details to the NetBird team.

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.
In NetBird, click the `Continue →` button. The wizard shows the `Enter your Okta details` form. Keep it open and switch to Okta to collect the values.

* 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.
Treat the `Client Secret` like a password. Paste it straight into the NetBird wizard, and don't share it over email or chat.

![The Sign On tab of the NetBird app in Okta, showing the OpenID Connect Client ID and Client Secret](/docs-static/img/manage/team/idp-sync/okta-sync/rl5Gelc.png)

Expand All @@ -78,16 +76,26 @@ Store these credentials securely, as you will need them soon.
* On the top right, click on your username
* Copy your [Okta account domain](https://developer.okta.com/docs/guides/find-your-domain/main/), shown under your email address in that menu, for example `trial-1234567.okta.com`.

The final step is to [send an email to the NetBird team](support@netbird.io) with the authentication information you just retrieved:
Back in the NetBird wizard, fill in the form with the values you collected:

* `Client ID` and `Client Secret`: the values from the Okta `Sign On` tab.
* `Okta account domain`: for example `trial-1234567.okta.com`.
* `Primary E-Mail Domain`: the domain of the email addresses your users sign in with, for example `mycompany.com`.

<img src="/docs-static/img/manage/team/idp-sync/okta-sync/okta-sso-enter-details.png" alt="The Enter your Okta details step of the Connect NetBird with Okta SSO wizard, with fields for Client ID, Client Secret, Okta account domain, and Primary E-Mail Domain, and the Connect button" className="imagewrapper-medium"/>

Click `Connect`. If your primary email domain isn't verified yet, NetBird asks you to prove you own it. The `Verify Domain Ownership` dialog shows a TXT record to add to your DNS:

* `Host`: your primary email domain, for example `mycompany.com`.
* `Value`: `nb-verification=` followed by a token unique to your account. Copy it from the dialog.

Sign in to your DNS provider, add the TXT record, then click `Start Verification`.

* Okta `Client ID`
* Okta `Client secret`
* Okta account domain
* Okta primary email domain (usually your username)
DNS changes can take a while to apply. If NetBird doesn't find the record straight away, click `Verify Later` and try again once the record has propagated: on the `Single Sign-On` tab, click `Settings` on the Okta card, open the `Domains` tab, and click `Verify` next to the domain. If you can't edit DNS for the domain, you can verify it by emailing [support@netbird.io](mailto:support@netbird.io) from an address on that domain instead.

You will receive an email once the NetBird team enables authentication for your account.
When the domain shows `Ownership Verified`, the Okta card on the `Single Sign-On` tab shows `Active`.

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).
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](https://app.netbird.io) and log in with your Okta account.

## Enabling Okta SCIM in NetBird

Expand Down
Loading