Connected.Framework/Connected.Security/Authentication/IAuthenticationResult.cs

using Connected.Security.Identity;

namespace Connected.Security.Authentication;

/// <summary>
/// Defines the reason <see cref="IAuthenticationMiddleware"/> decided 
/// to allow or refuse the authentication .
/// </summary>
public enum AuthenticationResultReason
{
	/// <summary>
	/// The authentication was successfully. This is the only reason
	/// that is used when authentication is successful.
	/// </summary>
	OK = 0,
	/// <summary>
	/// The provided identity was not found.
	/// </summary>
	NotFound = 1,
	/// <summary>
	/// The provided identity did not have a valid password.
	/// </summary>
	InvalidPassword = 2,
	/// <summary>
	/// The provided identity is not active in the environment.
	/// </summary>
	Inactive = 3,
	/// <summary>
	/// The provided identity is locked or blocked by the environment.
	/// </summary>
	Locked = 4,
	/// <summary>
	/// The provided identity does not have a password set but an <see cref="IAuthenticationMiddleware"/>
	/// requires one.
	/// </summary>
	NoPassword = 5,
	/// <summary>
	/// The provided identity's password has expired. 
	/// </summary>
	PasswordExpired = 6,
	/// <summary>
	/// The token provided by the identity is invalid.
	/// </summary>
	InvalidToken = 7,
	/// <summary>
	/// The credentials provided by identity are not valid or are not supported by the environment.
	/// </summary>
	InvalidCredentials = 8,
	/// <summary>
	/// There is other issue regarding identity which cannot be resolved.
	/// </summary>
	Other = 99
}
/// <summary>
/// Represents the result of the authentication process. <see cref="IAuthenticationMiddleware"/> should never
/// throw an exception during authentication process. It must always return <see cref="IAuthenticationResult"/> regardless
/// wether it was successful or not.
/// </summary>
public interface IAuthenticationResult
{
	/// <summary>
	/// The token which can be used to uniquely identify the identity. This token is
	/// generated by the <see cref="IAuthenticationMiddleware"/> when the authentication is
	/// successful and no previous token was created.
	/// </summary>
	/// <remarks>
	/// Each identity should have only one active token at the time and the new token can be invalidated
	/// by the environment. Token is also valid only for a limited time. Once expired, user will need to
	/// authenticate again. The primary use of this token is in the SSO systems.
	/// </remarks>
	string? Token { get; }
	/// <summary>
	/// Returns <code>true</code> if authentication was successful, <code>false</code> otherwise.
	/// </summary>
	bool Success { get; }
	/// <summary>
	/// The reason authentication was successful or not.
	/// </summary>
	AuthenticationResultReason Reason { get; }
	/// <summary>
	/// The identity which can be used in the process pipeline.
	/// </summary>
	/// <remarks>
	/// For example, this value will be used by HttpRequests as a User property.</remarks>
	IUser? User { get; }
}