// M-Files Server gRPC API 26.11. Generated from the M-Files Server IDL; do not edit.
// Documentation: https://developer.m-files.com/APIs/gRPC-API/
syntax = "proto3";

package MFiles;

import "mfiles/api/annotations.proto";
import "mfiles/enums.proto";
import "mfiles/structs.proto";

option csharp_namespace = "MFiles.Grpc";
option go_package = "github.com/M-Files/mfiles-grpc-api/go/mfiles;mfiles";
option java_multiple_files = true;
option java_package = "com.mfiles.grpc";
option objc_class_prefix = "MF_";

// Manages the server's login accounts: list, add, modify and remove logins, force logouts, look up
// Windows accounts and groups, and handle password resets.
//
// Use this interface to add, modify and delete logins.
//
// A login account is the server-level identity (M-Files or Windows authentication, server roles,
// license type) that user accounts in vaults are linked to. This is the service behind the
// "Login Accounts" node of M-Files Admin. Applications rarely need it; provisioning and audit
// scripts can use it.
//
// **Sessions and rights.** A server-level session is enough (log in with `login_data.vault_guid` =
// `{00000000-0000-0000-0000-000000000000}`); a vault session works too. Most methods require the
// **system administrator** server role (server right `manage_logins` in
// [ServerAccess](mfiles:MFiles.ServerAccess)); a vault administrator does not have it, and the call
// fails with "Access denied. You do not have the server-level access rights required by this
// operation." (0x800400A8, 0x800407E4). Exceptions:
//
// - [GetLogins](mfiles:MFiles.IRPCLoginsAdmin.GetLogins) and
//   [GetLogin](mfiles:MFiles.IRPCLoginsAdmin.GetLogin) also serve callers without server rights,
//   with a narrower result (see their remarks). This is why a vault administrator can list logins.
// - [CreatePasswordResetRequest](mfiles:MFiles.IRPCLoginsAdmin.CreatePasswordResetRequest) and
//   [ResetPassword](mfiles:MFiles.IRPCLoginsAdmin.ResetPassword) need no session at all: they are
//   the "forgot password" flow of M-Files Web.
//
// Methods by task:
//
// - **Read logins**: [GetLogins](mfiles:MFiles.IRPCLoginsAdmin.GetLogins),
//   [GetLogin](mfiles:MFiles.IRPCLoginsAdmin.GetLogin),
//   [GetLoginsWithSessions](mfiles:MFiles.IRPCLoginsAdmin.GetLoginsWithSessions).
// - **Change logins**: [AddLogin](mfiles:MFiles.IRPCLoginsAdmin.AddLogin),
//   [ModifyLogin](mfiles:MFiles.IRPCLoginsAdmin.ModifyLogin),
//   [RemoveLogin](mfiles:MFiles.IRPCLoginsAdmin.RemoveLogin),
//   [ForceLogout](mfiles:MFiles.IRPCLoginsAdmin.ForceLogout).
// - **Passwords**: [GetPasswordHash](mfiles:MFiles.IRPCLoginsAdmin.GetPasswordHash),
//   [SetPasswordHash](mfiles:MFiles.IRPCLoginsAdmin.SetPasswordHash) (copy a password between
//   servers),
//   [CreatePasswordResetRequestAdmin](mfiles:MFiles.IRPCLoginsAdmin.CreatePasswordResetRequestAdmin),
//   [CreatePasswordResetRequest](mfiles:MFiles.IRPCLoginsAdmin.CreatePasswordResetRequest),
//   [ResetPassword](mfiles:MFiles.IRPCLoginsAdmin.ResetPassword).
// - **Windows and Active Directory lookups** (for picking Windows accounts and groups):
//   [GetDomainName](mfiles:MFiles.IRPCLoginsAdmin.GetDomainName),
//   [GetComputerName](mfiles:MFiles.IRPCLoginsAdmin.GetComputerName),
//   [GetAllDomains](mfiles:MFiles.IRPCLoginsAdmin.GetAllDomains),
//   [GetOrganizationalUnitsForDomain](mfiles:MFiles.IRPCLoginsAdmin.GetOrganizationalUnitsForDomain),
//   [GetWindowsGroups](mfiles:MFiles.IRPCLoginsAdmin.GetWindowsGroups),
//   [GetWindowsGroupMembers](mfiles:MFiles.IRPCLoginsAdmin.GetWindowsGroupMembers),
//   [GetFullNameAndEmail](mfiles:MFiles.IRPCLoginsAdmin.GetFullNameAndEmail).
//
// A login is identified by its account name: the user name for M-Files logins, the down-level logon
// name (domain and user name separated by a backslash) for Windows logins. Server roles and the enabled state are in [SRVROLES](mfiles:MFiles.SRVROLES):
// a login without `can_log_in` is disabled.
service IRPCLoginsAdmin {
	option (mfiles.api.service) = { book: "admin" level: LEVEL_SPECIALIZED title: "Server login accounts" };

	// Removes a login account from the server.
	//
	// - Requires the system administrator server role (server right `manage_logins`).
	// - The user accounts linked to the login in vaults are not removed; remove them per vault if
	//   needed.
	rpc RemoveLogin( RemoveLoginRequest ) returns ( RemoveLoginResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the Windows domain of the server computer, or the computer name if it is not in a domain.
	//
	// - Requires the system administrator server role (server right `manage_logins`). Denied for
	//   other callers.
	rpc GetDomainName( GetDomainNameRequest ) returns ( GetDomainNameResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the name of the server computer.
	//
	// - Requires the system administrator server role (server right `manage_logins`).
	rpc GetComputerName( GetComputerNameRequest ) returns ( GetComputerNameResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Looks up the full name and e-mail address of a Windows account in its directory.
	//
	// - Requires the system administrator server role (server right `manage_logins`).
	// - Reads the directory (Active Directory, or the user synchronization plug-in configured for the
	//   domain), not the M-Files login. Use [GetLogin](mfiles:MFiles.IRPCLoginsAdmin.GetLogin) for the
	//   values stored in M-Files.
	rpc GetFullNameAndEmail( GetFullNameAndEmailRequest ) returns ( GetFullNameAndEmailResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Lists Windows groups that the server can see: local groups and domain groups.
	//
	// - Requires the system administrator server role (server right `manage_logins`).
	// - The number of groups is limited by server configuration; `group_limit_exceeded` tells
	//   whether the list was cut. Narrow the search with `domain_name` and
	//   `organizational_unit_name_dn`.
	rpc GetWindowsGroups( GetWindowsGroupsRequest ) returns ( GetWindowsGroupsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Lists the users and groups that are members of a Windows group.
	//
	// - Requires the system administrator server role (server right `manage_logins`).
	rpc GetWindowsGroupMembers( GetWindowsGroupMembersRequest ) returns ( GetWindowsGroupMembersResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Lists the Windows domains that the server computer can reach, including its own.
	//
	// - Requires the system administrator server role (server right `manage_logins`).
	rpc GetAllDomains( GetAllDomainsRequest ) returns ( GetAllDomainsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Lists the organizational units of a Windows domain.
	//
	// - Requires the system administrator server role (server right `manage_logins`).
	rpc GetOrganizationalUnitsForDomain( GetOrganizationalUnitsForDomainRequest ) returns ( GetOrganizationalUnitsForDomainResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Ends all sessions of the given login accounts in every vault on the server.
	//
	// - Requires the system administrator server role (server right `manage_logins`).
	// - The users are logged out at once; their clients must log in again.
	rpc ForceLogout( ForceLogoutRequest ) returns ( ForceLogoutResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Starts the "forgot password" flow for an M-Files login: sends the user an e-mail with a
	// password reset link.
	//
	// - Needs no session. The reset URL is not returned to the caller; it is only e-mailed. System
	//   administrators can get the URL with
	//   [CreatePasswordResetRequestAdmin](mfiles:MFiles.IRPCLoginsAdmin.CreatePasswordResetRequestAdmin).
	// - `site_url` must match the M-Files Web address configured for a vault on the server (with
	//   https if that address uses https); otherwise the call fails with "The parameter is
	//   incorrect.".
	// - Fails when password reset is disabled on the server, the login is not found, is a Windows
	//   login, has no e-mail address, has the system administrator role, or a request was sent for it
	//   very recently.
	// - On servers with vault login accounts, the vault given by `vault_guid` (or found from the host
	//   of `site_url`) is tried first.
	// - The link is valid for 7 days by default. Complete the reset with
	//   [ResetPassword](mfiles:MFiles.IRPCLoginsAdmin.ResetPassword).
	rpc CreatePasswordResetRequest( CreatePasswordResetRequestRequest ) returns ( CreatePasswordResetRequestResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Creates a password reset link for an M-Files login, returns it, and optionally e-mails it to
	// the user.
	//
	// - Requires the system administrator server role (server right `manage_logins`).
	// - The same rules as in
	//   [CreatePasswordResetRequest](mfiles:MFiles.IRPCLoginsAdmin.CreatePasswordResetRequest) apply.
	rpc CreatePasswordResetRequestAdmin( CreatePasswordResetRequestAdminRequest ) returns ( CreatePasswordResetRequestAdminResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the encrypted password hash of an M-Files login, for copying the password to another
	// server with [SetPasswordHash](mfiles:MFiles.IRPCLoginsAdmin.SetPasswordHash).
	//
	// - Requires the system administrator server role (server right `manage_logins`). Denied for
	//   other callers.
	// - The hash is encrypted with the public key the caller provides; `PASSWORD_ENCRYPTION_UNENCRYPTED`
	//   fails with "The parameter is incorrect.".
	rpc GetPasswordHash( GetPasswordHashRequest ) returns ( GetPasswordHashResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Sets the password of an M-Files login from a password hash, for example one read with
	// [GetPasswordHash](mfiles:MFiles.IRPCLoginsAdmin.GetPasswordHash) on another server.
	//
	// - Requires the system administrator server role (server right `manage_logins`).
	// - An unknown login fails with "Not found.". Works only for M-Files logins.
	rpc SetPasswordHash( SetPasswordHashRequest ) returns ( SetPasswordHashResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Completes the "forgot password" flow: sets a new password for a login with the values from the
	// password reset link.
	//
	// - Needs no session. The `account_name`, `expiration_time` and `reset_password_hash` come from
	//   the link's `username`, `expiration` and `hash` query parameters
	//   ([CreatePasswordResetRequest](mfiles:MFiles.IRPCLoginsAdmin.CreatePasswordResetRequest)).
	// - An invalid or expired link fails with "Changing the password failed.".
	// - Failed attempts count toward the server's login attack protection, like failed logins; a
	//   blocked address or account fails until the block ends.
	// - **Pitfall:** set `password_format` to `PASSWORD_FORMAT_SEE_OTHER_PARAMS`. The proto3 default
	//   selects a deprecated format that overrides the other password fields.
	rpc ResetPassword( ResetPasswordRequest ) returns ( ResetPasswordResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_NONE };
	}

	// Adds a login account to the server.
	//
	// - Requires the system administrator server role (server right `manage_logins`).
	// - On servers that use vault login accounts, only logins with the system administrator role can
	//   be added at server level.
	// - For an M-Files login, provide the password in `password_info`.
	rpc AddLogin( AddLoginRequest ) returns ( AddLoginResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the login accounts the caller is allowed to see: all of them for system administrators,
	// otherwise those linked to vaults the caller administers.
	//
	// - Any session can call it; the result depends on the caller:
	//   - with the server right `manage_logins` (system administrator role): all logins;
	//   - otherwise: only the logins that are linked to a user account in a vault where the caller has
	//     a user account with the vault right `manage_users` (vault administrators have it). All online
	//     vaults of the server are checked, whatever vault the session is in.
	// - A caller who administers no vault gets an empty list, not an error.
	// - So a vault administrator without server rights gets the logins of its vault's users, in a
	//   vault session and in a server-level session alike.
	rpc GetLogins( GetLoginsRequest ) returns ( GetLoginsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets one login account by account name.
	//
	// - An unknown account fails with "Not found.".
	rpc GetLogin( GetLoginRequest ) returns ( GetLoginResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the login accounts that currently have open sessions on the server.
	//
	// - Requires the system administrator server role (server right `manage_logins`). Denied for
	//   other callers.
	rpc GetLoginsWithSessions( GetLoginsWithSessionsRequest ) returns ( GetLoginsWithSessionsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Changes a login account: its server roles and enabled state, and optionally its password, full
	// name, e-mail address and license type.
	//
	// - Requires the system administrator server role (server right `manage_logins`).
	// - `srvroles` is always written; send the complete set (including `can_log_in` to keep the login
	//   enabled). The other fields are written only when `change_password` or `update_other_fields`
	//   is true.
	// - Changing the license type fails if no license of that type is available.
	// - On servers that use vault login accounts, a login that is not a system administrator can only
	//   be disabled or set to no license here.
	// - `update_client_id` and `client_id` are ignored by this method.
	// - By default, the linked user accounts in the online vaults are refreshed after a change.
	rpc ModifyLogin( ModifyLoginRequest ) returns ( ModifyLoginResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of RemoveLogin.
message RemoveLoginRequest {

	// The account name of the login to remove.
	string account_name = 1;
}

// The response of RemoveLogin.
message RemoveLoginResponse {
}

// The request of GetDomainName.
message GetDomainNameRequest {
}

// The response of GetDomainName.
message GetDomainNameResponse {

	// The domain name, or the computer name when the server is not in a domain.
	string domain = 1;
}

// The request of GetComputerName.
message GetComputerNameRequest {
}

// The response of GetComputerName.
message GetComputerNameResponse {

	// Receives the computer name.
	string computer = 1;
}

// The request of GetFullNameAndEmail.
message GetFullNameAndEmailRequest {

	// The Windows account in `DOMAIN\user` form.
	string account_name = 1;
}

// The response of GetFullNameAndEmail.
message GetFullNameAndEmailResponse {

	// Receives the full name.
	string full_name = 1;

	// Receives the email address.
	string email = 2;
}

// The request of GetWindowsGroups.
message GetWindowsGroupsRequest {

	// The domain to search, or unset for all groups.
	string domain_name = 1;

	// The distinguished name of an organizational unit to search in (see [GetOrganizationalUnitsForDomain](mfiles:MFiles.IRPCLoginsAdmin.GetOrganizationalUnitsForDomain)), or unset to search from the domain level.
	string organizational_unit_name_dn = 2;

	// True to search the sub-units too. Used only when `domain_name` is set.
	bool search_sub_items = 3;
}

// The response of GetWindowsGroups.
message GetWindowsGroupsResponse {

	// Receives the names of the groups (e.g. "DOMAIN\Domain Users").
	repeated string groups = 1;

	// Set to true if the result set does not contain all groups.
	bool group_limit_exceeded = 2;
}

// The request of GetWindowsGroupMembers.
message GetWindowsGroupMembersRequest {

	// The group in `DOMAIN\group` form.
	string group_name = 1;

	// `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_USERS` for the direct members only, or `EXTERNAL_GROUP_IMPORT_MODE_DIRECT_AND_NESTED_USERS` to include the members of nested groups.
	ExternalGroupImportMode egim = 2;
}

// The response of GetWindowsGroupMembers.
message GetWindowsGroupMembersResponse {

	// Receives the names of the users (e.g. "DOMAIN\user").
	repeated string users = 1;

	// Receives the names of the groups (e.g. "DOMAIN\Group 1").
	repeated string groups = 2;
}

// The request of GetAllDomains.
message GetAllDomainsRequest {
}

// The response of GetAllDomains.
message GetAllDomainsResponse {

	// Receives domain names.
	repeated string domains = 1;
}

// The request of GetOrganizationalUnitsForDomain.
message GetOrganizationalUnitsForDomainRequest {

	// The domain name in NetBIOS form, for example `CONTOSO`.
	string domain = 1;
}

// The response of GetOrganizationalUnitsForDomain.
message GetOrganizationalUnitsForDomainResponse {

	// Receives organizational units.
	repeated DirectoryItem ous = 1;
}

// The request of ForceLogout.
message ForceLogoutRequest {

	// The account names of the logins to log out.
	repeated string account_names = 1;
}

// The response of ForceLogout.
message ForceLogoutResponse {
}

// The request of CreatePasswordResetRequest.
message CreatePasswordResetRequestRequest {

	// The login's account name. Leave empty to identify the login by `account_email_address`.
	string account_name = 1;

	// Used only when `account_name` is empty; exactly one login must have this address.
	string account_email_address = 2;

	// The M-Files Web page that handles the reset. The link is this URL with `username`, `hash` and `expiration` query parameters added.
	string site_url = 3;

	// True if an e-mail containing the password reset URL should be sent to the user.
	bool send_email = 4;

	// Optional vault for servers that use vault login accounts.
	string vault_guid = 5;
}

// The response of CreatePasswordResetRequest.
message CreatePasswordResetRequestResponse {
}

// The request of CreatePasswordResetRequestAdmin.
message CreatePasswordResetRequestAdminRequest {

	// The name of the login account whose password should be reset.
	string account_name = 1;

	// The e-mail address of the login account whose password should be reset.
	string account_email_address = 2;

	// The site URL used in forming the password reset URL.
	string site_url = 3;

	// True to also e-mail the link to the user.
	bool send_email = 4;

	// The vault to try login account reset request in.
	string vault_guid = 5;
}

// The response of CreatePasswordResetRequestAdmin.
message CreatePasswordResetRequestAdminResponse {

	// The reset link.
	string password_reset_url = 1;
}

// The request of GetPasswordHash.
message GetPasswordHashRequest {

	// How to encrypt the hash for transit: set `PASSWORD_ENCRYPTION_AES256`.
	PasswordEncryption password_encryption = 3;

	// The caller's public key; the hash is encrypted with it.
	bytes public_key = 1;

	// The name of the account to get password hash from.
	string account_name = 2;
}

// The response of GetPasswordHash.
message GetPasswordHashResponse {

	// Deprecated; filled only for old clients. Use `password_info`.
	string password_hash = 1;

	// The encrypted hash with its hash algorithm and salt.
	PasswordInfo password_info = 2;
}

// The request of SetPasswordHash.
message SetPasswordHashRequest {

	// The name of the account to set password hash to.
	string account_name = 1;

	// Deprecated; leave empty and use `password_info`.
	string password_hash = 2;

	// The password hash with its algorithm, salt and transit encryption.
	PasswordInfo password_info = 3;
}

// The response of SetPasswordHash.
message SetPasswordHashResponse {
}

// The request of ResetPassword.
message ResetPasswordRequest {

	// The name of the login account whose password should be reset.
	string account_name = 1;

	// The time when this password request expires.
	string expiration_time = 2;

	// The hash used to confirm that this is a valid password reset.
	string reset_password_hash = 3;

	// The new password for the login account.
	string new_password = 4;

	// Optional vault for servers that use vault login accounts.
	string vault_guid = 5;

	// Set `PASSWORD_FORMAT_SEE_OTHER_PARAMS`. The other values, including the default, are deprecated.
	PasswordFormat password_format = 6;

	// Encryption used for the passwords in transit.
	PasswordEncryption password_encryption = 7;

	// True if `new_password` is the password itself (possibly encrypted), not a hash. If false, the hash must use `password_hash_algorithm_desired`.
	bool password_unhashed = 8;

	// Algorithm to be used to hash the new password in the database.
	PasswordHashAlgorithm password_hash_algorithm_desired = 9;

	// The salt of a hashed `new_password`. Ignored when `password_unhashed` is true; the server then generates the salt.
	string new_password_salt = 10;
}

// The response of ResetPassword.
message ResetPasswordResponse {
}

// The request of AddLogin.
message AddLoginRequest {

	// The new login. See [Login](mfiles:MFiles.Login).
	Login login = 1;

	// Deprecated; leave empty and use `password_info`.
	string password_hash = 2;

	// The encrypted password hash of an M-Files login.
	PasswordInfo password_info = 3;
}

// The response of AddLogin.
message AddLoginResponse {
}

// The request of GetLogins.
message GetLoginsRequest {
}

// The response of GetLogins.
message GetLoginsResponse {

	// The login accounts. See [Login](mfiles:MFiles.Login).
	repeated Login values = 1;
}

// The request of GetLogin.
message GetLoginRequest {

	// The account name: the user name of an M-Files login or `DOMAIN\user`.
	string account_name = 1;
}

// The response of GetLogin.
message GetLoginResponse {

	// The login account. See [Login](mfiles:MFiles.Login).
	Login plogin = 1;
}

// The request of GetLoginsWithSessions.
message GetLoginsWithSessionsRequest {
}

// The response of GetLoginsWithSessions.
message GetLoginsWithSessionsResponse {

	// The logins with sessions. See [Login](mfiles:MFiles.Login).
	repeated Login values = 1;
}

// The request of ModifyLogin.
message ModifyLoginRequest {

	// The name of the account to modify.
	string account_name = 1;

	// The complete new server roles, including `can_log_in`.
	SRVROLES srvroles = 2;

	// True to set the password from `password_info`.
	bool change_password = 3;

	// Deprecated; leave empty and use `password_info`.
	string password_hash = 4;

	// The new encrypted password hash. Used only when `change_password` is true.
	PasswordInfo password_info = 9;

	// True to write `full_name`, `email_address` and `licensetype`.
	bool update_other_fields = 5;

	// The full name of the account.
	string full_name = 6;

	// The email address of the account.
	string email_address = 7;

	// The license type of the account.
	LicenseType licensetype = 8;

	// Ignored.
	bool update_client_id = 10;

	// Ignored.
	string client_id = 11;
}

// The response of ModifyLogin.
message ModifyLoginResponse {
}