{"id":23359769,"url":"https://github.com/firehed/auth","last_synced_at":"2025-10-30T06:32:21.614Z","repository":{"id":30337548,"uuid":"33889915","full_name":"Firehed/auth","owner":"Firehed","description":"Easily integrate multi-factor auth into any PHP project","archived":false,"fork":false,"pushed_at":"2016-03-12T21:24:44.000Z","size":51,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-13T22:26:58.470Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Firehed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-13T19:45:40.000Z","updated_at":"2020-07-28T00:13:04.000Z","dependencies_parsed_at":"2022-07-31T09:07:55.182Z","dependency_job_id":null,"html_url":"https://github.com/Firehed/auth","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Firehed%2Fauth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Firehed%2Fauth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Firehed%2Fauth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Firehed%2Fauth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Firehed","download_url":"https://codeload.github.com/Firehed/auth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247729465,"owners_count":20986392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-21T11:11:55.343Z","updated_at":"2025-10-30T06:32:21.529Z","avatar_url":"https://github.com/Firehed.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Auth\n\nAuth is a library designed to take the complexity out of multi-factor and\nhigh-security authentication in PHP projects. Data is stored in\n[JWTs](http://jwt.io) which are tamper-resistant, permitting authentication\ninformation to be stored completely client-side without the need for\na database[^db].\n\nBy implementing a single interface, your existing PHP app can flexibly support\nMFA without being tied to a specific provider or implementation. Thanks to\nbeing based on open standards, the authentication data can be used with any\nframework, and even ported to other programming languages.\n\n## A simple example\n```php\n\u003c?php\nuse Firehed\\Auth;\nuse Firehed\\JWT;\nuse Firehed\\Security\\Secret;\n\n// General setup\n$keys = new JWT\\KeyContainer();\n$keys-\u003eaddKey('20130101',\n    JWT\\Algorithm::HMAC_SHA_256(),\n    new Secret('some randomly-generated secret'));\n\n$auth = new Auth\\Auth();\n$auth-\u003esetKeys($keys)\n    -\u003esetLoader(function($uid): Auth\\Authable {\n        return (new User())-\u003efind($uid);\n    });\n\n// Authenticating a user\n$user = User::findByEmail($_POST['email']);\n$password = new Auth\\Factors\\KnowledgeFactor(new Secret($_POST['password'));\n$auth-\u003esetUser($user);\ntry {\n    $auth-\u003evalidateFactor($password);\n    setcookie('auth_token',\n        $auth-\u003egetEncodedToken(),\n        time()+(86400*90),\n        '/',\n        'yourdomain.com',\n        true,\n        true);\n} catch (Auth\\Exceptions\\AuthException $e) {\n    // password was incorrect\n}\n\n// Accessing a previously-authenticated user\ntry {\n    $user = $auth-\u003esetEncodedToken($_COOKIE['auth_token'])\n        -\u003esetRequiredLevel(Auth\\Level::LOGIN())\n        -\u003egetUser();\n} catch (Auth\\Exceptions\\AuthException $e) {\n    // Authentication failed, prompt for login\n    header('Location: /login');\n}\n```\n\n## Installation\n\nInstallation is supported through Composer:\n\n    composer require firehed/auth\n\nFor more information, please visit [the Composer\nwebsite](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx)\n\n## API\n\n### setEncodedToken(string $token): self\nRestore an authentication session from an encoded JWT. This method will be\nmostly used on logged-in pages.\n\n### setUser(Firehed\\Auth\\Authable $user): self\nStart an authentication session for a new user. This method will be mostly used\nduring the start of a login flow.\n\n### setLoader(callable $loader): self\nProvide a callback that will return a Firehed\\Auth\\Authable object provided\na unique identifier. This will be used alongside `setEncodedToken` to allow\n`getUser` to function on restored sessions.\n\nIt must have the following signature:\n```php\nfunction($uid): Firehed\\Auth\\Authable\n```\n\n### setRequiredLevel(Firehed\\Auth\\Level $level): self\nProvide the authentication level required for `getUser` to return a user. This\ndefaults to `Level::LOGIN`.\n\n### getEncodedToken(): string\nGet a JWT containing the authentication data for the current user. This does\nnot contain sensitive data, and is tamper-resistant thanks to signing. You\nSHOULD store the encoded token client-side, so long as transmission is done\nsecurely (this applies to any session identifier). Note that this does include\nthe user's own ID.\n\n### getUser(): Firehed\\Auth\\Authable\nGet the authenticated user. If the user is insufficiently authenticated, this\nwill throw an exception, preventing accidental access.\n\n### enterHighSecurity(Firehed\\Auth\\Factors\\Factor $factor): self\nUse the provided factor to start a high-security session. It will last until\nthe expiration time on the factor. If no expiration time is set, it will only\nlast until the end of the request.\n\n### exitHighSecurity(): void\nExit high-security mode regardless of the time remaining.\n\n### validateFactor(Firehed\\Auth\\Factors\\Factor $factor): self\nAuthenticate the user with the provided factor.\n\n### expireFactor(Firehed\\Auth\\Factors\\FactorType $type): self\nRemove the authentication data provided by the specified factor type. Most\ncommonly, this will be used to log the user out.\n\n### setKeys(Firehed\\JWT\\KeyContainer $keys): self\nProvides a KeyContainer that's used internally for JWT handling. This allows\nkey rotation to be seamless and nearly-automatic\n\n## Core concepts\n\n* Authentication: the act of verifying identity\n* Factor: a method of authentication. There are three different factors:\n  * Inherence: something a user *is*, such as a fingerprint\n  * Knowledge: something a user *knows*, such as a passphrase\n  * Possession: something a user *has*, such as a OTP token\n* High-security mode: conceptually similar to `sudo`, this is a way to protect\n  especially-sensitive actions (password change, credit card management, etc.)\n  by requiring a fresh authentication.\n* Levels: there are four authentication levels that a page can require:\n  * `ANONYMOUS`: Users are not authenticated at all, nor will one be returned\n    by `getUser`\n  * `PARTIAL`: Allows validation methods to be called on a partially-\n    authencitaed user, although getUser() will return null. This SHOULD NOT be\n    used outside of an autentication upgrade flow; i.e. providing their OTP\n    code or token. Use getPartiallyAuthenticatedUser() to get at the underlying\n    user, which SHOULD be used ONLY for modifying the user's new factor\n    registration (e.g. TOTP code provided didn't match)\n  * `LOGIN`: Users require all of their factors to be present\n  * `HISEC`: In addition to all factors being present, one must have been\n    explicitly re-verified via the `enterHighSecurity` API\n\n## Examples\n\n(new examples coming soon)\n\n[^db]: Of course, you will still need to securely store password hashes, OTP\nshared secrets, etc. What you will not need to do is muck around with existing\nsession storage and handling.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirehed%2Fauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirehed%2Fauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirehed%2Fauth/lists"}