User Login
Leaf Auth provides a flexible and secure login system that works for both token based and session based authentication. It provides a unified way to authenticate users in your web apps and APIs.
Token vs Session Authentication
Token based authentication is a system where a user is given a token upon login which is then used to authenticate the user on every request. It is the most common authentication system for APIs. This video by Hamy Labs explains how token authentication works
Session-based authentication is a method where, after a user logs in, the server creates a session to remember them. Every time the user makes a request, their session ID is sent back to the server to verify their identity, allowing them to stay logged in while using the app.
Signing a user in
To sign a user in, you can use the login() method. This method takes in an array of data you want to use to authenticate the user. This data is usually the user's email and password, but can be anything as long as the password field is present.
auth()->login([
'email' => '[email protected]',
'password' => 'password'
]);The login() method returns true if the user is successfully authenticated and false if the user is not authenticated. You can then use the errors() method to get the error message.
$success = auth()->login([
'email' => '[email protected]',
'password' => 'password'
]);
if ($success) {
// User is authenticated
} else {
// User is not authenticated
$error = auth()->errors();
}You can get the data and tokens needed for authentication using the data() method:
$data = auth()->data();
// ['user' => [...], 'accessToken' => '...', 'refreshToken' => '...']If you want to use a couple of fields from the user within your application, you can use the user method. You can find the documentation for the Auth user method here.
Switching to session auth
Leaf uses token based authentication by default which uses a JWT to authenticate your users. Sessions are a more common way to authenticate users in fullstack applications. To switch to session based authentication, you can update your auth config:
auth()->config('session', true);
...
// auth login 'session' => true,With the addition of session auth, login() will automatically start a session, but will behave in the same way, which means redirects and any other functionality you need will be left up to you to handle:
...
// session is automatically started
$success = auth()->login([
'email' => '[email protected]',
'password' => 'password'
]);
if ($success) {
// User is authenticated
$user = auth()->user();
response()->redirect('/dashboard');
} else {
// User is not authenticated
$error = auth()->errors();
}This lets you handle complex control flows...or the simple redirect ones in a manner you prefer.
If you need finer control over how PHP creates your session, you can add your own config to the session.cookie config:
auth()->config('session.cookie', [
'secure' => true,
'httponly' => true,
'samesite' => 'lax'
]);Signing in from OAuth
Some applications allow users to sign in using OAuth which means there's no need for users to add emails or passwords, usually because the OAuth provider handles that for you. The most common OAuth providers are Google, Facebook, Twitter, GitHub, etc. To make it even easier to sign in users from OAuth, you can use one of the League OAuth2 client providers to get the user's data from the OAuth provider and then use that data to sign in the user using Leaf Auth.
Registering OAuth Providers New
Although you can use any OAuth provider you want, using one of the League OAuth2 client providers makes it easier to work within the context of Leaf Auth. You can find a list of all the available providers on the League Website. For instance, to use Google/GitHub as providers, you simply need to install the required packages and them add them to Leaf Auth in your app/routes/index.php file or just index.php if you are not using Leaf MVC:
// .env
GOOGLE_AUTH_CLIENT_ID={google-client-id}
GOOGLE_AUTH_CLIENT_SECRET={google-client-secret}
// anywhere in your app
$token = auth()->client('google')->anyLeagueMethod();$provider = new League\OAuth2\Client\Provider\Github([
'clientId' => '{github-client-id}',
'clientSecret' => '{github-client-secret}',
'redirectUri' => 'https://example.com/callback-url',
]);
auth()->withProvider('github', $provider);
// anywhere in your app
$token = auth()->client('github')->anyLeagueMethod();Leaf Auth provides the fromOAuth() function which allows you to create a session or token for a user without needing a password.
$user = auth()->client('github')->getResourceOwner($token);
$success = auth()->fromOAuth([
'token' => $token,
'user' => [
'name' => $user->getName(),
'email' => $user->getEmail(),
'avatar' => $user->getAvatar() ?? null,
]
]);Password Required in DB New
It is common for applications to start of with email/password authentication and later add OAuth as an alternative way to sign in. In such cases, the users table will most likely have a password field which is required. In such cases, you can fill the password field with a random string when creating a user from OAuth:
$user = auth()->client('google')->getResourceOwner($token);
$success = auth()->fromOAuth([
'token' => $token,
'user' => [
'name' => $user->getName(),
'email' => $user->getEmail(),
'password' => 'GOOGLE_AUTH_PLACEHOLDER',
'email_verified_at' => tick()->format('Y-M-D H:i:s'),
'avatar' => $user->getAvatar() ?? null,
]
]);If the user is successfully saved in the database, a session or token is created for them and the rest of the process is the same as signing up a user normally. If Leaf Auth fails to save the user, the method returns false. You can then use the errors() method to get the error message.
$success = auth()->fromOAuth([
'token' => $token,
'user' => [
'name' => $user['name'],
'email' => $user['email'],
'avatar' => $user['avatar_url']
]
]);
if (!$success) {
$error = auth()->errors();
}
// user is authenticated
$user = auth()->user();Everything after this point is the same as signing up a user normally.
OAuth Token
The fromOAuth() method expects an OAuth token to be passed in. This token is usually gotten from the OAuth provider you are using. You can later use this token to make requests to the OAuth provider on behalf of the user. Leaf Auth saves this token so you can retrieve it later using the auth()->oauthToken() method.
$token = auth()->oauthToken();Finding a user by id New
There are times when you might want to find a user by their id to perform some operations on them while they are NOT logged in. For instance, finding a user by their id to assign a role to them. Leaf Auth provides the find() method to do this:
$user = auth()->find(1);
...
$user->assign('admin');
...
$user->transactions()->create([...]);Auth with no password
Leaf Auth usually expects a password field to authenticate users. This is necessary because most applications require a password to authenticate users. The field is usually named password, however, you can configure Leaf Auth to expect a different field:
auth()->config('password.key', 'pass');Better still, you can turn off password authentication completely. This is useful in multi-step authentication systems, where you might authenticate a set of parameters before authenticating the password. To turn off password authentication, you can configure Leaf Auth like this:
auth()->config('password.key', false);Once this is done, Leaf will no longer expect a password field to authenticate users and will also turn off password hashing and verification.
Password verification
Password verification is done to check if a password matches the hashed password in the database. By default, Leaf uses the Leaf\Helpers\Password::verify method which has support for bcrypt and argon2. If you however want to use a different method or turn off password verification, you can do that directly in the config:
auth()->config('password.verify', false); // turn off verification
auth()->config('password.verify', function ($password, $hash) {
return Password::verify($password, $hash);
});These are the available options you can pass to password.verify:
false- This turns off password verificationnull/true- This uses the default verification method (Leaf\Helpers\Password::verify)function- This uses a custom method. The method should accept a password and a hash and return a boolean.
Custom error messages
Leaf Auth provides default error messages for different operations. If you want to customize these messages, you can configure Leaf Auth to use your custom messages:
auth()->config('messages.loginParamsError', 'Username is incorrect!');
auth()->config('messages.loginPasswordError', 'Password is incorrect!');Hiding sensitive information
The output of Leaf's authentication methods is an object with the user's data and the token or session. By default, the password field is hidden from the user data. This is a security measure to prevent the password from being exposed.
{
"user": {
"username": "mychidd22",
"email": "[email protected]",
"created_at": "2024-10-26 19:29:37.000000",
"updated_at": "2024-10-26 19:29:37.000000"
},
"accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyLmlkIjo5MjQsImlhdCI6MTczMDAyOTAwNywiZXhwIjo4NjQwMCwiaXNzIjoibG9jYWxob3N0OjU1MDAifQ.yLldIhOkUxn54-3RWLD7PJONoWwqpZ5mmP8fEZ4nNfs",
"refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyLmlkIjo5MjQsImlhdCI6MTczMDAyOTAwNywiZXhwIjozNDU2MDAsImlzcyI6ImxvY2FsaG9zdDo1NTAwIn0.tqfp5Co4vLtq3_J0r5Fp-XwuDSB1i6uC4AcogQ3vnc8"
}If you want to customize what items are hidden from the user data, you can configure Leaf Auth to hide them:
auth()->config('hidden', ['password', 'id', 'email', ...]);Controlling session lifetime
Whether you are using token or session based auth, you might want to control how long a user's session or token lasts. You can set the lifetime of a user's session or token config like this:
auth()->config('token.lifetime', '1 hour'); // 1 hour'
auth()->config('token.lifetime', 60 * 60 * 24 * 7); // 1 week
auth()->config('token.lifetime', 0); // never expireauth()->config('session.lifetime', '1 hour'); // 1 hour
auth()->config('session.lifetime', 60 * 60 * 24 * 7); // 1 week
auth()->config('session.lifetime', 0); // never expire