diff --git a/proto/caosdb/CMakeLists.txt b/proto/caosdb/CMakeLists.txt index 870d96e23c6b06026f05b84c928e0392bcd1c108..f7fa61531e3c135afc139c41337d8a59a3cca39f 100644 --- a/proto/caosdb/CMakeLists.txt +++ b/proto/caosdb/CMakeLists.txt @@ -21,6 +21,7 @@ set(CAOSDB_API_PACKAGES caosdb.info.v1 caosdb.entity.v1 + caosdb.acm.v1alpha1 ) # pass variable to parent scope diff --git a/proto/caosdb/acm/v1alpha1/main.proto b/proto/caosdb/acm/v1alpha1/main.proto new file mode 100644 index 0000000000000000000000000000000000000000..e6a1d9a84600d8eda8babf2e758e51ae8e25f896 --- /dev/null +++ b/proto/caosdb/acm/v1alpha1/main.proto @@ -0,0 +1,391 @@ +// +// This file is a part of the CaosDB Project. +// +// Copyright (C) 2021 Timm Fitschen <t.fitschen@indiscale.com> +// Copyright (C) 2021 IndiScale GmbH <info@indiscale.com> +// +// This program is free software: you can redistribute it and/or modify +// it under the terms of the GNU Affero General Public License as +// published by the Free Software Foundation, either version 3 of the +// License, or (at your option) any later version. +// +// This program is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +// GNU Affero General Public License for more details. +// +// You should have received a copy of the GNU Affero General Public License +// along with this program. If not, see <https://www.gnu.org/licenses/>. +// + +// This is the main file of the caosdb.acm.v1alpha1 package. +syntax = "proto3"; +option java_multiple_files = true; +option java_package = "org.caosdb.api.acm.v1alpha1"; + +package caosdb.acm.v1alpha1; + +/////////////////////////////////////////// +// COMMON MESSAGES +/////////////////////////////////////////// + +// Client preferences for the paging. The server MUST respect the index +// property or send the complete result set. The server MAY choose to send a +// different page length in the response +message PagingRequest { + // Desired index of the first element in the response. The index depends on + // the order of the elements in the result set. + int32 index = 1; + // Desired length of the page in the server response. + int32 page_length = 2; +} + +// The actual paging of the response. +message PagingResponse { + // Total numbers of results. + int32 total_number = 1; + // Index of the first item in the page. + int32 current_index = 2; +} + +/////////////////////////////////////////// +// PERMISSSIONS +/////////////////////////////////////////// + +// Request to list all known permissions (excluding entity permissions). +message ListKnownPermissionsRequest {} + +// Response with all known permissions. Clients may choose to create drop-down +// menues from this list. +message ListKnownPermissionsResponse { + // known permissions + repeated PermissionDescription permissions = 1; +} + +// Description of a permission. +message PermissionDescription { + // The permission + string permission = 1; + // The description + string description = 2; +} + +// PermissionRule. These belong to Roles. +message PermissionRule { + // The permission which is being granted oder denied. + string permission = 1; + // Priority permission rules (TRUE) overrule non-priority (FALSE) permission + // rules. + bool priority = 2; + // True means that the permission is being granted by this rule, false means + // the permission is being DENIED! + bool grant = 3; +} + +/////////////////////////////////////////// +// ROLES +/////////////////////////////////////////// + +// Role +message Role { + // Unique name of this role. + string name = 1; + // Description of the purpose of this role or which group of users this role + // represents. + string description = 2; + // List of permission rules for this role. + repeated PermissionRule permission_rules = 3; +} + +// Request message for the ListRoles RPC +message ListRolesRequest { + // Desired paging settings for the response. + PagingRequest paging = 1; +} + +// Response message for the ListRoles RPC +message ListRolesResponse { + // Actual paging setting of the response. + PagingResponse paging = 1; + // A subset (when paging is used) or the complete set (otherwise) of roles. + repeated ListRoleItem roles = 2; +} + +// Combines role, the role's capabilities and the current users permissions. +message ListRoleItem { + // Role + Role role = 1; + // The permissions of the user of the current session w.r.t. this role. + repeated RolePermissions permissions = 2; + // What can be done with this role. + repeated RoleCapabilities capabilities = 3; +} + +// Request message for the CreateSingleRole RPC +message CreateSingleRoleRequest { + // The new role. + Role role = 1; +} + +// Response message for the CreateSingleRole RPC +message CreateSingleRoleResponse {} + +// Request message for the RetrieveSingleRole RPC +message RetrieveSingleRoleRequest { + // the name of the role. + string name = 1; +} + +// Response message for the RetrieveSingleRole RPC +message RetrieveSingleRoleResponse { + // The role. + Role role = 1; + // Known users with this role + repeated User users = 2; + // The permissions of the user of the current session w.r.t. this role. + repeated RolePermissions permissions = 3; + // What can be do with this role. + repeated RoleCapabilities capabilities = 4; +} + +// Request message for the UpdateSingleRole RPC +message UpdateSingleRoleRequest { + // The role + Role role = 1; +} +// Response message for the UpdateSingleRole RPC +message UpdateSingleRoleResponse {} + +// Request message for the DeleteSingleRole RPC +message DeleteSingleRoleRequest { + // the name of the role. + string name = 1; +} + +// Response message for the DeleteSingleRole RPC +message DeleteSingleRoleResponse {} + +// Role Permissions +enum RolePermissions { + // Unspecified permission + ROLE_PERMISSIONS_UNSPECIFIED = 0; + // Role can be deleted + ROLE_PERMISSIONS_DELETE = 1; + // Description can be updated + ROLE_PERMISSIONS_UPDATE_DESCRIPTION = 2; + // Permission rules of this role can be updated + ROLE_PERMISSIONS_UPDATE_PERMISSION_RULES = 3; + // This role can be assigned + ROLE_PERMISSIONS_ASSIGN = 4; +} + +// Role Capabilities +enum RoleCapabilities { + // Unspecified capability + ROLE_CAPABILITIES_UNSPECIFIED = 0; + // This role is deletable + ROLE_CAPABILITIES_DELETE = 1; + // This role's permissions can be changed + ROLE_CAPABILITIES_UPDATE_PERMISSION_RULES = 2; + // This role can be assigned to a user + ROLE_CAPABILITIES_ASSIGN = 3; +} + +/////////////////////////////////////////// +// USERS +/////////////////////////////////////////// + +// UserStatus +enum UserStatus { + // The user status is unspecified/unknown. + USER_STATUS_UNSPECIFIED = 0; + // The user is inactive and cannot sign in. + USER_STATUS_INACTIVE = 1; + // The user is active and can sign in. + USER_STATUS_ACTIVE = 2; +} + +// PasswordSetting - it is handy to have this as a separate message b/c +// otherwise we could not distinguish between empty string and an unspecified +// password. +message PasswordSetting { + // The password + string password = 1; +} + +// EmailSetting - it is handy to have this as a separate message b/c otherwise +// we could not distinguish between empty string and an unspecified email. +message EmailSetting { + // The email adress + string email = 1; +} + +// EntitySetting - it is handy to have this as a separate message b/c otherwise +// we could not distinguish between empty string and an unspecified entity. +message EntitySetting { + // The entity which represents this user (e.g. a Person or Device Record). + string entity_id = 1; +} + +// User +message User { + // Indicates whether the user is active. Only active users can sign in and + // interact with the CaosDB Server. + UserStatus status = 1; + // Realm of this user. The realm is the authority which can authenticate this + // user, e.g. 'PAM' when the user is a (POSIX) user from the server's host, or + // 'CaosDB' when CaosDB server itself can authenticate the user. + string realm = 2; + // Name of this user. + string name = 3; + // Email setting of this user. + EmailSetting email_setting = 4; + // Entity setting of this user. + EntitySetting entity_setting = 5; + // List of roles of this user. + repeated string roles = 6; +} + +// Request message for the ListUsers RPC. +message ListUsersRequest { + // Desired paging settings for the response. + PagingRequest paging = 1; +} + +// Response message for the ListUsers RPC. +message ListUsersResponse { + // Actual paging setting of the response. + PagingResponse paging = 1; + // A subset (when paging is used) or the complete set (otherwise) of known + // users. + repeated User users = 2; +} + +// Request message for the CreateSingleUser RPC +message CreateSingleUserRequest { + // The new user. + User user = 1; + // The new password. + PasswordSetting password_setting = 2; +} + +// Response message for the CreateSingleUser RPC +message CreateSingleUserResponse {} + +// Request message for the RetrieveSingleUser RPC +message RetrieveSingleUserRequest { + // The user's realm + string realm = 1; + // The user's name + string name = 2; +} + +// Response message for the RetrieveSingleUser RPC +message RetrieveSingleUserResponse { + // The user + User user = 1; + // The permissions of the user of the current session. + repeated UserPermissions permissions = 2; + // What can be done with this user + repeated UserCapabilities capabilities = 3; +} + +// Request message for the UpdateSingleUser RPC +message UpdateSingleUserRequest { + // The new user. + User user = 1; + // The new password. Password will not be updated when this is unset. + PasswordSetting password_setting = 2; +} + +// Response message for the UpdateSingleUser RPC +message UpdateSingleUserResponse {} + +// Request message for the DeleteSingleUser RPC +message DeleteSingleUserRequest { + // The user's realm + string realm = 1; + // The user's name + string name = 2; +} + +// Response message for the DeleteSingleUser RPC +message DeleteSingleUserResponse {} + +// Permissions for updating and deleting a user. +enum UserPermissions { + // Unspecified permission + USER_PERMISSIONS_UNSPECIFIED = 0; + // The user can be deleted. + USER_PERMISSIONS_DELETE = 1; + // The password of the user can be updated. + USER_PERMISSIONS_UPDATE_PASSWORD = 2; + // The email of the user can be updated. + USER_PERMISSIONS_UPDATE_EMAIL = 3; + // The status (active/inactive) of the user can be changed. + USER_PERMISSIONS_UPDATE_STATUS = 4; + // The roles of the user can be altered. + USER_PERMISSIONS_UPDATE_ROLES = 5; + // Ths entity of the user can be set. + USER_PERMISSIONS_UPDATE_ENTITY = 6; +} + +// What can be done with a user (generally speaking, if permissions suffice). +enum UserCapabilities { + // Unspecified capability + USER_CAPABILITIES_UNSPECIFIED = 0; + // User can be deleted. + USER_CAPABILITIES_DELETE = 1; + // The user's password can be updated. + USER_CAPABILITIES_UPDATE_PASSWORD = 2; +} + +/////////////////////////////////////////// +// SERVICE DEFINITION +/////////////////////////////////////////// + +// A service for managing the access to the CaosDB Server via user accounts, +// roles and permissions. +service AccessControlManagementService { + // Request the list of known users. + rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) {}; + + // Retrieve a single user + rpc RetrieveSingleUser(RetrieveSingleUserRequest) + returns (RetrieveSingleUserResponse) {}; + + // Create a single new user + rpc CreateSingleUser(CreateSingleUserRequest) + returns (CreateSingleUserResponse) {}; + + // Update a single user + rpc UpdateSingleUser(UpdateSingleUserRequest) + returns (UpdateSingleUserResponse) {}; + + // Delete a single user + rpc DeleteSingleUser(DeleteSingleUserRequest) + returns (DeleteSingleUserResponse) {}; + + // Request the list of roles. + rpc ListRoles(ListRolesRequest) returns (ListRolesResponse) {}; + + // Retrieve a single role + rpc RetrieveSingleRole(RetrieveSingleRoleRequest) + returns (RetrieveSingleRoleResponse) {}; + + // Create a single new role + rpc CreateSingleRole(CreateSingleRoleRequest) + returns (CreateSingleRoleResponse) {}; + + // Update a single role + rpc UpdateSingleRole(UpdateSingleRoleRequest) + returns (UpdateSingleRoleResponse) {}; + + // Delete a single role + rpc DeleteSingleRole(DeleteSingleRoleRequest) + returns (DeleteSingleRoleResponse) {}; + + // List all known permissions + rpc ListKnownPermissions(ListKnownPermissionsRequest) + returns (ListKnownPermissionsResponse) {}; +} diff --git a/proto/caosdb/entity/v1/main.proto b/proto/caosdb/entity/v1/main.proto index dd5b0b28bc03d0b5debb5a7bc4b4ced0cee67557..6380a1ca80d0c942afd4b7ef15f24c24c01ed5fa 100644 --- a/proto/caosdb/entity/v1/main.proto +++ b/proto/caosdb/entity/v1/main.proto @@ -691,11 +691,143 @@ message MultiTransactionResponse { repeated Message transaction_infos = 4; } +// Request of the MultiRetrieveEntityACL rpc +message MultiRetrieveEntityACLRequest { + // The requested entity ids. + repeated string id = 1; +} + +// Response of the MultiRetrieveEntityACL rpc +message MultiRetrieveEntityACLResponse { + // The entities ACLs + repeated EntityACL acls = 1; +} + +// Request of the MultiUpdateEntityACL rpc +message MultiUpdateEntityACLRequest { + // The requested entity ids. + repeated EntityACL acls = 1; +} + +// Response of the MultiUpdateEntityACL rpc +message MultiUpdateEntityACLResponse {} + +// Entity Access Controll List (ACL) +message EntityACL { + // The entity id + string id = 1; + // The rules which make up the ACL + repeated EntityPermissionRule rules = 2; + // relevant permissions of the current session, e.g. if the current user is + // allowed to update the ACL. This is read-only and will be ignored by the + // server. + EntityAclPermission permission = 3; +} + +// Entity ACL Permission indicates whether the current user is allowed to update +// the Entity's ACL. +enum EntityAclPermission { + // UNSPECIFIED, effectively means "NO" + ENTITY_ACL_PERMISSION_UNSPECIFIED = 0; + // Non-priority rules may be edited. + ENTITY_ACL_PERMISSION_EDIT_ACL = 1; + // Priority and non-priority rules may be edited. + ENTITY_ACL_PERMISSION_EDIT_PRIORITY_ACL = 2; +} + +// Permission rules for Entity ACL +message EntityPermissionRule { + // The role for which this rule applies + string role = 1; + // Is priority? + bool priority = 2; + // Is grant? + bool grant = 3; + // permissions + repeated EntityPermission permissions = 4; + // capabilities + repeated EntityPermissionRuleCapability capabilities = 5; +} + +// What (given enough permissions) can be done with an EntityPermissionRule. +// E.g. globel entity permission rules, which are to be specified in a +// configuration file cannot be deleted, thus they are missing the +// ENTITY_PERMISSION_RULE_CAPABILITY_DELETE capability. +enum EntityPermissionRuleCapability { + // Unspecified capability. + ENTITY_PERMISSION_RULE_CAPABILITY_UNSPECIFIED = 0; + // This permission rule can be deleted/removed from the ACL + ENTITY_PERMISSION_RULE_CAPABILITY_DELETE = 1; +} + +// Entity permissions +enum EntityPermission { + // Unspecified permission. + ENTITY_PERMISSION_UNSPECIFIED = 0; + // Permission to retrieve the full entity (name, description, data type, ...) + // with all parents and properties (unless prohibited by another rule on the + // property level). + ENTITY_PERMISSION_RETRIEVE_ENTITY = 1; + // Permission to retrieve the full and final ACL of this entity. + ENTITY_PERMISSION_RETRIEVE_ACL = 2; + // Permission to retrieve the history of this entity. + ENTITY_PERMISSION_RETRIEVE_HISTORY = 3; + // Permission to retrieve the owner(s) of this entity. + ENTITY_PERMISSION_RETRIEVE_OWNER = 4; + // Permission to download the file belonging to this entity. + ENTITY_PERMISSION_RETRIEVE_FILE = 5; + // Permission to delete an entity. + ENTITY_PERMISSION_DELETE = 6; + // Permission to change the user-specified part of this entity's ACL. Roles + // with this Permission are called 'Owners'. + ENTITY_PERMISSION_EDIT_ACL = 7; + // Permission to change the value of this entity. + ENTITY_PERMISSION_UPDATE_DESCRIPTION = 8; + // Permission to change the value of this entity. + ENTITY_PERMISSION_UPDATE_VALUE = 9; + // Permission to change the role of this entity. + ENTITY_PERMISSION_UPDATE_ROLE = 10; + // Permission to remove parents from this entity. + ENTITY_PERMISSION_UPDATE_REMOVE_PARENT = 11; + // Permission to add a parent to this entity. + ENTITY_PERMISSION_UPDATE_ADD_PARENT = 12; + // Permission to remove properties from this entity. + ENTITY_PERMISSION_UPDATE_REMOVE_PROPERTY = 13; + // Permission to add a property to this entity. + ENTITY_PERMISSION_UPDATE_ADD_PROPERTY = 14; + // Permission to change the name of this entity. + ENTITY_PERMISSION_UPDATE_NAME = 15; + // Permission to change the data type of this entity. + ENTITY_PERMISSION_UPDATE_DATA_TYPE = 16; + // Permission to delete the file of this entity. + ENTITY_PERMISSION_UPDATE_REMOVE_FILE = 17; + // Permission to set a file for this entity. + ENTITY_PERMISSION_UPDATE_ADD_FILE = 18; + // Permission to move an existing file to a new location. + ENTITY_PERMISSION_UPDATE_MOVE_FILE = 19; + // Permission to refer to this entity via a reference property. + ENTITY_PERMISSION_USE_AS_REFERENCE = 20; + // Permission to implement this entity as a property. + ENTITY_PERMISSION_USE_AS_PROPERTY = 21; + // Permission to use this entity as a super type for other entities. + ENTITY_PERMISSION_USE_AS_PARENT = 22; + // Permission to use this entity as a data type for reference properties. + ENTITY_PERMISSION_USE_AS_DATA_TYPE = 23; + // Permission to update the query template definition of this QueryTemplate + ENTITY_PERMISSION_UPDATE_QUERY_TEMPLATE_DEFINITION = 24; +} + // Entity Transaction Service service EntityTransactionService { // Issue multiple mixed requests rpc MultiTransaction(MultiTransactionRequest) returns (MultiTransactionResponse); + // Request the Entity ACLs + rpc MultiRetrieveEntityACL(MultiRetrieveEntityACLRequest) + returns (MultiRetrieveEntityACLResponse); + // Set the Entity ACLs, + rpc MultiUpdateEntityACL(MultiUpdateEntityACLRequest) + returns (MultiUpdateEntityACLResponse); } /////////////////////////////////////////////////////////////////////////// diff --git a/proto/caosdb/info/v1/main.proto b/proto/caosdb/info/v1/main.proto index 9af2d93a6de624492c9a88c430f6561101942670..ab3b2947cac7a225237d2ca973776cb6f099064a 100644 --- a/proto/caosdb/info/v1/main.proto +++ b/proto/caosdb/info/v1/main.proto @@ -25,6 +25,8 @@ option java_package = "org.caosdb.api.info.v1"; package caosdb.info.v1; +/////////////////////////////// SERVER VERSION + // The version of an agent (following SemVer 2.0.0) message VersionInfo { // Major version number @@ -48,8 +50,29 @@ message GetVersionInfoResponse { VersionInfo version_info = 1; } +////////////////////////// SESSION + +// Request message for the GetSessionInfo RPC +message GetSessionInfoRequest {} + +// Response message for the GetSessionInfo RPC +message GetSessionInfoResponse { + // The realm of the user who owns this session + string realm = 1; + // The name of the user who owns this session + string username = 2; + // The roles of the user who owns this session + repeated string roles = 3; + // Seconds until this sessions expires (approximately). + int64 expires = 4; + // The permissions of the user who owns this sessions + repeated string permissions = 5; +} + // A service which provides general information about the server. service GeneralInfoService { // Request the detailed version information from the server. rpc GetVersionInfo(GetVersionInfoRequest) returns (GetVersionInfoResponse) {}; + // Request information about the current session (user, roles, timeout...). + rpc GetSessionInfo(GetSessionInfoRequest) returns (GetSessionInfoResponse) {}; }