feat: add group mapping option for group sync (#6705)

* feat: add group mapping option for group sync

* fixup! feat: add group mapping option for group sync

docs/admin/auth.md

@@ -197,4 +197,20 @@ CODER_OIDC_SCOPES=openid,profile,email,groups
 On login, users will automatically be assigned to groups that have matching
 names in Coder and removed from groups that the user no longer belongs to.
 
+For cases when an OIDC provider only returns group IDs ([Azure AD][azure-gids])
+or you want to have different group names in Coder than in your OIDC provider,
+you can configure mapping between the two.
+
+```console
+# as an environment variable
+CODER_OIDC_GROUP_MAPPING='{"myOIDCGroupID": "myCoderGroupName"}'
+# as a flag
+--oidc-group-mapping '{"myOIDCGroupID": "myCoderGroupName"}'
+```
+
+From the example above, users that belong to the `myOIDCGroupID` group in your
+OIDC provider will be added to the `myCoderGroupName` group in Coder.
+
 > **Note:** Groups are only updated on login.
+
+[azure-gids]: https://github.com/MicrosoftDocs/azure-docs/issues/59766#issuecomment-664387195

docs/api/general.md

@@ -234,6 +234,7 @@ curl -X GET http://coder-server:8080/api/v2/deployment/config \
       "client_id": "string",
       "client_secret": "string",
       "email_domain": ["string"],
+      "group_mapping": {},
       "groups_field": "string",
       "icon_url": {
         "forceQuery": true,

docs/api/schemas.md

@@ -1766,6 +1766,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a
       "client_id": "string",
       "client_secret": "string",
       "email_domain": ["string"],
+      "group_mapping": {},
       "groups_field": "string",
       "icon_url": {
         "forceQuery": true,
@@ -2110,6 +2111,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a
     "client_id": "string",
     "client_secret": "string",
     "email_domain": ["string"],
+    "group_mapping": {},
     "groups_field": "string",
     "icon_url": {
       "forceQuery": true,
@@ -2771,6 +2773,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a
   "client_id": "string",
   "client_secret": "string",
   "email_domain": ["string"],
+  "group_mapping": {},
   "groups_field": "string",
   "icon_url": {
     "forceQuery": true,
@@ -2801,6 +2804,7 @@ CreateParameterRequest is a structure used to create a new parameter value for a
 | `client_id`             | string                     | false    |              |             |
 | `client_secret`         | string                     | false    |              |             |
 | `email_domain`          | array of string            | false    |              |             |
+| `group_mapping`         | object                     | false    |              |             |
 | `groups_field`          | string                     | false    |              |             |
 | `icon_url`              | [clibase.URL](#clibaseurl) | false    |              |             |
 | `ignore_email_verified` | boolean                    | false    |              |             |