namespace Connected.Security.Authentication
{
	/// <summary>
	/// The service which performs authentication requests.
	/// </summary>
	/// <remarks>
	/// The service uses registered <see cref="IAuthenticationMiddleware"/> to perform
	/// the actual authentication.
	/// </remarks>
	public interface IAuthenticationService
	{
		/// <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 provider:
		/// <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);
	}
}