Extend IdP sync API docs with user/group filters (#130)

netbirdio · Jan 15, 2024 · e6ee8ec · e6ee8ec
1 parent ba2d7c7
commit e6ee8ec
Showing 1 changed file with 50 additions and 22 deletions.
diff --git a/misc/idp-sync/api.md b/misc/idp-sync/api.md
@@ -13,12 +13,13 @@ By default, for new integration synchronization is enabled.
 
 Request:
 - `service_account_key`: A Base64 encoded string derived from a service account key JSON. For the creation of the service account key JSON, refer to the provided [IdP guideline](https://docs.netbird.io/how-to/idp-sync#google-work-space).
-  Encode service account JSON to base64 by using the command:
+Encode service account JSON to base64 by using the command:
 ```shell
   base64 -i <SERVICE_ACCOUNT_KEY_PATH>
 ``` 
-
 -  `sync_interval`: Optional. The default value is 300 seconds.
+-  `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.
 
 ```shell
 curl --request POST \
@@ -27,18 +28,22 @@ curl --request POST \
   --header 'Authorization: Token <PAT>' \
   --header 'Content-Type: application/json' \
   --data '{
-	"service_account_key": "<SERVICE_ACCOUNT_KEY>",
-	"customerID": "<CUSTOMER_ID>"
+    "service_account_key": "<SERVICE_ACCOUNT_KEY>",
+    "customerID": "<CUSTOMER_ID>",
+    "group_prefixes": [],
+    "user_group_prefixes": []
 }'
 ```
 
 Response
 ```json
 {
-	"id": <ID>,
-	"customer_id": "<CUSTOMER_ID",
-	"sync_interval": 300,
-	"enabled": true
+  "id": <ID>,
+  "customer_id": "<CUSTOMER_ID",
+  "sync_interval": 300,
+  "enabled": true,
+  "group_prefixes": [],
+  "user_group_prefixes": []
 }
 ```
 
@@ -57,7 +62,9 @@ Response
   "id": <ID>,
   "customer_id": "<CUSTOMER_ID",
   "sync_interval": 300,
-  "enabled": true
+  "enabled": true,
+  "group_prefixes": [],
+  "user_group_prefixes": []
 }
 ```
 
@@ -77,7 +84,9 @@ Response
     "id": <ID>,
     "customer_id": "<CUSTOMER_ID>",
     "sync_interval": 300,
-    "enabled": true
+    "enabled": true,
+    "group_prefixes": [],
+    "user_group_prefixes": []
   }
 ]
 ```
@@ -108,7 +117,9 @@ Request
   base64 -i <SERVICE_ACCOUNT_KEY_PATH>
 ``` 
 -  `sync_interval`: Optional. Should not be less than 300 seconds.
-- `enabled`: Optional. Used to disable/enable the integration.
+-  `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 \
@@ -117,9 +128,11 @@ curl --request PUT \
   --header 'Authorization: Token <PAT>' \
   --header 'Content-Type: application/json' \
   --data '{
-	"service_account_key": "<SERVICE_ACCOUNT_KEY>",
-	"sync_interval": 300,
-	"enabled": false
+    "service_account_key": "<SERVICE_ACCOUNT_KEY>",
+    "sync_interval": 300,
+    "enabled": false,
+    "group_prefixes": [],
+    "user_group_prefixes": []
 }'
 ```
 
@@ -129,7 +142,9 @@ Response
   "id": <ID>,
   "customer_id": "<CUSTOMER_ID>",
   "sync_interval": 300,
-  "enabled": false
+  "enabled": false,
+  "group_prefixes": [],
+  "user_group_prefixes": []
 }
 ```
 
@@ -182,6 +197,9 @@ Request:
 - `client_id`: Azure Directory application client Id.
 - `tenant_id`: Azure Directory ID.
 - `sync_interval`: Optional. The default value is 300 seconds.
+-  `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 \
@@ -190,9 +208,11 @@ curl --request POST \
   --header 'Authorization: Token <PAT>' \
   --header 'Content-Type: application/json' \
   --data '{
-	"client_secret": "<CLIENT_SECRET>",
-	"client_id": "<CLIENT_ID>",
-	"tenant_id": "<TENANT_ID>"
+    "client_secret": "<CLIENT_SECRET>",
+    "client_id": "<CLIENT_ID>",
+    "tenant_id": "<TENANT_ID>",
+    "group_prefixes": [],
+    "user_group_prefixes": []
 }'
 ```
 
@@ -223,7 +243,9 @@ Response
   "client_id": "<CLIENT_ID>",
   "tenant_id": "<TENANT_ID>",
   "sync_interval": 300,
-  "enabled": true
+  "enabled": true,
+  "group_prefixes": [],
+  "user_group_prefixes": []
 }
 ```
 
@@ -244,7 +266,9 @@ Response
     "client_id": "<CLIENT_ID>",
     "tenant_id": "<TENANT_ID>",
     "sync_interval": 300,
-    "enabled": true
+    "enabled": true,
+    "group_prefixes": [],
+    "user_group_prefixes": []
   }
 ]
 ```
@@ -275,7 +299,9 @@ Request
   echo -n <CLIENT_SECRET> | base64
 ``` 
 -  `sync_interval`: Optional. Should not be less than 300 seconds.
-- `enabled`: Optional. Used to disable/enable the integration.
+-  `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 \
@@ -297,7 +323,9 @@ Response
   "client_id": "<CLIENT_ID>",
   "tenant_id": "<TENANT_ID>",
   "sync_interval": 300,
-  "enabled": true
+  "enabled": true,
+  "group_prefixes": [],
+  "user_group_prefixes": []
 }
 ```