101 lines
3.4 KiB
PHP
101 lines
3.4 KiB
PHP
<?php
|
|
|
|
declare(strict_types=1);
|
|
|
|
namespace KTXF\Security\Authentication;
|
|
|
|
use KTXF\Resource\Provider\ProviderInterface;
|
|
use KTXF\Security\Authentication\ProviderContext;
|
|
use KTXF\Security\Authentication\ProviderResult;
|
|
|
|
/**
|
|
* Unified Authentication Provider Interface
|
|
*/
|
|
interface AuthenticationProviderInterface extends ProviderInterface
|
|
{
|
|
/** Secret style authentication (e.g. password, TOTP, etc) */
|
|
public const METHOD_CREDENTIAL = 'credential';
|
|
|
|
/** Challenge/response (e.g. SMS code, email code, etc) */
|
|
public const METHOD_CHALLENGE = 'challenge';
|
|
|
|
/** Redirect-based (e.g. OIDC, SAML, OAuth) */
|
|
public const METHOD_REDIRECT = 'redirect';
|
|
|
|
/**
|
|
* Provider method - one of the METHOD_* constants
|
|
*/
|
|
public function method(): string;
|
|
|
|
/**
|
|
* Provider icon
|
|
*/
|
|
public function icon(): string;
|
|
|
|
// =========================================================================
|
|
// Credential Authentication
|
|
// =========================================================================
|
|
|
|
/**
|
|
* Authenticate with credentials (username/password style)
|
|
*
|
|
* @param ProviderContext $context Authentication context
|
|
* @param string $secret Password, PIN, or secret
|
|
*
|
|
* @return ProviderResult
|
|
*/
|
|
public function verify(ProviderContext $context, string $secret): ProviderResult;
|
|
|
|
// =========================================================================
|
|
// Challenge/Response Authentication
|
|
// =========================================================================
|
|
|
|
/**
|
|
* Begin a challenge (send code, prepare for verification)
|
|
*
|
|
* For SMS/Email: Sends the code and returns confirmation
|
|
* For TOTP: Returns challenge metadata (digits, etc.)
|
|
*
|
|
* @param ProviderContext $context Authentication context
|
|
*
|
|
* @return ProviderResult Contains challenge metadata in clientData
|
|
*/
|
|
public function beginChallenge(ProviderContext $context): ProviderResult;
|
|
|
|
/**
|
|
* Verify challenge response
|
|
*
|
|
* @param ProviderContext $context Authentication context
|
|
* @param string $code User's response code
|
|
*
|
|
* @return ProviderResult
|
|
*/
|
|
public function verifyChallenge(ProviderContext $context, string $code): ProviderResult;
|
|
|
|
// =========================================================================
|
|
// Redirect Authentication (OIDC/SAML)
|
|
// =========================================================================
|
|
|
|
/**
|
|
* Begin redirect-based authentication
|
|
*
|
|
* @param ProviderContext $context Authentication context (contains config)
|
|
* @param string $callbackUrl URL to redirect back to
|
|
* @param string|null $returnUrl Final destination after auth
|
|
*
|
|
* @return ProviderResult Contains redirect_url in clientData, state/nonce in sessionData
|
|
*/
|
|
public function beginRedirect(ProviderContext $context, string $callbackUrl, ?string $returnUrl = null): ProviderResult;
|
|
|
|
/**
|
|
* Complete redirect-based authentication
|
|
*
|
|
* @param ProviderContext $context Authentication context (contains stored state/nonce in metadata)
|
|
* @param array $params Callback parameters (code, state, etc.)
|
|
*
|
|
* @return ProviderResult Contains user attributes in identity on success
|
|
*/
|
|
public function completeRedirect(ProviderContext $context, array $params): ProviderResult;
|
|
|
|
}
|