namespace Connected.Security.Authentication.Middleware;

/// <summary>
/// Represents an authentication middleware which is called when authenticating identity.
/// </summary>
/// <remarks>
/// The environment should have only one <see cref="IAuthenticationMiddleware"/> registered which
/// uniquely authenticates all requests. The environment have a built in authentication middleware
/// which authenticates identities against standard entities. If you need to authenticate identities
/// against external data sources you need to implement your own <see cref="IAuthenticationMiddleware"/> and
/// register it in the configuration. 
/// </remarks>
public interface IAuthenticationMiddleware : IMiddleware
{
	/// <summary>
	/// Performs authentication against identity. Identity is not necessarry a user, it can be device, process
	/// or any other entity which needs protection.
	/// </summary>
	/// <param name="args">The authentication arguments explaining the identity. The following identities are supported by a
	/// default authentication middleware:
	/// <list type="bullet">
	/// <item><see cref="BasicAuthenticationArgs"/></item>
	/// <item><see cref="PinAuthenticationArgs"/></item>
	/// <item><see cref="SsoAuthenticationArgs"/></item>
	/// <item><see cref="BearerAuthenticationArgs"/></item>
	/// </list>
	/// </param>
	/// <returns>
	/// <see cref="IAuthenticationResult"/> containing information about authentication wether it is successfull or not and
	/// the reason why it was not successfully. If it's successfully it also provides <see cref="System.Security.Claims.ClaimsIdentity"/> identity.
	/// </returns>
	Task<IAuthenticationResult> Authenticate(AuthenticationArgs args);
}