Server login accounts (IRPCLoginsAdmin)
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.
| gRPC service | MFiles.IRPCLoginsAdmin |
|---|---|
| Book and level | Administration API, specialized |
| Methods | 19 |
| Proto file | mfiles/IRPCLoginsAdmin.proto |
Overview
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); 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 and GetLogin also serve callers without server rights, with a narrower result (see their remarks). This is why a vault administrator can list logins.
- CreatePasswordResetRequest and ResetPassword need no session at all: they are the "forgot password" flow of M-Files Web.
Methods by task:
- Read logins: GetLogins, GetLogin, GetLoginsWithSessions.
- Change logins: AddLogin, ModifyLogin, RemoveLogin, ForceLogout.
- Passwords: GetPasswordHash, SetPasswordHash (copy a password between servers), CreatePasswordResetRequestAdmin, CreatePasswordResetRequest, ResetPassword.
- Windows and Active Directory lookups (for picking Windows accounts and groups): GetDomainName, GetComputerName, GetAllDomains, GetOrganizationalUnitsForDomain, GetWindowsGroups, GetWindowsGroupMembers, 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:
a login without can_log_in is disabled.
Methods
| Method | Summary | Facts |
|---|---|---|
| AddLogin | Adds a login account to the server. | admin session |
| CreatePasswordResetRequest | Starts the "forgot password" flow for an M-Files login: sends the user an e-mail with a password reset link. | admin no session |
| CreatePasswordResetRequestAdmin | Creates a password reset link for an M-Files login, returns it, and optionally e-mails it to the user. | admin session |
| ForceLogout | Ends all sessions of the given login accounts in every vault on the server. | admin session |
| GetAllDomains | Lists the Windows domains that the server computer can reach, including its own. | admin session idempotent |
| GetComputerName | Gets the name of the server computer. | admin session |
| GetDomainName | Gets the Windows domain of the server computer, or the computer name if it is not in a domain. | admin session idempotent |
| GetFullNameAndEmail | Looks up the full name and e-mail address of a Windows account in its directory. | admin session idempotent |
| GetLogin | Gets one login account by account name. | admin session |
| GetLogins | Gets the login accounts the caller is allowed to see: all of them for system administrators, otherwise those linked to vaults the caller administers. | admin session idempotent |
| GetLoginsWithSessions | Gets the login accounts that currently have open sessions on the server. | admin session idempotent |
| GetOrganizationalUnitsForDomain | Lists the organizational units of a Windows domain. | admin session idempotent |
| GetPasswordHash | Gets the encrypted password hash of an M-Files login, for copying the password to another server with SetPasswordHash. | admin session idempotent |
| GetWindowsGroupMembers | Lists the users and groups that are members of a Windows group. | admin session idempotent |
| GetWindowsGroups | Lists Windows groups that the server can see: local groups and domain groups. | admin session idempotent |
| ModifyLogin | Changes a login account: its server roles and enabled state, and optionally its password, full name, e-mail address and license type. | admin session idempotent |
| RemoveLogin | Removes a login account from the server. | admin session |
| ResetPassword | Completes the "forgot password" flow: sets a new password for a login with the values from the password reset link. | admin no session |
| SetPasswordHash | Sets the password of an M-Files login from a password hash, for example one read with GetPasswordHash on another server. | admin session idempotent |