You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: enterprise/all-enteprise-features/external-openid-providers/README.md
+40
Original file line number
Diff line number
Diff line change
@@ -78,6 +78,46 @@ For this to work, make sure you have the following two things set:
78
78
79
79
If you disable the option above, new users won't be able to automatically go through the enrollment. You will need to create their accounts by hand (with the same email address as the one they have set on your OIDC provider's side) and only then they will have an option to activate it by logging through the provider.
80
80
81
+
### Directory synchronization
82
+
83
+
{% hint style="info" %}
84
+
This feature is available only in Defguard v1.2.0 and above
85
+
{% endhint %}
86
+
87
+
Defguard supports synchronizing users' and groups' states based on the state of the external provider directory. The following things can be synchronized:
88
+
89
+
***User Groups**: Automatically create and assign user groups in Defguard to reflect them in Google Workspace.
90
+
***User Deletion**: Removing a user from the provider's directory can also remove them from Defguard.
91
+
***User Status**: Disabling users in the provider's directory will disable them in Defguard.
92
+
93
+
Defguard doesn't automatically create users based on the users in your provider's directory. They will have to manually log in to Defguard through your provider for their Defguard accounts to be created. Defguard is responsible only for synchronizing their later state.
94
+
95
+
#### General configuration
96
+
97
+
The menu can be found in Defguard settings by navigating to the "OpenID" tab.
The following configuration options are currently available in the directory synchronization menu for all providers:
102
+
103
+
***Synchronize (All/User/Group):** What to synchronize.
104
+
***All** - synchronize both user state (disabled/enabled), their deletion, and groups
105
+
***User** - synchronize only user state (disabled/enabled) and whether they've been deleted
106
+
***Group** - synchronize only user groups
107
+
***Synchronization interval (600s by default):** How often to synchronize with your provider. Very low values may cause issues with the provider API. The user state is also synchronized on login.
108
+
109
+
{% hint style="danger" %}
110
+
If you want to delete your users based on the state of your provider we recommend trying out the "disable" behavior first to make sure everything works as expected. Always back up your database regularly.
111
+
{% endhint %}
112
+
113
+
***User behavior (Keep, Disable, Delete):** What to do with Defguard users who are absent from your provider's directory.
114
+
***Admin behavior (Keep, Disable, Delete):** What to do with Defguard users with admin status (in Defguard) who are absent from your provider's directory.
Defguard supports custom providers that allow a **code** response type in the OpenID authorization flow.
5
+
{% endhint %}
6
+
7
+
You can also configure a custom OpenID provider. The key thing here is setting up the **Base URL** correctly. This URL is used to discover all the endpoints required for the authorization flow.
8
+
9
+
The easiest way of obtaining the Base URL is to find out what is the OpenID `.well-known` URL of your provider. For example, for Google it's `https://accounts.google.com/.well-known/openid-configuration`, in this case, the Base URL would be `https://accounts.google.com` (note the lack of a trailing slash). The part starting with `/.well-known` is added automatically, so it should be omitted from the Base URL. This is explained in more detail in the [Base URL](custom.md#base-url) section.
10
+
11
+
In order to get the **Client ID** and **Client Secret** values, refer to the documentation of your custom provider of choice.
12
+
13
+
When configuring your external OpenID provider, at some point you will need to provide a callback URL, which will redirect the user back to Defguard. This URL is in form of `<DEFGUARD_DASHBOARD_URL>/auth/callback`. Replace `<DEFGUARD_DASHBOARD_URL>` with the URL under which your dashboard is accessible, e.g. `https://defguard.example.com`. If you'd like to use OpenID enrollment through proxy too, make sure to enter an additional URI in the form of `<DEFGUARD_ENROLLMENT_URL>/openid/callback`.
14
+
15
+
If you're having issues with your custom provider's base URL, check Defguard's (core) logs. It should say what URL it expected.
Copy file name to clipboardexpand all lines: enterprise/all-enteprise-features/external-openid-providers/google.md
+6-22
Original file line number
Diff line number
Diff line change
@@ -42,40 +42,24 @@ This feature is currently limited to 500 Google Workspace members or groups. It
42
42
This feature is available only in Defguard v1.2.0 and above
43
43
{% endhint %}
44
44
45
-
Defguard supports synchronization of users and groups state based on Google Workspace. The following things can be synchronized:
46
-
47
-
***User Groups**: Automatically create and assign user groups in Defguard to reflect them in Google Workspace.
48
-
***User Deletion**: Removing a user in Google Workspace can also remove them in Defguard.
49
-
***User Status**: Disabling a user in Google Workspace will disable them in Defguard.
50
-
51
-
Defguard doesn't automatically create users based on the users in your Workspace. They will have to manually login to Defguard through your provider in order for their Defguard accounts to be created. Defguard is responsible only for synchronizing their later state.
45
+
This documentation concerns only the Google directory synchronization. For more general information, see the [general directory synchronization guide](./#directory-synchronization).
52
46
53
47
#### Directory synchronization configuration menu
54
48
55
49
The menu can be found in Defguard settings by navigating to the "OpenID" tab.
The following configuration options are currently available in the directory synchronization menu:
60
-
61
-
***Synchronize (All/User/Group):** What to synchronize.
62
-
***All** - synchronize both user state (disabled/enabled), their deletion and groups
63
-
***User** - synchronize only user state (disabled/enabled) and whether they've been deleted
64
-
***Group** - synchronize only user groups
65
-
***Synchronization interval (600s by default):** How often to synchronize with Google. Very low values may cause issues with Google API. Users are also synchronized on login.
53
+
The following configuration options are currently available in the directory synchronization menu specifically for the Google provider:
66
54
67
-
{% hint style="danger" %}
68
-
If you want to delete your users based on the state of Google Workspace we recommend trying out the "disable" behavior first to make sure everything works as expected. Always backup your database regularly.
69
-
{% endhint %}
70
-
71
-
***User behavior (Keep, Disable, Delete):** What to do with Defguard users not present in Google Workspace.
72
-
***Admin behavior (Keep, Disable, Delete):** What to do with Defguard users with admin status (in Defguard) who are not present in Google Workspace.
73
55
***Admin email:** The email of the Google Workspace admin user on whose behalf Defguard will call the Google API
74
-
***Service account in use:** The email of the Google service account which is currently used
56
+
***Service account in use:** The email of the Google service account that is currently used
57
+
58
+
To learn more about the rest of the configuration options, see the [general directory synchronization guide](./#directory-synchronization).
75
59
76
60
#### Directory synchronization setup
77
61
78
-
1. Navigate to [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) in the Google cloud console\
62
+
1. Navigate to [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) in the Google Cloud console\
Copy file name to clipboardexpand all lines: enterprise/all-enteprise-features/external-openid-providers/microsoft.md
+38-7
Original file line number
Diff line number
Diff line change
@@ -30,18 +30,49 @@ Make sure the Redirect URL you insert here is correct. Replace `defguard.example
30
30
31
31
13. Now you should be good to go. A new login button should appear on the login screen.
32
32
33
-
#### Custom OpenID provider
33
+
### Directory synchronization
34
+
35
+
{% hint style="info" %}
36
+
This feature is available only in Defguard 1.2.1 and above
37
+
{% endhint %}
34
38
35
39
{% hint style="warning" %}
36
-
Defguard supports custom providers that allow a **code** response type in the OpenID authorization flow.
40
+
This feature is currently limited to 999 Microsoft Entra ID members or groups. It may not work correctly if you have more members than that. If this limit is an issue, report it on our GitHub.
37
41
{% endhint %}
38
42
39
-
You can also configure a custom OpenID provider. The key thing here is setting up the **Base URL** correctly. This URL is used to discover all the endpoints required for the authorization flow.
43
+
Defguard supports synchronizing groups' and users' states based on your Microsoft directory.
44
+
45
+
Make sure to check the [general guide to directory synchronization](./#directory-synchronization) to learn more about the available configuration options.
46
+
47
+
#### Setup
48
+
49
+
1. Go back to your app registrations in Microsoft Entra ID and select the app you registered during the provider setup.
6. Now grant admin consent for the permissions using the "Grant admin consent for" button\
40
73
41
-
The easiest way of obtaining the Base URL is finding out what is the OpenID `.well-known` URL of your provider. For example, for Google it's `https://accounts.google.com/.well-known/openid-configuration`, in this case, the Base URL would be `https://accounts.google.com` (note the lack of a trailing slash). The part starting with `/.well-known` is added automatically, so it should be omitted from the Base URL. This is explained in more detail in the [Base URL](microsoft.md#base-url) section.
42
74
43
-
In order to get the **Client ID** and **Client Secret** values, refer to the documentation of your custom provider of choice.
When configuring your external OpenID provider, at some point you will need to provide a callback URL, which will redirect the user back to Defguard. This URL is in form of `<DEFGUARD_DASHBOARD_URL>/auth/callback`. Replace `<DEFGUARD_DASHBOARD_URL>` with the URL under which your dashboard is accessible, e.g. `https://defguard.example.com`. If you'd like to use OpenID enrollment through proxy too, make sure to enter an additional URI in the form of `<DEFGUARD_ENROLLMENT_URL>/openid/callback`.
46
77
47
-
If you're having issues with your custom provider's base URL, check Defguard's (core) logs. It should say what URL it expected.
78
+
7. You should be good to go now. Navigate to the directory sync settings in Defguard and try to test your setup using the test connection button.
0 commit comments