diff --git a/public/docs-static/img/manage/team/idp-sync/okta-sync/nwutb3Z.png b/public/docs-static/img/manage/team/idp-sync/okta-sync/nwutb3Z.png deleted file mode 100644 index 4d1518fd..00000000 Binary files a/public/docs-static/img/manage/team/idp-sync/okta-sync/nwutb3Z.png and /dev/null differ diff --git a/public/docs-static/img/manage/team/idp-sync/okta-sync/okta-sso-enter-details.png b/public/docs-static/img/manage/team/idp-sync/okta-sync/okta-sso-enter-details.png new file mode 100644 index 00000000..8363a951 Binary files /dev/null and b/public/docs-static/img/manage/team/idp-sync/okta-sync/okta-sso-enter-details.png differ diff --git a/src/pages/manage/team/idp-sync/okta-sync.mdx b/src/pages/manage/team/idp-sync/okta-sync.mdx index 26379f10..b9c243b6 100644 --- a/src/pages/manage/team/idp-sync/okta-sync.mdx +++ b/src/pages/manage/team/idp-sync/okta-sync.mdx @@ -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 @@ -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: @@ -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) @@ -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: -* Okta `Client ID` -* Okta `Client secret` -* Okta account domain -* Okta primary email domain (usually your username) +* `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`. -You will receive an email once the NetBird team enables authentication for your account. +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 -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). +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`. + +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. + +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](https://app.netbird.io) and log in with your Okta account. ## Enabling Okta SCIM in NetBird