diff --git a/docs/directory-sync/api-reference.md b/docs/directory-sync/api-reference.md index d96fba30..02856eed 100644 --- a/docs/directory-sync/api-reference.md +++ b/docs/directory-sync/api-reference.md @@ -12,14 +12,18 @@ The following guides provide information about the APIs and SDKs that are availa ### Directory +Below are the properties of a directory connection. + #### Properties - `name`: The name of the directory - `tenant`: The tenant ID of the tenant you want to create the directory for. - `product`: The product ID of the product you want to create the directory for. - `type`: The directory provider type. See the [Directory Providers](./providers) for more information. -- `webhook_url`: The webhook URL to which the directory connection will POST the events. -- `webhook_secret`: The webhook secret used to sign the webhook payload. +- `webhook.endpoint`: The webhook URL to which the directory connection will POST the events. +- `webhook.secret`: The webhook secret used to sign the webhook payload. +- `log_webhook_events`: Indicate if the webhook events should be logged. +- `deactivated`: Indicate if the directory connection is deactivated. :::info The `tenant` and `product` should not contain the `:` character since we use it as a delimiter internally. @@ -89,7 +93,7 @@ curl --request POST \ #### Response -```javascript +```json { "data": { "id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016", @@ -149,7 +153,7 @@ curl --request GET \ #### Response -```javascript +```json { "data": [ { @@ -208,7 +212,7 @@ curl --request GET \ #### Response -```javascript +```json { "data": { "id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016", @@ -266,7 +270,7 @@ curl --request GET \ #### Response -```javascript +```json { "data": [ { @@ -276,9 +280,7 @@ curl --request GET \ "email": "aswin@boxyhq.com", "active": true, "raw": { - "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:User" - ], + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "aswin@boxyhq.com", "name": { "givenName": "Aswin", @@ -313,9 +315,7 @@ curl --request GET \ "email": "kiran@boxyhq.com", "active": true, "raw": { - "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:User" - ], + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "kiran@boxyhq.com", "name": { "givenName": "Kiran", @@ -383,7 +383,7 @@ curl --request GET \ #### Response -```javascript +```json { "data": { "id": "ebc31d6e-7d62-4f81-b9e5-eb5f1a04ee92", @@ -392,9 +392,7 @@ curl --request GET \ "email": "kiran@boxyhq.com", "active": true, "raw": { - "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:User" - ], + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "kiran@boxyhq.com", "name": { "givenName": "Kiran", @@ -460,16 +458,14 @@ curl --request GET \ #### Response -```javascript +```json { "data": [ { "id": "44d08c0e-d185-4a5e-80a6-b47a717ffaa5", "name": "Developers", "raw": { - "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:Group" - ], + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "displayName": "Developers", "members": [ { @@ -525,15 +521,13 @@ curl --request GET \ #### Response -```javascript +```json { "data": { "id": "44d08c0e-d185-4a5e-80a6-b47a717ffaa5", "name": "Developers", "raw": { - "schemas": [ - "urn:ietf:params:scim:schemas:core:2.0:Group" - ], + "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "displayName": "Developers", "members": [ { @@ -564,6 +558,153 @@ curl --request GET \ --- +### Google Directory Sync + +Google Directory Sync specific properties: + +- `google_domain`: The Google Workspace domain name. +- `google_access_token`: The Google Admin access token. +- `google_refresh_token`: The Google Admin refresh token. + +Jackson requires following API scopes: + +- `https://www.googleapis.com/auth/admin.directory.group.member.readonly` +- `https://www.googleapis.com/auth/admin.directory.group.readonly` + +#### 1. Get Authentication URL + +Get the URL to authenticate with admin credentials. Google will prompt the user to authenticate with the admin credentials and authorize the application to access the Google Workspace directories. + +#### Request + + + + +```javascript showLineNumbers +await directorySyncController.google.generateAuthorizationUrl({ + directoryId: '58b5cd9dfaa39d47eb8f5f88631f9a629a232016', +}); +``` + + + + +#### Response + +```json +{ + "data": { + "authorizationUrl": "https://accounts.google.com/..." + }, + "error": null +} +``` + +#### 2. Get Access Token + +Get the access token from the authorization code. + +#### Request + + + + +```javascript showLineNumbers +await directorySyncController.google.getAccessToken({ + directoryId: '58b5cd9dfaa39d47eb8f5f88631f9a629a232016', + code: 'authorization-code', +}); +``` + + + + +#### Response + +```json +{ + "data": { + "access_token": "ya29.a0AWY7CknlXtELCHzdKuS...", + "refresh_token": "1//03MJpa-zseicbCgYIARAAGAMSNwF-...", + "scope": "https://www.googleapis.com/auth/admin.directory.group.member.readonly https://www.googleapis.com/auth/admin.directory.group.readonly", + "token_type": "Bearer", + "expiry_date": 1684343934305 + }, + "error": null +} +``` + +#### 3. Set Access Token to Directory + +Set the access token and refresh token to the directory. We'll use the access token to make requests to the Google Directory API. + +#### Request + + + + +```javascript showLineNumbers +await directorySyncController.google.setToken({ + directoryId: '58b5cd9dfaa39d47eb8f5f88631f9a629a232016', + accessToken: 'ya29.a0AWY7CknlXtELCHzdKuS...', + refreshToken: '1//03MJpa-zseicbCgYIARAAGAMSNwF-...', +}); +``` + + + + +#### Response + +```json +{ + "data": { + "id": "58b5cd9dfaa39d47eb8f5f88631f9a629a232016", + "name": "App", + "tenant": "boxyhq", + "product": "jackson", + "type": "google", + "google_domain": "boxyhq.com", + "google_access_token": "ya29.a0AWY7CknlXtELCHzdKuS...", + "google_refresh_token": "1//03MJpa-zseicbCgYIARAAGAMSNwF-..." + }, + "error": null +} +``` + +#### 4. Sync Directory + +Jackson can be configured to sync your Google Workspace directory. + + + + +```javascript showLineNumbers +const callback = (event: DirectorySyncEvent) => { + console.log(event); +}; + +await directorySyncController.sync(callback); +``` + + + + +```bash +curl -X POST \ + -H "Authorization: Api-Key YOUR_API_KEY" \ + http://localhost:5225/api/v1/dsync/cron/sync-google +``` + + + + +You'll ideally want to run the sync on a schedule (e.g. every 2 hours). You can use a cron job to invoke this URL on a schedule. + +See more information about the [Directory Sync Event](#handle-the-requests-from-identity-providers) below. + +--- + ### Handle the Requests from Identity Providers Make sure your application can handle the requests from Identity Providers. diff --git a/docs/directory-sync/observability.md b/docs/directory-sync/observability.md new file mode 100644 index 00000000..0c58e667 --- /dev/null +++ b/docs/directory-sync/observability.md @@ -0,0 +1,13 @@ +# Observability + +Jackson provides first-class observability on the back of OpenTelemetry. Currently we support the following metrics. Traces and logs are coming soon. + +Please check the [Environment Variables](../jackson/deploy/env-variables#opentelemetry-configuration) to configure to enable this feature. + +## Metrics + +| Name | Description | Type | +| --------------------------------- | --------------------------------------------------- | ----- | +| `jackson.dsync.connection.create` | Number of directory sync connection create requests | Count | +| `jackson.dsync.connection.get` | Number of directory sync connection get requests | Count | +| `jackson.dsync.connection.delete` | Number of directory sync connection delete requests | Count | diff --git a/docs/directory-sync/providers/google.md b/docs/directory-sync/providers/google.md new file mode 100644 index 00000000..0822d8de --- /dev/null +++ b/docs/directory-sync/providers/google.md @@ -0,0 +1,58 @@ +--- +title: Google Workspace Directory +sidebar_label: Google Workspace +--- + +# Google Workspace + +The following guide will walk you through the process of configuring SAML Jackson to use Google Workspace as a directory sync provider. + +--- + +Jackson requires a Google OAuth App to be configured to access the Google Workspace API. You can use your existing OAuth App or create a new one. + +### Create OAuth App + +Navigate to the [Google Cloud Console](https://console.cloud.google.com/) and select your project from the list. + +![img alt](/img/dsync/providers/google/oauth/1.png) + +Select **APIs & Services** from the left menu and then select **Credentials**. + +Select **OAuth client ID** from the **CREATE CREDENTIALS** dropdown. + +![img alt](/img/dsync/providers/google/oauth/2.png) + +Give your credentials a name and select **Web application** as the **Application type**. + +Add the following **Authorised redirect URIs** and then click **Create**. + +`https:///api/scim/oauth/callback` + +![img alt](/img/dsync/providers/google/oauth/3.png) + +:::info +Note that the above callback URL works if you're using Jackson as a service. + +If using Jackson as an NPM package, the Authorised redirect URIs will be a URL on your application that you'll need to configure. See [Google Directory Sync API](/docs/directory-sync/api-reference#google-directory-sync) for more information. +::: + +Copy the **Client ID** and **Client secret** and save them for later. + +![img alt](/img/dsync/providers/google/oauth/4.png) + +See the [Environment Variables](/docs/directory-sync/api-reference#google-directory-sync) section to learn how to configure Jackson with these values. + +Once configuring Jackson, you can authenticate the tenants with Google OAuth and sync their Workspace directory. + +### Schedule Sync + +Jackson can be configured to sync your Google Workspace directory on a schedule (e.g. every 2 hours). + +Jackson service exposes the below API URL that can be called to trigger a sync. You can use a cron job to invoke this URL on a schedule. + +Depending on the number of Google directories you have, the sync can take a few minutes to complete. + +`https:///api/scim/cron/sync-google` + +Learn more about [Google Directory Sync API](/docs/directory-sync/api-reference#4-sync-directory). diff --git a/docs/directory-sync/providers/index.md b/docs/directory-sync/providers/index.md index caa27cb3..b6471039 100644 --- a/docs/directory-sync/providers/index.md +++ b/docs/directory-sync/providers/index.md @@ -6,3 +6,4 @@ SAML Jackson supports the following directory providers: - [OneLogin SCIM v2.0](./onelogin) - [Okta SCIM v2.0](./okta) - [JumpCloud SCIM v2.0](./jumpcloud) +- [Google Workspace](./google) diff --git a/docs/jackson/deploy/env-variables.md b/docs/jackson/deploy/env-variables.md index d01e36fa..653d5b12 100644 --- a/docs/jackson/deploy/env-variables.md +++ b/docs/jackson/deploy/env-variables.md @@ -393,6 +393,26 @@ Set one of these to `1` or `true` to turn off our anonymous analytics. We only t The following env vars are used to configure the directory sync feature. +`DSYNC_GOOGLE_` env vars are only applicable if you are using Google Workspace as a directory sync provider. + ### **DSYNC_WEBHOOK_BATCH_SIZE** Enable batch processing of directory sync events. The value represents the number of events to batch together instead of sending each event individually. This requires you to configure a cron job to [process the queued events](/docs/directory-sync/api-reference#batch-processing-events) + +### **DSYNC_GOOGLE_CLIENT_ID** + +The Google authentication client ID. + +NPM library option: `dsync.providers.google.clientId` + +### **DSYNC_GOOGLE_CLIENT_SECRET** + +The Google authentication client secret. + +NPM library option: `dsync.providers.google.clientSecret` + +### **DSYNC_GOOGLE_REDIRECT_URI** + +The URI to redirect to after completing the authentication request. + +NPM library option: `dsync.providers.google.callbackUrl` diff --git a/docs/jackson/observability.md b/docs/jackson/observability.md index ffe6f1d4..d2f31d97 100644 --- a/docs/jackson/observability.md +++ b/docs/jackson/observability.md @@ -6,14 +6,11 @@ Please check the [Environment Variables](./deploy/env-variables.md#opentelemetry ## Metrics -| Name | Description | Type | -| --------------------------------- | --------------------------------------------------- | ----- | -| `jackson.connection.create` | Number of SSO Connection create requests | Count | -| `jackson.connection.get` | Number of SSO Connection get requests | Count | -| `jackson.connection.delete` | Number of SSO Connection delete requests | Count | -| `jackson.oauth.authorize` | Number of oauth authorize requests | Count | -| `jackson.oauth.token` | Number of oauth token requests | Count | -| `jackson.oauth.userinfo` | Number of oauth user info requests | Count | -| `jackson.dsync.connection.create` | Number of directory sync connection create requests | Count | -| `jackson.dsync.connection.get` | Number of directory sync connection get requests | Count | -| `jackson.dsync.connection.delete` | Number of directory sync connection delete requests | Count | +| Name | Description | Type | +| --------------------------- | ---------------------------------------- | ----- | +| `jackson.connection.create` | Number of SSO Connection create requests | Count | +| `jackson.connection.get` | Number of SSO Connection get requests | Count | +| `jackson.connection.delete` | Number of SSO Connection delete requests | Count | +| `jackson.oauth.authorize` | Number of oauth authorize requests | Count | +| `jackson.oauth.token` | Number of oauth token requests | Count | +| `jackson.oauth.userinfo` | Number of oauth user info requests | Count | diff --git a/sidebars.js b/sidebars.js index c83f71c4..4a066360 100644 --- a/sidebars.js +++ b/sidebars.js @@ -68,6 +68,7 @@ module.exports = { 'directory-sync/examples', 'directory-sync/webhooks', 'directory-sync/events', + 'directory-sync/observability', { type: 'category', label: 'Providers', @@ -78,6 +79,7 @@ module.exports = { 'directory-sync/providers/okta', 'directory-sync/providers/onelogin', 'directory-sync/providers/jumpcloud', + 'directory-sync/providers/google', ], }, ], diff --git a/static/img/dsync/providers/google/oauth/1.png b/static/img/dsync/providers/google/oauth/1.png new file mode 100644 index 00000000..0a8d0e1b Binary files /dev/null and b/static/img/dsync/providers/google/oauth/1.png differ diff --git a/static/img/dsync/providers/google/oauth/2.png b/static/img/dsync/providers/google/oauth/2.png new file mode 100644 index 00000000..c7865649 Binary files /dev/null and b/static/img/dsync/providers/google/oauth/2.png differ diff --git a/static/img/dsync/providers/google/oauth/3.png b/static/img/dsync/providers/google/oauth/3.png new file mode 100644 index 00000000..21f58caa Binary files /dev/null and b/static/img/dsync/providers/google/oauth/3.png differ diff --git a/static/img/dsync/providers/google/oauth/4.png b/static/img/dsync/providers/google/oauth/4.png new file mode 100644 index 00000000..1b10cddd Binary files /dev/null and b/static/img/dsync/providers/google/oauth/4.png differ