Login and sessions (IRPCLogin)
An interface for handling client login & logout operations.
Use this interface to log in to MFServer and to maintain the login session.
| gRPC service | MFiles.IRPCLogin |
|---|---|
| Book and level | Vault API, core |
| Methods | 25 |
| Proto file | mfiles/IRPCLogin.proto |
Overview
Opens, maintains and closes sessions. Almost every other call needs the session ID that
LogIn returns, sent as the binary metadata header
mfiles-session-id-bin (the 48 bytes of session_data.session_id, unchanged).
Which methods matter:
| Job | Methods |
|---|---|
| Find out how to authenticate | GetServerCapabilities, GetAuthenticationConfiguration |
| Open a session | LogIn (vault or server level), LogInWithSession (another vault, same user) |
| Keep it open | KeepAlive, at least every session_data.keep_alive_interval_in_seconds |
| Close it | LogOut |
| Inspect it | GetVaultSessionInfo |
Typical order:
- QueryVersion and GetServerCapabilities (no session needed).
- GetAuthenticationConfiguration when
the vault may use single sign-on;
AUTH_METHOD_PLUGINmeans log in withAUTH_DATA_TYPE_PLUGIN, otherwise use user name and password (AUTH_DATA_TYPE_CREDENTIALS). - LogIn with the vault GUID. Keep
session_data. - Call KeepAlive on a timer while the session is in use.
- On
UNAUTHENTICATED, log in again withLogInand continue with the new session ID. - LogOut when done. A session that is not logged out holds its license until it times out.
A session is bound to one vault, or to no vault (a server-level session, opened with the vault
GUID {00000000-0000-0000-0000-000000000000}). Methods that need a vault fail with
E_MFILES_LOGIN_REQUIRED when called with a server-level session.
Errors: an invalid, expired or missing session is reported as gRPC status UNAUTHENTICATED with
no error trailers. All other failures, including a wrong password, use status UNKNOWN with the
M-Files error stack in the mfiles-error-serialized-bin trailer.
Other methods of this service serve M-Files' own clients (licensing warnings, password encryption, client settings, replication) and are marked as such.
Guides: Authentication and sessions covers every login type and the session lifecycle, and Call metadata the headers that every call sends.
Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| GetServerCapabilities | Gets the features the server supports, without logging in. | session no session idempotent |
| GetAuthenticationConfiguration | Tells a client, before login, whether to authenticate with an authentication plug-in (single sign-on) and returns the plug-in's client-side configuration. | session no session idempotent |
| LogIn | Authenticates the caller and opens a session to a vault, or to the server when the vault GUID is all zeros. | session no session |
| LogInWithSession | Opens a new session to a vault (or the server) for the user of an existing session, without authenticating again. | session session |
| KeepAlive | Tells the server that the session is still in use, so that it does not expire. | session session idempotent |
| LogOut | Ends the session and releases its license. | session session |
| GetVaultSessionInfo | Gets basic information about the current vault session: server version and ID, vault GUID and name, and the state of the server push channel. | session session returns metadata structure version |
Other methods
| Method | Summary | Facts |
|---|---|---|
| ChangePassword | Changes the M-Files password of the logged-in account. | session session |
| CreateUserSession | Opens a session that acts as another user of the vault. | session session idempotent |
| DisconnectDevice | Removes a device registration (device token) of the logged-in user in the session's vault. | session session |
| GetAuthenticationPlugins | Lists the authentication plug-ins installed on the server, without their configurations. | session no session |
| GetClientSettingsByType | Gets client settings (theme, timeouts, banners, web security settings) for an M-Files web, desktop or Outlook client. | session no session |
| GetLicenseExpirationInfo | Gets the number of days until the server's license and its subscription expire. | session session idempotent |
| GetLoginSettings | Gets the anonymous login settings and enabled vertical applications of the vault that serves the given host name, without a session. | session no session |
| GetPublicKey | Gets the server's RSA public key, for encrypting secrets that a client sends to the server. | session session idempotent |
| GetPublicKeyAnonymous | Gets the server's RSA public key without a session, for encrypting authentication data before login. | session no session |
| GetRPCOverCOMInterface | Gets RPC over COM interface for accessing M-Files Server. | session no session |
| GetVaultConnectionInfo | Gets the full connection information of the current vault session, in the form the M-Files COM API uses. | session session |
| IsServerRunningInEvaluationMode | Tells whether the server runs on an evaluation license, and how many evaluation days are left. | session session idempotent |
| LoginForAutomaticUpdates | Logs in for automatic updates. | session no session |
| LogInRemote | Logs in (with authentication) to a remote server. | session no session |
| Relogin | Logs in again by using the current session ID. Used by M-Files' own clients. | session session |
| ResolveMaturityOfFeature | Returns which of the named server feature flags are enabled on this server. | session no session |
| SetOpenSessionCheck | Sets whether administrators are warned about this session when they take the vault offline or do other maintenance. | session session |
| VerifyLicenseSubscriptionTime | Fails if the server's license subscription has expired; succeeds otherwise. | session no session |