// 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 credentials that the vault uses to access external systems, such as external
// repositories connected to the vault, on behalf of the user.
//
// Some vault applications and external repository connections need the user's own credentials
// for the external system. The server keeps those credentials per user and target. M-Files
// clients use this service in their "external repositories" dialogs.
//
// 1. [GetExtensionAuthenticationTargets](mfiles:MFiles.IRPCExtensionAuthentications.GetExtensionAuthenticationTargets)
//    lists the external systems (targets) and the authentication methods they accept.
// 2. [GetExtensionAuthenticationStatus](mfiles:MFiles.IRPCExtensionAuthentications.GetExtensionAuthenticationStatus)
//    tells for which targets the caller has stored credentials.
// 3. [StoreExtensionAuthenticationCredentials](mfiles:MFiles.IRPCExtensionAuthentications.StoreExtensionAuthenticationCredentials)
//    logs the caller in to a target by storing credentials.
// 4. [LogoutWithExtensionAuthentication](mfiles:MFiles.IRPCExtensionAuthentications.LogoutWithExtensionAuthentication)
//    removes them.
//
// All methods need a vault session; anonymous sessions cannot store credentials. A target is
// identified by `ExtensionAuthenticationTarget.id`. Methods that name an unknown target generally
// succeed without doing anything, so check the result with
// [GetExtensionAuthenticationStatus](mfiles:MFiles.IRPCExtensionAuthentications.GetExtensionAuthenticationStatus).
//
// Credentials for the whole vault (common, background and permission-reading accounts) are set
// by vault administrators with
// [StoreExtensionAuthenticationSpecialCredentials](mfiles:MFiles.IRPCExtensionAuthentications.StoreExtensionAuthenticationSpecialCredentials).
// Send credentials only over TLS.
service IRPCExtensionAuthentications {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Extension authentications" };

	// Lists the external systems that accept credentials through this service.
	//
	// - Requires a vault session. No special vault rights are needed.
	// - Empty when the vault has no external system that accepts credentials this way.
	rpc GetExtensionAuthenticationTargets( GetExtensionAuthenticationTargetsRequest ) returns ( GetExtensionAuthenticationTargetsResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Logs the caller in to an external system with encrypted credentials. Used by M-Files clients
	// that encrypt the credentials above the transport layer; applications should call
	// [StoreExtensionAuthenticationCredentials](mfiles:MFiles.IRPCExtensionAuthentications.StoreExtensionAuthenticationCredentials)
	// over TLS instead.
	//
	// - Data that the server cannot decrypt fails with "The parameter is incorrect.".
	rpc LoginWithExtensionAuthentication( LoginWithExtensionAuthenticationRequest ) returns ( LoginWithExtensionAuthenticationResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Removes the caller's stored credentials for an external system and logs the caller out of it.
	//
	// - Requires a vault session. Affects only the caller's own credentials.
	// - Succeeds also when nothing was stored for the target.
	rpc LogoutWithExtensionAuthentication( LogoutWithExtensionAuthenticationRequest ) returns ( LogoutWithExtensionAuthenticationResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Asks the external system to start a new login for the caller, so that the caller can switch to
	// another account there. Used by M-Files clients; applications rarely call it.
	//
	// - Requires a vault session of a user; anonymous sessions fail.
	// - What happens depends on the external system; any new credentials are stored for the caller.
	rpc LogInAsDifferentUserForExtensionAuthentication( LogInAsDifferentUserForExtensionAuthenticationRequest ) returns ( LogInAsDifferentUserForExtensionAuthenticationResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Lists the targets for which the caller has stored credentials, with the account name used.
	//
	// - Requires a vault session. Returns only the caller's own entries.
	// - A target with no entry has no stored credentials for the caller.
	rpc GetExtensionAuthenticationStatus( GetExtensionAuthenticationStatusRequest ) returns ( GetExtensionAuthenticationStatusResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Stores vault-wide credentials for an external system: the common, background or
	// permission-reading account. Used by vault administration tools.
	//
	// - Requires full control of the vault; other users get "Access denied.".
	// - The credentials must be encrypted in a format internal to the M-Files clients; data that the
	//   server cannot decrypt fails with "The parameter is incorrect.".
	rpc StoreExtensionAuthenticationSpecialCredentials( StoreExtensionAuthenticationSpecialCredentialsRequest ) returns ( StoreExtensionAuthenticationSpecialCredentialsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Removes vault-wide credentials for an external system. Used by vault administration tools.
	//
	// - Requires full control of the vault; other users get "Access denied.".
	// - Succeeds also when nothing was stored.
	rpc RemoveExtensionAuthenticationSpecialCredentials( RemoveExtensionAuthenticationSpecialCredentialsRequest ) returns ( RemoveExtensionAuthenticationSpecialCredentialsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Logs the caller in to an external system by storing the caller's credentials for it.
	//
	// - Requires a vault session of a user; anonymous sessions fail. `target` must not be empty
	//   ("The parameter is incorrect. (Invalid target name.)").
	// - Replaces credentials already stored for the caller and the target.
	// - The credentials travel in clear text inside the message. Use this method only over TLS.
	// - Use this method rather than
	//   [LoginWithExtensionAuthentication](mfiles:MFiles.IRPCExtensionAuthentications.LoginWithExtensionAuthentication),
	//   which expects encrypted data.
	rpc StoreExtensionAuthenticationCredentials( StoreExtensionAuthenticationCredentialsRequest ) returns ( StoreExtensionAuthenticationCredentialsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}
}

// The request of GetExtensionAuthenticationTargets.
message GetExtensionAuthenticationTargetsRequest {
}

// The response of GetExtensionAuthenticationTargets.
message GetExtensionAuthenticationTargetsResponse {

	// The targets. Pass `id` as `target` to the other methods, and use `supported_plugins` to choose how to authenticate.
	repeated ExtensionAuthenticationTarget targets = 1;
}

// The request of LoginWithExtensionAuthentication.
message LoginWithExtensionAuthenticationRequest {

	// The `id` of the target.
	string target = 1;

	// The credentials, encrypted with the server's public key in a format internal to the M-Files clients.
	bytes ear_data_encrypted = 2;
}

// The response of LoginWithExtensionAuthentication.
message LoginWithExtensionAuthenticationResponse {
}

// The request of LogoutWithExtensionAuthentication.
message LogoutWithExtensionAuthenticationRequest {

	// The `id` of the target.
	string target = 1;
}

// The response of LogoutWithExtensionAuthentication.
message LogoutWithExtensionAuthenticationResponse {
}

// The request of LogInAsDifferentUserForExtensionAuthentication.
message LogInAsDifferentUserForExtensionAuthenticationRequest {

	// The `id` of the target.
	string target = 1;
}

// The response of LogInAsDifferentUserForExtensionAuthentication.
message LogInAsDifferentUserForExtensionAuthenticationResponse {
}

// The request of GetExtensionAuthenticationStatus.
message GetExtensionAuthenticationStatusRequest {
}

// The response of GetExtensionAuthenticationStatus.
message GetExtensionAuthenticationStatusResponse {

	// One entry per target with stored credentials.
	repeated ExtensionAuthenticationStatus statuses = 1;
}

// The request of StoreExtensionAuthenticationSpecialCredentials.
message StoreExtensionAuthenticationSpecialCredentialsRequest {

	// Which vault-wide account to set: `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_COMMON`, `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_BACKGROUND` or `EXTENSION_AUTHENTICATION_SPECIAL_USER_TYPE_PERMISSIONS`.
	ExtensionAuthenticationSpecialUserType eeasut = 1;

	// The `id` of the target.
	string target = 2;

	// The credentials, encrypted with the server's public key in a format internal to the M-Files clients.
	bytes ear_data_encrypted = 3;
}

// The response of StoreExtensionAuthenticationSpecialCredentials.
message StoreExtensionAuthenticationSpecialCredentialsResponse {
}

// The request of RemoveExtensionAuthenticationSpecialCredentials.
message RemoveExtensionAuthenticationSpecialCredentialsRequest {

	// Which vault-wide account to remove.
	ExtensionAuthenticationSpecialUserType eeasut = 1;

	// The `id` of the target.
	string target = 2;
}

// The response of RemoveExtensionAuthenticationSpecialCredentials.
message RemoveExtensionAuthenticationSpecialCredentialsResponse {
}

// The request of StoreExtensionAuthenticationCredentials.
message StoreExtensionAuthenticationCredentialsRequest {

	// The `id` of the target, from [GetExtensionAuthenticationTargets](mfiles:MFiles.IRPCExtensionAuthentications.GetExtensionAuthenticationTargets).
	string target = 1;

	// The credentials. See [ExtensionAuthenticationResponse](mfiles:MFiles.ExtensionAuthenticationResponse).
	ExtensionAuthenticationResponse authentication_data = 2;
}

// The response of StoreExtensionAuthenticationCredentials.
message StoreExtensionAuthenticationCredentialsResponse {
}