From 40f12aeca39cdad1a9d99dcd0cc166be9514bc27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E3=82=B1=E3=82=A4=E3=83=A9?= Date: Wed, 27 Nov 2024 14:39:03 -0700 Subject: [PATCH] chore: update group and role sync notes (#15658) --- coderd/apidoc/docs.go | 8 ++++---- coderd/apidoc/swagger.json | 8 ++++---- codersdk/idpsync.go | 14 ++++++-------- docs/reference/api/schemas.md | 14 +++++++------- 4 files changed, 21 insertions(+), 23 deletions(-) diff --git a/coderd/apidoc/docs.go b/coderd/apidoc/docs.go index fe5d7c6384..f814b25d99 100644 --- a/coderd/apidoc/docs.go +++ b/coderd/apidoc/docs.go @@ -11126,7 +11126,7 @@ const docTemplate = `{ "type": "boolean" }, "field": { - "description": "Field selects the claim field to be used as the created user's\ngroups. If the group field is the empty string, then no group updates\nwill ever come from the OIDC provider.", + "description": "Field is the name of the claim field that specifies what groups a user\nshould be in. If empty, no groups will be synced.", "type": "string" }, "legacy_group_name_mapping": { @@ -11137,7 +11137,7 @@ const docTemplate = `{ } }, "mapping": { - "description": "Mapping maps from an OIDC group --\u003e Coder group ID", + "description": "Mapping is a map from OIDC groups to Coder group IDs", "type": "object", "additionalProperties": { "type": "array", @@ -12931,11 +12931,11 @@ const docTemplate = `{ "type": "object", "properties": { "field": { - "description": "Field selects the claim field to be used as the created user's\ngroups. If the group field is the empty string, then no group updates\nwill ever come from the OIDC provider.", + "description": "Field is the name of the claim field that specifies what organization roles\na user should be given. If empty, no roles will be synced.", "type": "string" }, "mapping": { - "description": "Mapping maps from an OIDC group --\u003e Coder organization role", + "description": "Mapping is a map from OIDC groups to Coder organization roles.", "type": "object", "additionalProperties": { "type": "array", diff --git a/coderd/apidoc/swagger.json b/coderd/apidoc/swagger.json index 04af1b4015..4f439e472f 100644 --- a/coderd/apidoc/swagger.json +++ b/coderd/apidoc/swagger.json @@ -9983,7 +9983,7 @@ "type": "boolean" }, "field": { - "description": "Field selects the claim field to be used as the created user's\ngroups. If the group field is the empty string, then no group updates\nwill ever come from the OIDC provider.", + "description": "Field is the name of the claim field that specifies what groups a user\nshould be in. If empty, no groups will be synced.", "type": "string" }, "legacy_group_name_mapping": { @@ -9994,7 +9994,7 @@ } }, "mapping": { - "description": "Mapping maps from an OIDC group --\u003e Coder group ID", + "description": "Mapping is a map from OIDC groups to Coder group IDs", "type": "object", "additionalProperties": { "type": "array", @@ -11696,11 +11696,11 @@ "type": "object", "properties": { "field": { - "description": "Field selects the claim field to be used as the created user's\ngroups. If the group field is the empty string, then no group updates\nwill ever come from the OIDC provider.", + "description": "Field is the name of the claim field that specifies what organization roles\na user should be given. If empty, no roles will be synced.", "type": "string" }, "mapping": { - "description": "Mapping maps from an OIDC group --\u003e Coder organization role", + "description": "Mapping is a map from OIDC groups to Coder organization roles.", "type": "object", "additionalProperties": { "type": "array", diff --git a/codersdk/idpsync.go b/codersdk/idpsync.go index 6d34714bc5..3a2e707ccb 100644 --- a/codersdk/idpsync.go +++ b/codersdk/idpsync.go @@ -12,11 +12,10 @@ import ( ) type GroupSyncSettings struct { - // Field selects the claim field to be used as the created user's - // groups. If the group field is the empty string, then no group updates - // will ever come from the OIDC provider. + // Field is the name of the claim field that specifies what groups a user + // should be in. If empty, no groups will be synced. Field string `json:"field"` - // Mapping maps from an OIDC group --> Coder group ID + // Mapping is a map from OIDC groups to Coder group IDs Mapping map[string][]uuid.UUID `json:"mapping"` // RegexFilter is a regular expression that filters the groups returned by // the OIDC provider. Any group not matched by this regex will be ignored. @@ -62,11 +61,10 @@ func (c *Client) PatchGroupIDPSyncSettings(ctx context.Context, orgID string, re } type RoleSyncSettings struct { - // Field selects the claim field to be used as the created user's - // groups. If the group field is the empty string, then no group updates - // will ever come from the OIDC provider. + // Field is the name of the claim field that specifies what organization roles + // a user should be given. If empty, no roles will be synced. Field string `json:"field"` - // Mapping maps from an OIDC group --> Coder organization role + // Mapping is a map from OIDC groups to Coder organization roles. Mapping map[string][]string `json:"mapping"` } diff --git a/docs/reference/api/schemas.md b/docs/reference/api/schemas.md index 211dc9297f..35c677bccd 100644 --- a/docs/reference/api/schemas.md +++ b/docs/reference/api/schemas.md @@ -3026,10 +3026,10 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o | Name | Type | Required | Restrictions | Description | | ---------------------------- | ------------------------------ | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auto_create_missing_groups` | boolean | false | | Auto create missing groups controls whether groups returned by the OIDC provider are automatically created in Coder if they are missing. | -| `field` | string | false | | Field selects the claim field to be used as the created user's groups. If the group field is the empty string, then no group updates will ever come from the OIDC provider. | +| `field` | string | false | | Field is the name of the claim field that specifies what groups a user should be in. If empty, no groups will be synced. | | `legacy_group_name_mapping` | object | false | | Legacy group name mapping is deprecated. It remaps an IDP group name to a Coder group name. Since configuration is now done at runtime, group IDs are used to account for group renames. For legacy configurations, this config option has to remain. Deprecated: Use Mapping instead. | | » `[any property]` | string | false | | | -| `mapping` | object | false | | Mapping maps from an OIDC group --> Coder group ID | +| `mapping` | object | false | | Mapping is a map from OIDC groups to Coder group IDs | | » `[any property]` | array of string | false | | | | `regex_filter` | [regexp.Regexp](#regexpregexp) | false | | Regex filter is a regular expression that filters the groups returned by the OIDC provider. Any group not matched by this regex will be ignored. If the group filter is nil, then no group filtering will occur. | @@ -4876,11 +4876,11 @@ CreateWorkspaceRequest provides options for creating a new workspace. Only one o ### Properties -| Name | Type | Required | Restrictions | Description | -| ------------------ | --------------- | -------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `field` | string | false | | Field selects the claim field to be used as the created user's groups. If the group field is the empty string, then no group updates will ever come from the OIDC provider. | -| `mapping` | object | false | | Mapping maps from an OIDC group --> Coder organization role | -| » `[any property]` | array of string | false | | | +| Name | Type | Required | Restrictions | Description | +| ------------------ | --------------- | -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- | +| `field` | string | false | | Field is the name of the claim field that specifies what organization roles a user should be given. If empty, no roles will be synced. | +| `mapping` | object | false | | Mapping is a map from OIDC groups to Coder organization roles. | +| » `[any property]` | array of string | false | | | ## codersdk.SSHConfig