Vault login accounts (IRPCVaultLoginsAdmin)
Manages vault login accounts: login accounts stored in one vault, used on servers that have vault login accounts enabled, such as M-Files Cloud.
Use this interface to add, modify and delete vault logins.
| gRPC service | MFiles.IRPCVaultLoginsAdmin |
|---|---|
| Book and level | Administration API, specialized |
| Methods | 17 |
| Proto file | mfiles/IRPCVaultLoginsAdmin.proto |
Overview
A login account is what a person or application authenticates with: account type (M-Files or Windows), user name, password, license type, full name and email (Login). Normally login accounts belong to the server and are managed by system administrators with IRPCLoginsAdmin. On a server with vault login accounts enabled, each vault keeps its own login accounts in the vault, and vault administrators manage them with this service. Either way, a login needs a user account in the vault (IRPCUsersAdmin) to use the vault; see the table in the IRPCUsersAdmin overview.
- Availability. Vault login accounts are a server-wide setting. Check it anonymously with
GetServerCapabilities:
server_capabilities.vault_login_accounts. An M-Files Cloud server returned true; a default on-premises server returns false. When it is false, every method of this service fails with "This operation is currently not available. The registry key for enabling vault-specific login accounts needs to be set first." (error code 0x8004093A), before the session is checked. - Session and rights. Requires a vault session; the methods work on the logins of that
vault. Most methods need the vault right
manage_users(VaultAccess); the server role system administrator is not needed. A server can be configured to make vault login accounts read-only for vault administrators: then AddVaultLogin, ModifyVaultLogin, ModifyVaultLoginEx and RemoveVaultLogin also need the system administrator server role (server rightmanage_logins). - Server and vault logins together. When a vault login and a server login have the same account name, the vault login is used for that vault. A vault login can never have the system administrator role. While vault login accounts are enabled, server-level AddLogin accepts only system administrators.
- Logins with an External ID (
Login.external_id) are maintained by identity synchronization (M-Files Manage); removing or renaming them here fails.
Methods by task (the server-level equivalents are in IRPCLoginsAdmin):
- Read: GetVaultLogins, GetVaultLogin, GetVaultLoginsWithSessions.
- Add, change, remove: AddVaultLogin, ModifyVaultLogin, ModifyVaultLoginEx, RemoveVaultLogin, ForceLogoutVaultLoginSessions.
- Passwords: CreateVaultLoginPasswordResetRequest, ResetVaultLoginPassword, GetVaultLoginPasswordHash, SetVaultLoginPasswordHash.
- Directory lookups for importing Windows accounts:
GetAllDomainsInVault,
GetOrganizationalUnitsForDomainInVault,
GetWindowsGroupsInVault,
GetWindowsGroupMembersInVault,
GetFullNameAndEmailInVault.
They read the domain directory, or the vault's default user synchronization plugin when one is
configured for the domain. A server can be configured to use only that plugin for callers
without the server right
manage_logins.
Typical provisioning on such a server:
AddVaultLogin, then
AddUser with login_name set to the new login's account
name.
Methods
| Method | Summary | Facts |
|---|---|---|
| AddVaultLogin | Adds a login account to the vault. | admin session |
| CreateVaultLoginPasswordResetRequest | Creates a password reset link for an M-Files login of the vault, and optionally emails it to the login's email address. | admin session |
| ForceLogoutVaultLoginSessions | Logs out all sessions of the given login accounts in this vault. | admin session |
| GetAllDomainsInVault | Lists the domains whose accounts can be imported: the server's own domain and the domains it can reach. | admin session idempotent |
| GetFullNameAndEmailInVault | Looks up the full name and email address of a Windows account in the directory. | admin session idempotent |
| GetOrganizationalUnitsForDomainInVault | Lists the organizational units of a domain. | admin session idempotent |
| GetVaultLogin | Gets one vault login by account name. | admin session |
| GetVaultLoginPasswordHash | Reads the password hash of a vault login, encrypted with a public key that the caller supplies. | admin session idempotent |
| GetVaultLogins | Gets all login accounts stored in the vault. | admin session idempotent |
| GetVaultLoginsWithSessions | Gets the login accounts that currently have sessions to this vault. | admin session idempotent |
| GetWindowsGroupMembersInVault | Lists the users and groups that are members of a Windows group. | admin session idempotent |
| GetWindowsGroupsInVault | Lists Windows groups of the server's domains, for importing users by group. | admin session idempotent |
| ModifyVaultLogin | Changes the server roles, password, full name, email address or license type of a vault login. | admin session idempotent |
| ModifyVaultLoginEx | Replaces the data of a vault login, optionally including its account name. | admin session |
| RemoveVaultLogin | Removes a login account from the vault. | admin session |
| ResetVaultLoginPassword | Sets a new password for a vault login, authorized by a password reset link. | admin session |
| SetVaultLoginPasswordHash | Sets the password of a vault login from a password hash. | admin session idempotent |