From f3d0151a55eaf1f968dda0072b16c811ebb384df Mon Sep 17 00:00:00 2001 From: Tor Colvin Date: Mon, 7 Apr 2025 13:05:39 -0400 Subject: [PATCH 1/6] DOC-11383 clarify use of admin_channels with collection_access --- docs/api/components/schemas.yaml | 96 +++++++++++++++----------------- 1 file changed, 45 insertions(+), 51 deletions(-) diff --git a/docs/api/components/schemas.yaml b/docs/api/components/schemas.yaml index d231a50189..2e7d907e75 100644 --- a/docs/api/components/schemas.yaml +++ b/docs/api/components/schemas.yaml @@ -252,6 +252,7 @@ User: User names can only have alphanumeric ASCII characters and underscores. type: string + required: true password: description: |- The password of the user. @@ -259,35 +260,27 @@ User: Mandatory. unless `allow_empty_password` is `true` in the database configs. type: string admin_channels: - description: A list of channels to explicitly grant to the user for the default collection. + description: A list of channels to explicitly grant to the user for the default collection. See `collection_access` for channels in named collections. type: array items: type: string all_channels: description: |- - All the channels that the user has been granted access to for the default collection. + All the channels that the user has been granted access to for the default collection. See `collection_access` for channels in named collections. Access could have been granted through the sync function, roles, or explicitly on the user under the `admin_channels` property. type: array items: type: string readOnly: true - collection_access: - description: A set of access grants by scope and collection. - type: object - additionalProperties: - x-additionalPropertiesName: scopename - description: An object keyed by scope, containing a set of collections. - type: object - additionalProperties: - x-additionalPropertiesName: collectionname - $ref: '#/CollectionAccessConfig' + $ref: '#/CollectionAccessConfig' email: description: The email address of the user. type: string disabled: description: 'If true, the user will not be able to login to the account as it is disabled.' type: boolean + default: false admin_roles: description: A list of roles to explicitly grant to the user. type: array @@ -325,34 +318,44 @@ User: readOnly: true title: User CollectionAccessConfig: - description: An object keyed by collection name, defines access for the collection. - type: object - properties: - admin_channels: - description: A list of channels to explicitly grant to the user. - type: array - items: - type: string - all_channels: - description: |- - All the channels that the user has been granted access to. + collection_access: + description: A set of access grants by scope and collection for a specific collection. + type: object + additionalProperties: + maxProperties: 1 + description: An object keyed by scope, containing a set of collections. + type: object + x-additionalPropertiesName: scopename + additionalProperties: + description: An object keyed by collection name, defines access collections in this scope. + type: object + x-additionalPropertiesName: collectionname + properties: + admin_channels: + description: A list of channels to explicitly grant to the user in this collection. + type: array + items: + type: string + all_channels: + description: |- + All the channels that the user has been granted access to in this collection. - Access could have been granted through the sync function, roles, or explicitly on the user under the `admin_channels` property. - type: array - items: - type: string - readOnly: true - jwt_channels: - description: The channels that the user has been granted access to through channels_claim. - type: array - items: - type: string - readOnly: true - jwt_last_updated: - description: The last time that the user's JWT roles/channels were updated. - type: string - format: date-time - readOnly: true + Access could have been granted through the sync function, roles, or explicitly on the user under the `admin_channels` property. + type: array + items: + type: string + readOnly: true + jwt_channels: + description: The channels that the user has been granted access to through channels_claim. + type: array + items: + type: string + readOnly: true + jwt_last_updated: + description: The last time that the user's JWT roles/channels were updated. + type: string + format: date-time + readOnly: true Role: description: Properties associated with a role type: object @@ -364,29 +367,20 @@ Role: Role names can only have alphanumeric ASCII characters and underscores. type: string admin_channels: - description: The channels that users in the role are able to access for the default collection. + description: The channels that users in the role are able to access for the default collection. Use `collection_access.scopename.collectionname.admin_channels` for channels in named collections. type: array items: type: string all_channels: description: |- - The channels that the role grants access to for the default collection. + The channels that the role grants access to for the default collection. See `collection_access.scopename.collectionname` for channels in named collections. These channels could have been assigned by the Sync function or using the `admin_channels` property. type: array items: type: string readOnly: true - collection_access: - description: A set of access grants by scope and collection. - type: object - additionalProperties: - x-additionalPropertiesName: scopename - description: An object keyed by scope, containing a set of collections. - type: object - additionalProperties: - x-additionalPropertiesName: collectionname - $ref: '#/CollectionAccessConfig' + $ref: '#/CollectionAccessConfig' title: Role User-session-information: type: object From e3c40e59117cfc98b5654f0c469e7dacd66cd2a1 Mon Sep 17 00:00:00 2001 From: Tor Colvin Date: Mon, 7 Apr 2025 13:43:48 -0400 Subject: [PATCH 2/6] properties can't be required --- docs/api/components/schemas.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/api/components/schemas.yaml b/docs/api/components/schemas.yaml index 2e7d907e75..03f18953fd 100644 --- a/docs/api/components/schemas.yaml +++ b/docs/api/components/schemas.yaml @@ -252,7 +252,6 @@ User: User names can only have alphanumeric ASCII characters and underscores. type: string - required: true password: description: |- The password of the user. From 5d8273de0daf8c08dbbead162c3d58d8baa67378 Mon Sep 17 00:00:00 2001 From: Tor Colvin Date: Tue, 8 Apr 2025 09:40:39 -0400 Subject: [PATCH 3/6] Update docs/api/components/schemas.yaml Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com> --- docs/api/components/schemas.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/api/components/schemas.yaml b/docs/api/components/schemas.yaml index 03f18953fd..6120252839 100644 --- a/docs/api/components/schemas.yaml +++ b/docs/api/components/schemas.yaml @@ -259,7 +259,9 @@ User: Mandatory. unless `allow_empty_password` is `true` in the database configs. type: string admin_channels: - description: A list of channels to explicitly grant to the user for the default collection. See `collection_access` for channels in named collections. + description: |- + A list of channels to explicitly grant to the user for the default collection. + See `collection_access` for channels in named collections. type: array items: type: string From 81c11173b1b99c073bf36bbfe8b8e16eb10f580d Mon Sep 17 00:00:00 2001 From: Tor Colvin Date: Tue, 8 Apr 2025 09:40:46 -0400 Subject: [PATCH 4/6] Update docs/api/components/schemas.yaml Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com> --- docs/api/components/schemas.yaml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/api/components/schemas.yaml b/docs/api/components/schemas.yaml index 6120252839..28ff8b31b9 100644 --- a/docs/api/components/schemas.yaml +++ b/docs/api/components/schemas.yaml @@ -368,7 +368,9 @@ Role: Role names can only have alphanumeric ASCII characters and underscores. type: string admin_channels: - description: The channels that users in the role are able to access for the default collection. Use `collection_access.scopename.collectionname.admin_channels` for channels in named collections. + description: |- + The channels that users in the role are able to access for the default collection. + Use `collection_access.scopename.collectionname.admin_channels` for channels in named collections. type: array items: type: string From 6652f4d9106294624c19843d31a7cbfff8b7069a Mon Sep 17 00:00:00 2001 From: Tor Colvin Date: Tue, 8 Apr 2025 09:40:55 -0400 Subject: [PATCH 5/6] Update docs/api/components/schemas.yaml Co-authored-by: Simon Dew <39966290+simon-dew@users.noreply.github.com> --- docs/api/components/schemas.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/api/components/schemas.yaml b/docs/api/components/schemas.yaml index 28ff8b31b9..2b681ee536 100644 --- a/docs/api/components/schemas.yaml +++ b/docs/api/components/schemas.yaml @@ -267,7 +267,8 @@ User: type: string all_channels: description: |- - All the channels that the user has been granted access to for the default collection. See `collection_access` for channels in named collections. + All the channels that the user has been granted access to for the default collection. + See `collection_access` for channels in named collections. Access could have been granted through the sync function, roles, or explicitly on the user under the `admin_channels` property. type: array From e39d4708cab6cd30913386f2c99531918fa0c294 Mon Sep 17 00:00:00 2001 From: Tor Colvin Date: Thu, 24 Apr 2025 09:27:30 -0400 Subject: [PATCH 6/6] add additional info to jwt, match user/role text --- docs/api/components/schemas.yaml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/api/components/schemas.yaml b/docs/api/components/schemas.yaml index da0eb3aee0..e0b95d0024 100644 --- a/docs/api/components/schemas.yaml +++ b/docs/api/components/schemas.yaml @@ -304,7 +304,7 @@ User: type: string readOnly: true jwt_channels: - description: The channels that the user has been granted access to through channels_claim. + description: The channels that the user has been granted access to through channels_claim for the default collection. type: array items: type: string @@ -348,13 +348,13 @@ CollectionAccessConfig: type: string readOnly: true jwt_channels: - description: The channels that the user has been granted access to through channels_claim. + description: The channels that the user has been granted access to through channels_claim for this collection. type: array items: type: string readOnly: true jwt_last_updated: - description: The last time that the user's JWT roles/channels were updated. + description: The last time that the user's JWT channels were updated for this collection. type: string format: date-time readOnly: true @@ -370,14 +370,14 @@ Role: type: string admin_channels: description: |- - The channels that users in the role are able to access for the default collection. - Use `collection_access.scopename.collectionname.admin_channels` for channels in named collections. + A list of channels to explicitly grant to the role for the default collection. + See `collection_access` for channels in named collections. type: array items: type: string all_channels: description: |- - The channels that the role grants access to for the default collection. See `collection_access.scopename.collectionname` for channels in named collections. + All the channels that the role has been granted access to for the default collection. These channels could have been assigned by the Sync function or using the `admin_channels` property. type: array