Okta SCIM sync (#163)

Co-authored-by: Maycon Santos <mlsmaycon@gmail.com>
Co-authored-by: Misha Bragin <bangvalo@gmail.com>

misc/idp-sync/api.md

@@ -1,5 +1,13 @@
 # Integration API Documentation
 
+Table of contents
+* [Introduction](#introduction)
+* [Authentication](#authentication)
+* [Google endpoints](#google-endpoints)
+* [Azure/Entra ID](#azure-endpoints)
+* [Okta SCIM endpoints](#okta-scim-endpoints)
+
+
 ## Introduction
 This reference provides detailed information on managing integrations via NetBird Cloud API.
 
@@ -365,3 +373,177 @@ Response
   }
 ]
 ```
+
+## Okta SCIM Endpoints
+
+### Create Integration
+Create a Okta SCIM integration with the following request. The new integration will be enabled by default.
+
+Request input:
+-  `group_prefixes`: Specifies list of starts_with patterns for group provision. If the group name matches one the the pattern it will be provisioned regardless of the members. Optional. The default value is empty list.
+-  `user_group_prefixes`: Specifies list of starts_with patterns for user provision. If the user belongs to group which name matches one the the pattern the user will be provisioned. Optional. The default value is empty list.
+- `enabled`: Optional. Used to disable/enable the integration.
+
+```shell
+curl --request POST \
+  --url https://api.netbird.io/api/integrations/okta-scim-idp \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token <PAT>' \
+  --header 'Content-Type: application/json' \
+  --data '{
+    "group_prefixes": [],
+    "user_group_prefixes": []
+}'
+```
+
+
+Response
+```json
+{
+	"id": 1,
+	"enabled": true,
+	"group_prefixes": [],
+	"user_group_prefixes": [],
+	"auth_token": "nbs_pBmR9mwBpsJH03B0DGojHzhLTRndg90QGPsS"
+}
+```
+
+> Take a note of the `auth_token` returned; you will need it to configure the Okta application.
+
+
+### Get all Okta integrations for the account
+Request
+```shell
+curl --request GET \
+  --url https://api.netbird.io/api/integrations/okta-scim-idp \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token <PAT>'
+```
+
+Response
+```json
+[
+  {
+  	"id": 1,
+  	"enabled": true,
+  	"group_prefixes": [],
+  	"user_group_prefixes": [],
+  	"auth_token": "nbs_pBm*********************************"
+  }
+]
+```
+
+### Get Integration by ID
+Request
+```shell
+curl --request GET \
+  --url https://api.netbird.io/api/integrations/okta-scim-idp/<ID> \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token <PAT>'
+```
+
+Response
+```json
+{
+	"id": 1,
+	"enabled": true,
+	"group_prefixes": [],
+	"user_group_prefixes": [],
+	"auth_token": "nbs_pBm*********************************"
+}
+```
+
+### Regenerate Auth token
+Request
+```shell
+curl --request POST \
+  --url https://api.netbird.io/api/integrations/okta-scim-idp/<ID>/token \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token <PAT>'
+```
+> Replace ID with the integration ID you want to update.
+
+Response
+```json
+{
+	"id": 1,
+	"enabled": true,
+	"group_prefixes": [],
+	"user_group_prefixes": [],
+	"auth_token": "nbs_pBmR9mwBpsJH03B0DGojHzhLTRndg90QGPsS"
+}
+```
+
+### Update Integration
+Updates the selected parameters for a specific integration.
+
+Request
+-  `group_prefixes`: Specifies list of starts_with patterns for group provision. If the group name matches one the the pattern it will be provisioned regardless of the members. Optional. The default value is empty list.
+-  `user_group_prefixes`: Specifies list of starts_with patterns for user provision. If the user belongs to group which name matches one the the pattern the user will be provisioned. Optional. The default value is empty list.
+- `enabled`: Optional. Used to disable/enable the integration.
+
+```shell
+curl --request PUT \
+  --url https://api.netbird.io/api/integrations/okta-scim-idp/<ID> \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token <PAT>' \
+  --header 'Content-Type: application/json' \
+  --data '{
+	"enabled": true,
+	"group_prefixes": [],
+	"user_group_prefixes": []
+}'
+```
+
+> Replace ID with the integration ID you want to update.
+
+Response
+```json
+{
+	"id": 1,
+	"enabled": true,
+	"group_prefixes": [],
+	"user_group_prefixes": [],
+	"auth_token": "nbs_pBmR9mwBpsJH03B0DGojHzhLTRndg90QGPsS"
+}
+```
+
+### Delete Integration
+Request
+```shell
+curl --request DELETE \
+  --url https://api.netbird.io/api/integrations/okta-scim-idp/<ID> \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token <PAT>'
+```
+
+> Replace ID with the integration ID you want to update.
+
+Response
+```json
+{}
+```
+
+### Get Integration sync logs
+Request
+```shell
+curl --request GET \
+  --url https://api.netbird.io/api/integrations/okta-scim-idp/<ID>/logs \
+  --header 'Accept: application/json' \
+  --header 'Authorization: Token <PAT>'
+```
+
+> Replace ID with the integration ID you want to update.
+
+Response
+```json
+[
+  {
+    "id": <ID>,
+    "level": "info",
+    "timestamp": "timestamp UTC",
+    "message": "message"
+  }
+]
+```
+

src/pages/how-to/idp-sync.mdx

@@ -121,4 +121,128 @@ Before you start creating and configuring an Azure AD application, ensure that y
 </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`.
+- Select `NetBird` application in overview page, take note of `Application (client) ID` and `Directory (tenant) ID`.
+
+
+### Okta
+
+#### Step 1. Create and configure SAML 2.0 application
+In this step, we will create and configure NetBird SAML 2.0 application in okta.
+- Navigate to Okta Admin Dashboard
+- Click `Applications` in the left menu and then click on `Applications`
+- Click `Create App Integration`
+- Fill in the form with the following values and click `Next`
+  - Sign-in method: `SAML 2.0`
+
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-new-application.png" alt="high-level-dia" />
+</p>
+
+- Fill in the form with the following values and click `Next`
+  - App integration name: `NetBird SCIM`
+
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-saml-general-settings.png" alt="high-level-dia" />
+</p>
+
+- Fill in the form will the following values and click `Next`
+    - Single sign-on URL: `http://localhost`
+    - Audience URI (SP Entity ID): `http://localhost`
+
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-saml-configuration.png" alt="high-level-dia" />
+</p>
+
+- Select  App type as `This is an internal app that we have created` and click `Finish`
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-saml-configuration-feedback.png" alt="high-level-dia" />
+</p>
+
+#### Step 2. Create Okta SCIM integration
+Refer to the [api.md](https://github.com/netbirdio/docs/blob/main/misc/idp-sync/api.md#okta-scim-endpoints) document for detailed instructions on how to create the integration.
+After creating, please take note of the `auth_token` from the response as we will use it in the next step.
+
+#### Step 3. Enable and configure SCIM provisioning
+Before proceeding with this step, we need to create
+- Navigate to Okta Admin Dashboard
+- Click `Applications` in the left menu and then click on `Applications`
+- Select the `NetBird SCIM` application we created earlier
+
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-netbird-app-overview.png" alt="high-level-dia" />
+</p>
+
+- Click `General` tab and in `App Settings` click `Edit` to update the settings
+- Tick `Enable SCIM provisioning` and click `Save`
+
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-scim-provisioning-enabled.png" alt="high-level-dia" />
+</p>
+
+- Click `Provisioning` and under `SCIM connection` click `Edit`
+- Fill in the form will the following values and click `Save`
+    - SCIM connector base URL: `https://api.netbird.io/api/scim/v2`
+    - Unique identifier field for users: `userName`
+    - Supported provisioning actions: `Push New Users`, `Push Profile Updates`, `Push Groups`
+    - Authentication Mode: `HTTP Header`
+    - HTTP Header Token you obtained from NetBird : `nbs_zKY09...`
+
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-scim-provisioning-settings.png" alt="high-level-dia" />
+</p>
+
+- Click on `Test Connector Configuration` to verify if the SCIM configuration is working. After the test is completed,
+make sure `Create Users`, `Update User Attributes`, and `Push Groups` were successful.
+
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-connector-configuration-test.png" alt="high-level-dia" />
+</p>
+
+
+- Click `Save` and then click `Provisioning` tab
+
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-scim-to-app-configuration.png" alt="high-level-dia" />
+</p>
+
+- Go to the `Provisioning` tab, and select the `To App` settings and click `Edit`
+- Enable `Create Users`, `Update User Attributes`, and `Deactivate Users` and click `Save`
+
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-scim-to-app-sync-enabled.png" alt="high-level-dia" />
+</p>
+
+#### Step 4. Assign groups to application and push to NetBird
+
+This step will cover how to provision user sync using groups and push them to NetBird. If you are interested in managing single user
+access without using the groups, you can learn how to do it [here](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-assign-apps.htm).
+
+- Go to the `Assignments` tab.
+
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-groups-assignments.png" alt="high-level-dia" />
+</p>
+
+- Select the `Assign` and then click `Assign to Groups`
+- Select the groups you want to provision, and then select `Assign` and click `Save and Go Back`.
+- Select `Done` after you've finished assigning groups.
+
+At this point, all members of the groups assigned to the application will be synced to NetBird.
+
+- Go to the `Push Groups` tab
+
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-sync-groups.png" alt="high-level-dia" />
+</p>
+
+- Select the `Push Groups` and then click `Find groups by name`
+- Search groups to push and then click `Save`
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-push-group-assignment.png" alt="high-level-dia" />
+</p>
+
+- The selected groups will then be synced to NetBird.
+<p>
+    <img src="/docs-static/img/how-to-guides/okta-group-push-status.png" alt="high-level-dia" />
+</p>
+