mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-19 00:46:35 +00:00
Add IdP sync docs (#117)
* Add misc idp configs * Update api.md * add idp-sync docs for Azure AD * Rephrase * API integration section titles --------- Co-authored-by: braginini <bangvalo@gmail.com>
This commit is contained in:
Bethuel Mmbaga
335
misc/idp-sync/api.md
Normal file
335
misc/idp-sync/api.md
Normal file
@@ -0,0 +1,335 @@
|
||||
# Integration API Documentation
|
||||
|
||||
## Introduction
|
||||
This reference provides detailed information on managing integrations via NetBird Cloud API.
|
||||
|
||||
## Authentication
|
||||
Authentication is required for all API requests. Please refer to the [authentication guideline](https://docs.netbird.io/how-to/access-netbird-public-api) for how to create and authenticate API calls using Personal Access Tokens (PAT).
|
||||
|
||||
## Google Workspace Integration
|
||||
|
||||
### Create Integration
|
||||
The new integration synchronization is enabled by default when created.
|
||||
|
||||
Request:
|
||||
- `serviceAccountKey`: 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](idp.md).
|
||||
Encode service account JSON to base64 by using the command:
|
||||
```shell
|
||||
base64 -i <SERVICE_ACCOUNT_KEY_PATH>
|
||||
```
|
||||
|
||||
- `syncInterval`: Optional. The default value is 300 seconds.
|
||||
|
||||
```shell
|
||||
curl --request POST \
|
||||
--url https://api.netbird.io/api/integrations/google-idp \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"serviceAccountKey": "<SERVICE_ACCOUNT_KEY>",
|
||||
"customerID": "<CUSTOMER_ID>"
|
||||
}'
|
||||
```
|
||||
|
||||
Response
|
||||
```json
|
||||
{
|
||||
"id": <ID>,
|
||||
"customerId": "<CUSTOMER_ID",
|
||||
"syncInterval": 300,
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
### Get Integration by ID
|
||||
Request
|
||||
```shell
|
||||
curl --request GET \
|
||||
--url https://api.netbird.io/api/integrations/google-idp/<ID> \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>'
|
||||
```
|
||||
|
||||
Response
|
||||
```json
|
||||
{
|
||||
"id": <ID>,
|
||||
"customerId": "<CUSTOMER_ID",
|
||||
"syncInterval": 300,
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
### Get All Integrations By AccountID
|
||||
Request
|
||||
```shell
|
||||
curl --request GET \
|
||||
--url https://api.netbird.io/api/integrations/google-idp \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>'
|
||||
```
|
||||
|
||||
Response
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": <ID>,
|
||||
"customerId": "<CUSTOMER_ID>",
|
||||
"syncInterval": 300,
|
||||
"enabled": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Force Integration Sync
|
||||
Request
|
||||
```shell
|
||||
curl --request GET \
|
||||
--url https://api.netbird.io/api/integrations/google-idp/<ID>/sync \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>'
|
||||
```
|
||||
|
||||
Response
|
||||
```json
|
||||
{
|
||||
"result": "ok"
|
||||
}
|
||||
```
|
||||
|
||||
### Update Integration
|
||||
Updates the selected parameters for a specific integration.
|
||||
|
||||
Request
|
||||
- `serviceAccountKey`: 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](idp.md).
|
||||
Encode service account JSON to base64 by using the command:
|
||||
```shell
|
||||
base64 -i <SERVICE_ACCOUNT_KEY_PATH>
|
||||
```
|
||||
- `syncInterval`: Optional. Should not be less than 300 seconds.
|
||||
- `enabled`: Optional. Used to disable/enable the integration.
|
||||
|
||||
```shell
|
||||
curl --request PUT \
|
||||
--url https://api.netbird.io/api/integrations/google-idp/<ID> \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"serviceAccountKey": "<SERVICE_ACCOUNT_KEY>",
|
||||
"syncInterval": 300,
|
||||
"enabled": false
|
||||
}'
|
||||
```
|
||||
|
||||
Response
|
||||
```json
|
||||
{
|
||||
"id": <ID>,
|
||||
"customerId": "<CUSTOMER_ID>",
|
||||
"syncInterval": 300,
|
||||
"enabled": false
|
||||
}
|
||||
```
|
||||
|
||||
### Delete Integration
|
||||
Request
|
||||
```shell
|
||||
curl --request DELETE \
|
||||
--url https://api.netbird.io/api/integrations/google-idp/<ID> \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>'
|
||||
```
|
||||
Response
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
### Get Integration sync logs
|
||||
Request
|
||||
```shell
|
||||
curl --request GET \
|
||||
--url https://api.netbird.io/api/integrations/google-idp/<ID>/logs \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>'
|
||||
```
|
||||
Response
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": <ID>,
|
||||
"level": "info",
|
||||
"timestamp": "timestamp UTC",
|
||||
"message": "message"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
|
||||
## Azure AD Integration
|
||||
Before proceeding with the setup, please ensure that you have configured Azure as per the guidelines outlined in the [IdP guideline](idp.md).
|
||||
|
||||
### Create Integration
|
||||
The new integration synchronization is enabled by default when created.
|
||||
|
||||
Request:
|
||||
- `clientSecret`: A Base64 encoded string derived from Azure Directory application client credential secret.
|
||||
Encode service account JSON to base64 by using the command:
|
||||
```shell
|
||||
echo -n <CLIENT_SECRET> | base64
|
||||
```
|
||||
- `clientId`: Azure Directory application client Id.
|
||||
- `tenantId`: Azure Directory ID.
|
||||
- `syncInterval`: Optional. The default value is 300 seconds.
|
||||
|
||||
```shell
|
||||
curl --request POST \
|
||||
--url https://api.netbird.io/api/integrations/azure-idp \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"clientSecret": "<CLIENT_SECRET>",
|
||||
"clientId": "<CLIENT_ID>",
|
||||
"tenantId": "<TENANT_ID>"
|
||||
}'
|
||||
```
|
||||
|
||||
Response
|
||||
```json
|
||||
{
|
||||
"id": <ID>,
|
||||
"clientId": "<CLIENT_ID>",
|
||||
"tenantId": "<TENANT_ID>",
|
||||
"syncInterval": 300,
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
### Get Integration by ID
|
||||
Request
|
||||
```shell
|
||||
curl --request GET \
|
||||
--url https://api.netbird.io/api/integrations/azure-idp/<ID> \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>'
|
||||
```
|
||||
|
||||
Response
|
||||
```json
|
||||
{
|
||||
"id": <ID>,
|
||||
"clientId": "<CLIENT_ID>",
|
||||
"tenantId": "<TENANT_ID>",
|
||||
"syncInterval": 300,
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
### Get All Integrations By AccountID
|
||||
Request
|
||||
```shell
|
||||
curl --request GET \
|
||||
--url https://api.netbird.io/api/integrations/azure-idp \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>'
|
||||
```
|
||||
|
||||
Response
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": <ID>,
|
||||
"clientId": "<CLIENT_ID>",
|
||||
"tenantId": "<TENANT_ID>",
|
||||
"syncInterval": 300,
|
||||
"enabled": true
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Force Integration Sync
|
||||
Request
|
||||
```shell
|
||||
curl --request GET \
|
||||
--url https://api.netbird.io/api/integrations/azure-idp/<ID>/sync \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>'
|
||||
```
|
||||
|
||||
Response
|
||||
```json
|
||||
{
|
||||
"result": "ok"
|
||||
}
|
||||
```
|
||||
|
||||
### Update Integration
|
||||
Updates the selected parameters for a specific integration.
|
||||
|
||||
Request
|
||||
- `clientSecret`: A Base64 encoded string derived from Azure Directory application client credential secret.
|
||||
Encode service account JSON to base64 by using the command:
|
||||
```shell
|
||||
echo -n <CLIENT_SECRET> | base64
|
||||
```
|
||||
- `syncInterval`: Optional. Should not be less than 300 seconds.
|
||||
- `enabled`: Optional. Used to disable/enable the integration.
|
||||
|
||||
```shell
|
||||
curl --request PUT \
|
||||
--url https://api.netbird.io/api/integrations/azure-idp/<ID> \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data '{
|
||||
"clientSecret": "<CLIENT_SECRET>",
|
||||
"syncInterval": 300,
|
||||
"enabled": false
|
||||
}'
|
||||
```
|
||||
|
||||
Response
|
||||
```json
|
||||
{
|
||||
"id": <ID>,
|
||||
"clientId": "<CLIENT_ID>",
|
||||
"tenantId": "<TENANT_ID>",
|
||||
"syncInterval": 300,
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
### Delete Integration
|
||||
Request
|
||||
```shell
|
||||
curl --request DELETE \
|
||||
--url https://api.netbird.io/api/integrations/azure-idp/<ID> \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>'
|
||||
```
|
||||
Response
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
### Get Integration sync logs
|
||||
Request
|
||||
```shell
|
||||
curl --request GET \
|
||||
--url https://api.netbird.io/api/integrations/azure-idp/<ID>/logs \
|
||||
--header 'Accept: application/json' \
|
||||
--header 'Authorization: Token <PAT>'
|
||||
```
|
||||
Response
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": <ID>,
|
||||
"level": "info",
|
||||
"timestamp": "timestamp UTC",
|
||||
"message": "message"
|
||||
}
|
||||
]
|
||||
```
|
||||
Reference in New Issue
Block a user