Let's have an honest discussion about Lucia

[pilcrowOnPaper]

Hi, everyone.

The vibe I'm getting recently is that there's a disconnect between what I want out of Lucia, and what the community wants. An identity crisis if you will. I'm not sure how big the gap is, but it's definitely there. Part of the reason for that, I believe, is that while I have kept the project scope limited, I haven't clearly defined the goals of the project. I see that as a failure on my part as project lead. And my view on the library has definitely changed over time. The issue needs to be addressed, so let's talk about it.

Personally, I don't see auth as a whole hard. Just tedious and time consuming. So I don't want Lucia to handle a lot of things, just the annoying bits. And the most obvious target I see is session management. I think you'd agree here as well. And database adapters are a nice addition for small~medium sized projects too. So Lucia should definitely handle sessions and related database queries. Good.

Then comes the issue with authentication. There are mainly 2 approaches: OAuth and passwords. Either way, you interact with keys right now.

OAuth

First OAuth. I think having built-in providers that do all the requests is a big time saver. But the OAuth story in Lucia doesn't end there. You create a table for storing keys, and Lucia will handle database queries for getting existing users and creating keys. Is that necessary, and more importantly worth it? Yes, you get a nice API interface, but you give up on how those data is stored and you have to learn the concept of keys. Like, here's an example. The first one is with keys, and the second is without.

// with keys
try {
  const { githubUser, getExistingUser, createUser } =
    await githubAuth.validateAuthorizationCode(code);
  const existingUser: User | null = await getExistingUser();
  // the rest handled by lucia
  if (existingUser) {
    const session: Session = await auth.createSession(existingUser.id);
    auth.handleRequest().setSession(session);
    return redirect(302, "/");
  }
  const newUser: User = await createUser({
    attributes: {
      github_id: githubUser.id,
      username: githubUser.login,
    },
  });
  const session: Session = await auth.createSession(newUser.userId);
  auth.handleRequest().setSession(session);
  return redirect(302, "/");
} catch {
  // invalid code
  return error(400);
}

// without keys
try {
  const { githubUser } = await githubAuth.validateAuthorizationCode(code);
  const existingUser: UserSchema | null = await db.getUserByGithubUserId(
    githubUser.id
  );
  // the rest handled by lucia
  if (existingUser) {
    const session: Session = await auth.createSession(existingUser.id);
    auth.handleRequest().setSession(session);
    return redirect(302, "/");
  }
  const newUser: User = await auth.createUser({
    attributes: {
      github_id: githubUser.id,
      username: githubUser.login,
    },
  });
  const session: Session = await auth.createSession(newUser.userId);
  auth.handleRequest().setSession(session);
  return redirect(302, "/");
} catch {
  // invalid code
  return error(400);
}

There are both equally readable and maintainable. And with the second one, you don't have to learn a Lucia-specific concept. Another benefit is that without the limitation keys, you have the options to store data that best fits your application:

1. Only Github: Store the Github user id within the user table (like the example)
2. Multiple OAuth options: Store the Github in a github_user table

These are better options than storing every method into a single table.

Passwords

Next, password based auth. Unlike Auth.js, I don't want to make it harder to implement it. But I do want to discourage people from implementing it if they're not willing to put the care required to pull it off. Because here's the thing: email/password auth is tedious. It's not hard, but there's a lot of steps required to implement it correctly. And you're not making your password based auth any more secure by using Lucia's keys. Besides, if you're willing to take time to implement email verification, password reset tokens, and login throttling, keys aren't really making your work significantly easier.

You might think Lucia should handle stuff like verification tokens and login throttling. But, auth is inherently tied to your database, framework, and project structure. Lucia isn't the right abstraction level to implement it. For it to be realistic, Lucia would have to only support a single database driver/ORM, and maybe a single framework.

And similar to OAuth, if you just want basic password based auth for internal projects, it isn't hard:

const storedCredentials = await db.getUserCredentialsByUsername(username);
if (!storedCredentials) {
  return error(400, "Invalid username or password");
}
const validPassword = await verifyPassword(
  storedCredentials.hashedPassword,
  password
);
if (!validPassword) {
  return error(400, "Invalid username or password");
}
const session: Session = await auth.createSession(newUser.userId);
auth.handleRequest().setSession(session);
return redirect(302, "/");

The biggest benefit you get right now is that Lucia hashes password using the recommended algorithm + settings. But Lucia/Oslo can just provide an API just for that, without the database part or keys.

What do I want?

I want to remove keys. Maybe it's too radical. But I think it's a flawed concept that just isn't worth the trouble.

• It doesn't do much
• It's too limiting for large projects
• It gives a false sense of security

My original plan with v3 was to keep keys but only for OAuth, but maybe it's better to change rip off the bandaid.

But that's what I want from Lucia, taking into considering what's possible (session management) and what's not (a perfect library that handles every step of auth). I have to accept that it's not a personal project anymore. And that people hate breaking changes. So I want to ask the community; what do you want from Lucia?

[tajkirkpatrick]

I, of course personally, want keys they provide a sense of uniformity. As for passwords, I am wholeheartedly in the camp of discouraging their use. If there exists a pathway to implementing them, hand me the pieces I need to the foot gun and let me build it. Offer me resources, considerations, and disclaimers, but anything beyond that? Take care of it for me completely. Which of course, would contradict the discouragement of using them in the first place.

[pilcrowOnPaper]

Keys were originally added to provide a sense of uniformity but that's hard when different projects have different requirement (=database schema). And point is that key are the wrong abstraction

[maietta]

Rip the Band-Aid clean off. It only stings for a little bit.

[vegeta897]

I support removing keys. I'm already basically ignoring them by copying the user's Twitch ID into user attributes, just to avoid having to do a join when selecting a user by Twitch ID.

I also don't use passwords but I think your reasoning is sound.

[jadbox]

Just me careful to change the user's Twitch ID in every table when the user wants to change it!

[vegeta897]

Appreciate the caution, but I'm talking about their internal Twitch user ID, which cannot be changed (it'd be chaos if they could!), unlike their username which can. If Lucia receives a new Twitch user ID from oauth it would correctly create a new user. Even if it's the same human, it's a different Twitch account.

[fezproof]

I feel like one of the best features of keys is being ignored here. I agree passwords should probably just die, but having unique keys for each login type allows an easy way to have users link multiple OAuth providers to the same account.
Say if a user wants to switch from Apple to Google OAuth. They could:

1. Log in with google
2. Go to settings
3. Add key for Apple
4. Remove key for google
5. Continue to log in with Apple

Keys also allow for easy future proofing for when there could be a mix of OAuth providers and Passkeys.
There may be other ways to add the same features, but keys make it sooo easy atm.

[pilcrowOnPaper]

It's still possible, and in a much more clean way. You just have to create a google_user and apple_user table. Same concept as keys, but they get separated into their own tables.

Also, you can't implement passkeys with keys.

[saturnonearth]

Honestly I prefer this to keys. The less stuff that Lucia needs you to add in the first place, the better. That way, if you want simple, you get it, if you want complexity, you can add it later.

[jasongitmail]

you just have to create a google_user and apple_user table. Same concept as keys, but they get separated into their own tables.

I'm not keen on this though. It would be cleaner to at least store all OAuth providers together in one table, to keep like items together. Creating one-table per provider creates new complexity.

[Masstronaut]

You just have to create a google_user and apple_user table.

Would the User table then also need a 1:1 relation to the table for each separate auth method? That seems rather tedious in its own way.

[pilcrowOnPaper]

You can still keep everything in a single table. The point of the discussion is that you can decided what's best for your application.

[ernestoresende]

Speaking as a heavy user of Lucia ever since I discovered it sometime after the v1 release: I don't think Lucia, as a project, needs to go any further in terms of what it's trying to achieve.

Personally, I don't see auth as a whole hard. Just tedious and time consuming. So I don't want Lucia to handle a lot of things, just the annoying bits. And the most obvious target I see is session management.

This is on point. Auth is tedious and time consuming, and Lucia already takes a massive chunk of work out of my hands. But I think the most compelling aspect of Lucia is that the way it's structured also gives me enough flexibility to bend parts of it to meet my requirements. A few examples:

1. I've had to implement Lucia in a way it kept backwards compatibility with an older bcrypt hashing. Lucia let's me handle this by just supplying and additional option.
2. I've had to use officially unsupported database adapters. There is API documentation and third-party implementations, so I just wrote my own adapter and plugged it into Lucia, quick & easy.

I think not covering request throttling, email verifications, and any other tasks not directly related to the session management aspect, was the correct decision so far: Lucia does one thing, and it tries to do it as well as it possibly can.

I already have ownership of both the database and the API layer. If I want to use mailing, or implement request throttling, this should not fall into Lucia's umbrella of responsibilities.

---

Unlike Auth.js, I don't want to make it harder to implement it. But I do want to discourage people from implementing it if they're not willing to put the care required to pull it off.

This is fair, passwords are dangerous when handled incorrectly. Period. That being said though, one of the things that instantly drove me away from Auth.js is how they actively prevent you from configuring credential based authentication under some conditions.

I get it, we want to make the transition to a passwordless future, and we want better tools to help us achieve that. But not every project is a greenfield one, and in the real world, we have business requirements to meet... Many times, these business requirements will tell us that a credential based authentication system is needed. So we will build/maintain them.

So I agree, usage of credential based methods should be discouraged where possible (with visible warnings in the docs and some bits of developer education). But not removed.

---

I want to remove keys. Maybe it's too radical. But I think it's a flawed concept that just isn't worth the trouble.

I don't have a strong opinion about it to be completely honest. I think the feeling I have for them is, that they're fine.

Yes, they are a Lucia specific concept, and yes, they do require you to adhere to a Lucia specific shape of database schema, but they never got in my way, even when working in making my authentication layer backward compatible with previous iterations (most databases will allow me to have a trigger to copy values from the user_key table to somewhere else I'll need to keep supporting the legacy API's).

I will say this though. Adding tables to a database is easier them removing them. On a personal level, for me, the removal of keys would incur in some serious refactoring on several projects where I want to keep using the latest version of Lucia.

If you think this is a necessary change to realize your vision for the library, I'd say go for it. But be mindful that other authors of projects that currently use Lucia for their authentication layer in productions environments might not be too happy about it, so planning it throughly (migration guides on how to handle the database changes without losing data) is a good idea.

[pilcrowOnPaper]

On a personal level, for me, the removal of keys would incur in some serious refactoring on several projects where I want to keep using the latest version of Lucia.

This is something I'm well aware of. I won't push a change without a defined migration path, and I just want to hear from the community right now.

[pilcrowOnPaper]

Also, I will never purposefully kneecap Lucia to make implementing password auth hard. That's just stupid. I just think keys are not the best approach even if you want to add password based auth.

[balazsorban44]

Auth.js creator here. We never prevented anything, only discouraged, if it ever came through that way, we might have miscommunicated.

Password auth with Auth.js takes ~5 lines if you have a good understanding of it. Support is not going away, ever. Period. Now making it secure and good? As @pilcrowOnPaper said in this exact discussion, takes effort.

Read #1231 (comment) for my detailed answer and let me know.

[ernestoresende]

Admittedly, it's been a long time since I've used Auth.js directly. So long indeed, that I don't think "Auth.js" was a thing already (still only next-auth back then). In any case, assuming the core API hasn't changed drastically since then and based on what I can remember from using the library, I want to focus specifically on this part:

[...]one of the things that instantly drove me away from Auth.js is how they actively prevent you from configuring credential based authentication under some conditions.

I think I should have bolded under certain conditions, and spent some time specifying what exactly I'm talking about: yes, I can use credentials based authentication with Auth.js, as long as I:

• Use the JWT session strategy
• Don't mix it with other OAuth providers

Sure, I can persist the callback of the session on the database by myself. But the library already has a database adapter to handle this for me, and the reason why it's not doing it is because of opinions.

Note
I've kept note of the fact that nextauthjs/next-auth#8482 changes the jwt() to the authorize() on the docs, making it much clearer that you can, indeed, still use session data to work your own data persistence logic, and I think this is a step in the right direction regarding developer education.

In the same lines, because I'm forced to change to the JWT session strategy, If want to use other OAuth providers with credentials, I'll have to manually handle database entries. Again, the database adapters are there. I just can't use them, because the library has choosen to artifically limit my access to these API's.

So yes, while I agree these do not prevent me from rolling out my own workarounds, I don't want to have to rely on those workarounds in the first place.

This kind of behavior discouragement is different from the kind I suggest on my OP. Things like these: https://github.com/anthonyshew/next-auth/blob/6ac22cf6c813563288da4f470499f64f9a7c36fe/docs/docs/guides/providers/credentials-provider.md?plain=1#L59-L88, only prove to me that, if I tried to work with Auth.js in the same way I work today with Lucia, I would have to bring my own hashing, salting, and database persistence logic. And this, I believe, is one of the core reasons some of us migrated away from Auth.js as soon as we found out about Lucia.

I'm open to continuing the conversation about this — and other topics related to Auth.js — further if needed, as I still think that, like Lucia, Auth.js is a incredibly useful library in the sense that it takes the away the pain of doing the complicated and boring bits. But it suffers from the hindrances of both the aspects mentioned by this OP, and other aspects mentioned elsewhere in this discussion topic (created routes that aren't used, PR for blocking bugs sitting open for long time periods, confusing mensaging and developer education on where the separation between next-auth and auth.js occurs). I would suggest though that the conversation is taken outside this discussion topic, as it would not pertrain to Lucia's feedback colection being done here.

[jasongitmail]

But I think the most compelling aspect of Lucia is that the way it's structured also gives me enough flexibility to bend parts of it to meet my requirements.

I agree with this so far (fairly new to Lucia).

I appreciate Lucia's enthusiastic maintenance, docs, and thought given (e.g. architecture to sit between DB and framework, ability to use separate DBs for user data and sessions, etc).

My perspective:

As a user:

• Philosophically, I don't want to become an auth expert/connoisseur. Lower and lower level isn't a selling point (it often means more maintenance and more surface area to create security consequences putting it together 'wrong'). My ideal is a maintained library with good docs, to implement it and get back to focusing on differentiating aspects of a project. But without inflexibility or lack of maintenance like AuthJS (UI routes created that aren't used, PR for blocking bugs sitting open for months, etc).
• I'd prefer a clear path.
• The new split of Lucia and Oslo will create a new decision point to research and decide between. Merging them back into one eventually seems beneficial, rather than increasing decision points.

I'm interested in:

• magic links/codes
• passkeys -- I'd like to see this in Lucia
• OAuth (occasionally)
• I don't use passwords, but it sounds like others do, from the other discussion, and keeping support would them to keep using Lucia.

No opinion on keys. I'm too new to Lucia and reserving judgement.

[pilcrowOnPaper]

The new split of Lucia and Oslo will create a new decision point to research and decide between. Merging them back into one eventually seems beneficial, rather than increasing decision points.

The long term plan is to use Oslo as the foundation of Lucia. And the big benefit of that is Oslo provides a lot of other utilizes aside from sessions, including APIs for verification tokens and passkeys.

And you can't implement passkeys with current key architecture

[jasongitmail]

Yeah, I assume you'll want a table for passkeys, given a user could have more than one passkey.

[pilcrowOnPaper]

And you need store pubic keys and challenges

[ObieMD5]

I specifically moved away from Auth.js because of the limiting aspect of passwords. I understand that passwords are discouraged because due diligence still needs to be done. However, we still have requirements to have credentials logins. I don't understand the big push to get away from them when almost every new application from the private sector still requires them. I'm indifferent either way about the interactions that Lucia has with my user information. If you want to handle session management and provide oauth/password utility functions/providers, I'm game. If you go that route, I would at least lay out a checklist of things the user should provide to accomplish it correctly, not by giving code examples but by listing them out. I think for password authentication, it would be better if we had the chance to provide the users of the library additional utility functions for generating/validating TOTP to make credentials usage on the "safer" side.

Removing the key table would be fine, as we can use the utility functions to validate the data from how we are storing it. Request throttling, email verification, and others should be kept out of auth as they are not directly auth-related, but maybe suggest the user implement them. Even then, you could still utilize Lucia in a passwordless capability. The user of the library would have to handle the passwordless part of it like a short-lived token at an endpoint that is emailed to them that would create a session. Medium.com does this with just an email address to create an account, and then they email you a link anytime you want to log in. This then makes a session and allows you to enter as you do.

[pilcrowOnPaper]

I don't think passwords are bad. And I'll never make it difficult on purpose nor will I remove guides on it from the docs. That's just stupid. I just think keys aren't very helpful if you want to implement password based auth.

Also, Oslo my other project than I'm hoping to make the foundation of Lucia, has utilities for working HOTP and TOTP..

[ObieMD5]

I'm indifferent about the key table. Using the predefined setup guide, helps people get up and going fast but I think in the end, most would like the flexibility to store them how they see fit. If it doesn't make sense in the end, especially if you were to add additional methods like passkeys and they don't work with that structure we would have to roll a separate table for them regardless unless it was provided some how through the library.

[balazsorban44]

My answer on Auth.js' choices #1231 (comment)

[donprasetiyo]

But I do want to discourage people from implementing it if they're not willing to put the care required to pull it off.

Can you be specific about the care required? I only use Lucia for easier and secure way to handle sessions. That's all.

For password reset and email verification, I think I can do it on my own.

[PizzaConsole]

I have followed this project on and off for awhile. Finally in the past 2 months implementing it into a production application. I have been able to make everything work well. I believe that a project should pick it one thing to do well and focus on that. So, I applaud you for really trying to find that one thing. I am too little experience to provide feedback on overall design. Though, I will say that I have recently been thinking that maybe it would be just easier to copy out the parts of Lucia that I like and integrated them directly into my project. As you mentioned, Auth is very closely tied to how a specific project works and it DB schema. Frankly I didn't really follow your above examples either...

Overall, IMO I think that if you want to change the design, then you should just rip the bandaid.

[balazsorban44]

Auth.js is not tied to any DB model though. We have a very basic/common requirement for a User and Account table, with most fields optional, and then both the Session (when a JWT session is used) and VerificationToken (if no email provider is needed) tables are optional.

Otherwise you can also save anything in these models, map the property names, etc how you like.

You can also create your own database adapter, you can even pull these things from different databases, combine HTTP/fetch with DB connection strings in the same adapter, eg. store sessions in Redis and everything else in PostgreSQL, literally no restrictions.

This was good feedback though, I can see how this isn't clear from our docs! Noted it down and will clarify.

[balazsorban44]

Creator of Auth.js here.

Unlike Auth.js, I don't want to make it harder to implement it. But I do want to discourage people from implementing it if they're not willing to put the care required to pull it off.

I want to be clear. We do not make it harder to get credentials login working in Auth.js. We are pretty much on pair with the outlined goal here.

Most people will be discouraged when they see that Auth.js has the artificial "limitation" that it doesn't work with a database. It literally takes ~5 lines to do it anyway though. If you don't realize it, you most likely should not implement it yourself. (We tried to make it more clear in the docs, see nextauthjs/next-auth#8482. I'll make sure this is reflected everywhere)

As @pilcrowOnPaper says, you need to be willing to put the care required to pull it off.

I understand that this is a common option still, and that's exactly why we are keeping the option to do it, and always will! Right now we have the bare minimum.

That said, passwordless is a great alternative IMO, but I'm also optimistic about newer alternatives like WebAuthn/Passkeys, which we are looking into supporting out-of-the-box.

That's all I wanted to say. Great post, great lib, respect @pilcrowOnPaper! 🎩

[balazsorban44]

Anyways, I absolutely did not mean to hijack the conversation of Lucia, only wanted to provide our stance since we were called out. Let's start a discussion/issue on our repo instead if you still have concerns or better, concrete suggestions that we can work on together. 🙏

[Issaminu]

Sorry for also hijicking on this discussion, but I literally did make a suggestion to improve the docs, and you were clearly against adding more contributions to that provider.

The reason why I responded here in the first place was because I genuinely didn't understand why you would push against clarity in the Credentials docs. It just seems so counter-intuitive to keep supporting it yet try to keep the developer experience around it intentionally vague and frustrating.

[ghost]

@balazsorban44 what are these magical 5 lines of code that you keep mentioning? if it is that easy why not just document it so developers new to next-auth can easily implement it

[ghost]

what a shame no response from the next-auth dev

[hillac]

nextauthjs/next-auth#4394 (comment)
Seems to be the cleanest solution I've found yet. More like 10 lines but not too bad.

[isaacfink]

My 2 cents as someone who has followed the development of Lucia but has never used it in a project
When I initially saw Lucia I thought of it as an auth library as opposed to a framework, I like libraries that provide low level building blocks allowing us more control over every step involved

I don't get why libraries are discouraging password authentication, it is by far the most popular method of authentication and the way to move away is not to persuade developers but rather users, I think every auth library should fully support it and the fact that it hard to pull of is all the more reason for libraries to support it so we don't have to worry about security

[pilcrowOnPaper]

My point was that given the current abstraction level Lucia, it can't provide everything required for password based auth. And that keys weren't the best abstraction for implementing password based auth.

[ap-1]

Maybe a little bit off-topic, but I'd love to see Lucia support WebAuthn/Passkeys. Is this possible with Lucia's keys?

[pilcrowOnPaper]

No since you need to store public keys for the user

[pilcrowOnPaper]

As for the migration path, you have a few options:

1. Keep using keys
2. Create an oauth_account table where provider_id and provider_user_id is the composite primary key (recommended)
3. Create google_account, github_account etc (option 2 but separated into each table)
4. Store GitHub user id etc into the user table

Option 2 and 3 can be done with a few lines of SQL, but option 4 maybe a bit annoying (especially for SQLite)

[pilcrowOnPaper]

Just going to add it here for future reference (SQLite):

Option 2

CREATE TABLE oauth_account (
  provider TEXT NOT NULL,
  provider_user_id TEXT NOT NULL,
  user_id TEXT NOT NULL,
  PRIMARY KEY (provider, provider_user_id),
  FOREIGN KEY (user_id) REFERENCES user(id)
);

INSERT INTO oauth_account (provider, provider_user_id, user_id)
SELECT substr(id, 1, 6), substr(id, 8), user_id FROM user_key
WHERE substr(id, 1, 6) = 'github';

Option 3

CREATE TABLE credentials (
  hashed_password TEXT NOT NULL,
  user_id TEXT NOT NULL UNIQUE,
  FOREIGN KEY (user_id) REFERENCES user(id)
);

INSERT INTO credentials (hashed_password, user_id)
SELECT hashed_password, user_id FROM user_key
WHERE substr(id, 1, 5) = 'email';

Option 4

CREATE TABLE new_user (
  id TEXT NOT NULL PRIMARY KEY,
  github_id TEXT NOT NULL UNIQUE
);

INSERT INTO new_user (id, github_id)
SELECT user.id, substr(user_key.id, 8) FROM user
INNER JOIN user_key ON user_key.user_id = user.id AND substr(user_key.id, 1, 6) = 'github';

CREATE TABLE new_session (
  id TEXT NOT NULL PRIMARY KEY,
  user_id TEXT NOT NULL,
  expires INTEGER NOT NULL,
  FOREIGN KEY (user_id) REFERENCES new_user(id)
);

INSERT INTO new_session (id, user_id, expires)
SELECT id, user_id, idle_expires FROM user_session;

[timnghg]

I am mostly working on B2B & internal projects, IMHO, like it or not, password is still dominated in auth methods in these kinds of projects.

Passwords are still having many upsides:

• Freedom, totally independents from external factors if needed
• Trustful, who are you believing? Yourself or Big/medium techs with their OAuth API?
• Privacy, are you sure that only your app known your user's access_token, when and where are your users' login?
• Controllable, key factor for enterprise ready app

When using OAth, we are still using password but shift it complexity to OAuth provider with the price of freedom & privacy.

Instead of discourage developer from password, maybe we can split passwords to it own package with their crucial modern features like password rules/strength, forgot/reset password, auto expiration, leak detection, suspicious behavior, ... It's a ton of work, but it still worth it.

[pilcrowOnPaper]

The issue is that those features requires a tight integration with your database, and possible framework. The adapter based model doesn't fit

[PizzaConsole]

To your point with trustful. https://sec.okta.com/harfiles

[quintesse]

The adapter based model doesn't fit

A bit late to the party but I think that you're right. The fact that a tight integration with database and framework would be needed seems to me that perhaps the wrong abstractions were chosen.

Coming from next-auth my first reaction on reading the Lucia docs was: "why are you messing with databases?" It means you need all those adapters just to read/write basic information. The app that you're integrating with very likely already has all the code necessary to access data from databases or whatever their data stores are.

I wonder if it wouldn't be easier to go to an abstraction where you use callbacks to ask things like: does this user exist? are they allowed to log in? are their credentials correct?
And even those can probably be boiled down to a single: is this user allowed access?

Then on top of that abstraction you could create more elaborate ones.
(For example, why deal with creating users when most providers won't let you create users anyway? Just make that an extension of some sort that people could use if they want/need to).

In our app we're using next-auth's CredentialsProvider which gives us full control of the authentication (we actually have different users depending on the sub-domain or the first path element, but there could be duplicates! For example, a user "john" that exists in several subdomains but that is potentially a different person in each case).

The interface in that case is really simple, you could literally implement:

authorize(creds, req) {
    if (creds.username !== "test" && creds.password !== "test") {
        return null;
    }
    return { any custom info here };
}

And in fact using next-auth only for that seems overkill, which is why we're on the lookout for simpler options. (Which unfortunately my first quick look at Lucia doesn't seem to be, because I don't see anything just as simple as that).

[rnbokade]

Maybe this along with a cli would make it next level.
something like npx add-lucia-auth then it asks which base framework. then ask which db driver, which session storage, then where to store models, then wether to enable features like OAuth, MFA,2fa or not. It might as well ask different methods to enable like email-password, username-password, oauth, email-magiclink, email-otp, phonenumber-otp etc.
A lot of dev time could be saved by auto code generation for most part. It would make adoption really easy.

[pilcrowOnPaper]

Here's some code examples for what this could mean:

OAuth

Basic

const tokens = await githubAuth.validateCallback(code);
const githubUser = await githubAuth.getGithubUser(tokens.accessToken);

const existingUser = await db
  .table("user")
  .where("github_user_id", "=", githubUser.id)
  .get();

if (existingUser) {
  const session = await auth.createSession(existingUser.id);
  locals.auth.setSession(session);
}

const userId = auth.generateUserId();

await db.table("user").insert({
  id: generateUserId(),
  username: githubUser.login,
  github_user_id: githubUser.login,
});

const session = await auth.createSession(userId);
locals.auth.setSession(session);

Multiple providers

const github = new Github(clientId, clientSecret);

const tokens = await github.validateCallback(code);
const githubUser = await github.getGithubUser(tokens.accessToken);

const existingAccount = await db
  .table("account")
  .where("user_id", "=", githubUser.id)
  .get();
if (existingAccount) {
  const session = await auth.createSession(existingAccount.user_id);
  locals.auth.setSession(session);
}

const userId = auth.generateUserId();

await db.transaction(
  db.table("user").insert({
    id: userId,
    username: githubUser.login,
  }),
  db.table("oauth_account").insert({
    provider: "github",
    provider_user_id: githubUser.id,
    user_id: userId,
  })
);

const session = await auth.createSession(userId);
locals.auth.setSession(session);

Password

Basic

import { Argon2id } from "oslo/password";

const argon2id = new Argon2id();
const hashedPassword = await argon2id.hash(password);

const userId = auth.generateUserId();

await db.table("user").insert({
  id: userId,
  username,
  hashed_password: hashedPassword,
});

const user = await db.table("user").where("username", "=", username).get();
if (!user) {
  throw new Error("Invalid username or password");
}
const validPassword = await argon2id.verify(user.hashed_password, password);
if (!validPassword) {
  throw new Error("Invalid username or password");
}

Or, if you're storing the credentials in a different table:

const credentials = await db
  .table("credentials")
  .innerJoin("user", "user.id", "credentials.user_id")
  .where("user.username", "=", username)
  .get();
if (!credentials) {
  throw new Error("Invalid username or password");
}
const validPassword = await argon2id.verify(
  credentials.hashed_password,
  password
);

[deadcoder0904]

As someone who currently uses Lucia (before I was using Next Auth but faced way too many issues & didn't get answers for it & couldn't figure it out myself either), I like Lucia bcz its simple.

My opinion is simple: Just do what is simple & common (popular choice)

Lucia meant you had to write your own db which is a bit hard but still felt much simpler than Next Auth.

So I'd prefer if you keep it simple as it is & prefer common use-cases even if you don't agree with them.

You can create another project if you want to propose a new solution.

See Express vs Koa but even though Koa is better as the creator of Express himself said, its still not popular.

Express works. For everyone. And even now Express is used much more than Koa.

So you can make a better yet another library & it has to be a massive 10x improvement for people to switch.

But the alternative is people will stop preferring Lucia if it gets hard or if you add something that makes something that was easy previously hard.

If you think you can execute your vision, go ahead. Early adopters can beta test.

Dont pull an Angular 2 or what Next.js did recently.

Keep it simple.

We just wanna get Auth working with simple APIs. Don't wanna learn more than that. I think most devs are like that. If we could do a Clerk/Auth0 style 1-liners then we'd prefer that but there's no OSS library that provides it yet :)

[saturnonearth]

My opinion is simple: Just do what is simple & common (popular choice).
Lucia meant you had to write your own db which is a bit hard but still felt much simpler than Next Auth.
So I'd prefer if you keep it simple as it is & prefer common use-cases even if you don't agree with them.

I think this is always the thought, but it is often hard to make something easy to use and get started, and easy to customize. Usually things that are opinionated and give the user less choice are easier to implement, as the library maintainer has full control.

[ulic75]

This may be slightly off-topic, but just thought I'd mention what I'd love.

In my current work environment we have a combination of apps. Mainly C# WinForms client app and WebForms, Angular and Qwik web apps. I would love to be able to unify the authentication and authorization between all of these in a central place. Obviously this is probably way beyond the scope for Lucia and I totally get that. I think you had previously mentioned at one point about maybe having options for other non-js based frameworks and that is something I'd love to see.

Take this as you will, I certainly don't have any expectations.

[iqbal125]

Been reading the discussions, I think rip off the band aid move might be the better approach. When projects try to do too many things and cater to many people the project just gets bloated from wat Ive seen.

[Masstronaut]

I think there are a number of upstream decisions to consider.

1. Oslo

What is the niche of oslo? What problem(s) does it solve, and for who? When should someone be reaching for Oslo as the best choice?

My impression is that Oslo provides primitives, but leaves it to the consumer to put them together in a useful way.

2. Lucia

What does Lucia aspire to do beyond Oslo? What needs to be true for Lucia to be the right choice for a project?

My mental model for Lucia is that it provides an unopinionated abstraction for authentication & session management that is built upon the basic primitives (of the sort I expect Oslo to provide) and has adapters/flexibility to support whatever (JS/TS) framework and database combo that I am using. So personally I would expect it to have APIs/guides for everything I would need to correctly use all the supported authentication methods.

3. Lucia capabilities

What authentication methods does Lucia aim to meet? There are a number that have been discussed already and seem aspirationally in-scope:

• Credentials (email/username + password)
• OAuth providers
• WebAuthn
• Passkeys

Given my impression of Lucia and what's in scope for authentication methods, I would like see better support for some of the credential scenarios. I think it would be reasonable for lucia to have opinionated APIs for validating a password is secure enough (length, character mix, etc.), generating an email verification code, validating the verification code, and password resets.

I would additionally like to see 2FA/MFA as potentially in scope - something akin to generate2FACode(userId) and verify2FACode(userId, code) which leaves sending the code to me as the Lucia consumer to figure out. Whether it's email, phone, or some other method of delivery is not of concern to lucia.

Covering lucia's full surface area with these things is a big undertaking (frameworks x db adapters x authentication methods) so perhaps some of this should move upstream to Oslo utilities?

4. Given the separate aspirations of Oslo & Lucia, what's the right abstraction?

What are the right building blocks to support lucia's aspirations, and how do they differ from Oslo? I think removing keys and providing an answer that is akin to "pick one of these 4 things" fails to meet the high bar set by Lucia thus far in creating an easy to use auth solution. Keys are an effective way to grow with the consumer, who can easily add additional auth methods as it makes sense to in their app. Doing so doesn't require major changes.

For example, does it make sense for password hashing to not be exposed by Lucia at all, and for that capability to move to Oslo? Still allow overriding it in Lucia, but if you want the lower level functions for tasks like hashing a password or generating a 2FA code, require taking on Oslo as a dependency to get them?

---

Ultimately I think until you have a clear vision of what you do want ("removing keys" doesn't count!), it'll be a struggle to make the right choices.

As a Lucia consumer, I'd be open to the migration work of keys being removed, but I'd want a clear and compelling value prop of what I'm getting out of the deal. Is it:

• Better credentialed auth support out of the box (reset&verification codes + code validation)
• Faster updates?
• Less code for me to maintain?
• Simpler integration into new projects?
• Faster/easier to add more authentication options to my project?
• Out of the box support for new auth methods like WebAuthn, Passkeys, MFA/2FA (send the code myself though, no problem)

My impression of your post is that you want to remove keys because it's a lucia specific concept. I've already learned it, though, so getting to keep a unified API based on a concept I've already learned is a good deal for me. So currently it's hard for me to support removing something that I've already learned which gives me an easier API. Can you instead paint a picture of how great my life is going to be as a result of giving up keys?

[pilcrowOnPaper]

Keys don't work with passkeys, and it's a bit cumbersome for credentials auth since we don't/can't provide an API for changing the key's email/username (provider user id). There isn't much different between the work required to learn keys and use the keys API, and just doing it yourself either. It's a redundant abstraction to make the library feel more beginner friendly.

Oslo already has APIs for generating TOTP, validating WebAuthn responses, and working with verification tokens. And I'm considering adding a utility for checking the password strength.

[Masstronaut]

Is adding support for passkeys in Lucia an explicit goal? If 3.0 adds support for passkeys and removing lucia keys is a necessary step to get there, I think it's a lot easier to support than simply "remove keys" IMO.

Given Oslo already has APIs for TOTP etc. I suspect the more fruitful discussion would be centered around how lucia can gracefully include them, and it sounds like removing keys would be a natural byproduct of that.

So TL;DR: I'm in favor of removing keys, given it doesn't happen until there is a compelling story around the benefits of having to do that refactor. IMO that benefit would ideally be support for TOTP, WebAuthn validation, passkeys, or at least some subset of those things. I'd also want to see guidance/documentation on how to tie multiple auth solutions together for a single user in a clean way, which is what I currently get out of using keys.

[jasongitmail]

The keys table could add columns needed for a passkey authentication, if it the table is retained. Keys would not need to be removed, even though it was phrased that way. It's really a separate architecture decision.

[getDanArias]

And I'm considering adding a utility for checking the password strength.

Howdy, @pilcrowOnPaper I wanted to ask you, please, if you ever got into adding that utility to check password strength 🤔 Is there any recommendations you have on how to approach this by chance? Thanks in advance!

[pilcrowOnPaper]

My personal opinion is that, especially in the long term, there is more value for Lucia to focus on documentation and guides, rather than the code itself. What does that mean? Rather than providing database-connected APIs for verification tokens, OAuth, passkeys, etc (ie. do 90% of the backend for you), it'll be more beneficial if we teach people how to implement auth using Lucia, Oslo, and their preferred ORM or query builder. Like, for OAuth, you just need like a few simple database queries. It takes minimum effort. You should be able to do that.

And there lies the issue. If you want to implement auth by yourself, you should be ready to work with your database and put some effort into it. Lucia and Oslo will take care of the details, like session expirations, passkey validation, OAuth requests, and more. But you should at the very least understand the big picture. How OAuth works. How passkeys works. And the docs is the best place to teach that.

Auth isn't easy. A library can only handle so much. And IMO we shouldn't hide that fact.

[ObieMD5]

If you are talking about focusing on documentation and guides that would be displayed in this GitHub repo, we can already do that. If you are talking about adding them to the website, could you set it up in a public repo that we, as the community, can contribute to through pull requests? The former option would be better, as you could update the website with a link to the example in this repo.

[pilcrowOnPaper]

Not sure what you mean? The source for the docs website is in the monorepo, the example is available in lucia-auth/examples repo

[ObieMD5]

Ah, that is my fault, I didn't realize it was all here. I thought this was just for the library. With that being said would you be open to that support from the community?

[pilcrowOnPaper]

yeah most contributions are for the docs

[simonsarris]

I would especially like to see guides on how you (the library author) would structure things in a slightly more complicated mock project. Like an example that showed both username and email as possible logins (via password), plus where other user info would be stored in tables relative to that user data, that could serve as a best-practices project. I hope that makes sense.

Put another way: Good auth lib requires good docs but since its wrapped up in DB stuff it also ideally should gently push the user towards good (or sensible starting) practices, too.

[flipvh]

What you are writing makes a lot of sense @pilcrowOnPaper. I am eager to see where it will go. My 2 cents: I think there is a big market for a low profile, generic and well documented solution. That said, on the other side of the spectrum you have - I believe - a big market for a full-fledged open source implementation which is - with some config and your own frontend - ready to ship. The downside is that it will be an opinionated solution, since you will make this for one set of libraries+framework to keep it maintainable. That said, with good documentation, this can be a very valuable example implementation for the community? My company would be happy to invest/donate in both if you are interested in such a plan. (I hope its clear enough, Its a bit tricky to be sure its well understandable 😄 )

[Ed1ks]

When we started to search for Auth Frameworks which support Vue + Nuxt, we didnt find many, which are production ready. There were some but they are bugged a lot - so not really safe to use.
We tried to archieve using an Auth Provider (Keycloak) for authentication. In many frameworks (dot.net, angular,...) its an pretty easy task. But sadly for nuxt there isnt anything on the market. After lot of research we luckily find lucia. And its idea to cache session in an db is very pretty. So we tried to "install" lucia in our project with keycloak support. Sadly we ended in hours of reverse engineering of lucia to understand every part of it, so we can add key methods in our project, which just are part of authentication and are using lucia-style. For e.g. refreshing tokens.
My question is, what wants lucia to be? A Toolbox for some parts of authentication?
I think Lucia wants to be a grown authentication Framework which offers everything an developer needs for Authentication any maybe in future also Authorization. Lucia should use its potential.

[sieftt]

I've been looking for it for the past few days, and I didn't understand it until your answer. Thank you very much!
Can I do exactly this? https://lucia-auth.com/guides/oauth/custom-providers

[Ed1ks]

This is broadly. You can also check the framework specific tutorial:
https://lucia-auth.com/tutorials/github-oauth/nuxt
and also the example:
https://github.com/lucia-auth/examples/tree/main/nuxt/github-oauth

[sieftt]

Thanks,
I read some documents, but I'm still a little confused.
I use astro in my project. What I'm confused about is:

1. Is the keycloak provider here similar to the github provider?
2. Does the login page here use keycloak login theme?
3. What I mean is that I want to log in through the username and password, but the username and password here are still the specific realm in keycloak, and the user and password of the specific client.

[Ed1ks]

1. It´s pretty similar. You can use the example code and update it with this:
   https://arctic.js.org/providers/keycloak
   and this: https://arctic.js.org/guides/oauth2-pkce

2. The Login Page in the example contains just a link to the provider. The provider provides then also the login page. After successful login you will then redirected back to your page and the callback gets called.

3. Yes, if you use keycloak, you need to login with keycloak username and password. Or you create subprovider in keycloak.

[sieftt]

Thank you very much, as you said, amazing, I successfully got the callback of keycloak！

[ghost]

@pilcrowOnPaper So is there going to be a huge change to Lucia? Was planning on investing some time in figuring out how to implement Lucia with Next.js 14 since I am tired of wasting my time trying to do a work around to get next-auth sessions to be stored in the database.

[jasongitmail]

with Next.js 14 since I am tired of wasting my time trying to do a work around to get next-auth sessions to be stored in the database.

@JuanM2020 AuthJS (formerly next-auth) supports database sessions. As long as AuthJS has the database adapter you need, it should work. (I ran into issues, because I'm using a newer type of DB and the PRs to make it work haven't been merged. So your mileage may vary. But fyi in case helpful.)

[ghost]

@jasongitmail i could be missing something but it is not working for me. could you show me your setup?

[jasongitmail]

I had to remove AuthJS because Turso isn't fully supported and the PRs to make it work have been sitting there for a long time, so I don't have the code handy. But iirc it was two parts: 1.) set session.strategy in your config to 'database' and 2.) set up your database adapter. Someone in their Discussions could probably guide better on the details.

[ghost]

@jasongitmail yeah when I set the strategy to database it say it is not allowed for credentials. maybe this is a recent change

[jasongitmail]

Could be. I only tried OAuth.

[lolcabanon]

@pilcrowOnPaper first of all, very nice of you to start this thread!

As a somewhat experienced but still noob developer, here's my opinion on the subject.

(Keep in mind I consider myself naive on the subject of auth. Even if i've been coding for some years, I have very little professional experience.)

Why I loved using Lucia?

• Easy to set up
• Good documentation
• Flexible/Extensible (where it makes sense)
• Provide safe-enough default (for credentials auth)
• Takes the pain away (sessions, cookies, hashing...)

Migration to an eventual v3

Breaking changes?

I would not care at all migrating (to a keyless implementation or whatever) if there is a guide provided. Since Lucia's doc is understandable, I have no doubt a migration guide would be perfect if you decide to go this route.

Development / Maintenance

I would also be happy to migrate if it means you (as the main maintainer of the project) think you have good reasons for it, and it also means that you'll be happy to maintain it further.

On the other side, i'd be pretty sad to learn that you would deprecate it after v3 because it went too far from you vision.

It is important that you respect youself in the process.

On the subject of Guides / Templates

In my experience, the hardest part was to figure out the auth (sign up, login, logout) workflow. Once all the bits put together, adding a database query here to create a user or verify a hashed password is just routine (let's be honest, i'm already making lots of complex db queries in my app...).

Lucia really helped me pull off a simple template to build a mental model. Even just templates (or even maybe a checklist of crucial steps in order) without the library would have been a substantial help to me.

What i'd like Lucia/Oslo to be

Oslo as primitive utilities is in its place imo.

For Lucia, the best I can think of is something I can give a config to and that would return a collection of utilities to use around my app (much like it is designed now). I kind of think of it as a wrapper around Oslo for common tasks.

I don't really care about details like database schemas or keys, as they are easy to pick up (and adopt) if it makes sense and make my dev life easier. I have trust in people like you to figure out the best approach, as I have never created an auth library as you did.

Also, in my ideal world, all these common tasks could be overriden/extended to offer maximum flexibility.

I saw someone mention Express/Koa in some comment and I think it is a nice way to think about it (mostly middlewares).

Also SvelteKit architecture with load functions, actions and hooks is an awesome model for me. Perfect balance between opinionated (optimal patterns and workflows) and flexible (specific db queries, validation functions, sending TOTP requests to the user with X method as somebody else mentioned).

Another rather random example, but I love the way svelte-headless-table implemented the 'plugin system*, making any instance unique and extensible while providing multiple possibilities and combinations.

Library vs Framework

Not an expert, but I sometimes see the debate of "is React a framework or library?". I don' t use React so I don't know at all, but my point is more about the comparison.

From what i've seen :

Library = you call it in your code (Oslo?)

Framework = wrapper that call your code at the right moment (Lucia?)

This is how I see things from my naive point of view! Hope my take on this can help you clarify the questions that are going around your head!

✌️

Edit :

To add up on that, i'm also really fan of Vanilla JS solutions as it usually doable to use a JS solution in any framework (with a little bit of work of course) but much harder the other way around (ex: port a React lib to Svelte).

[naourass]

I know how to do database queries or fancy algorithms coding, but I don't know how to maintain an authentication flow that is actively up to date with the current best practices or at least the current standards of security in the given scope. The latter is the reason why I look for existing auth libraries for early stage projects, and what I would want from Lucia to provide.

[xsonic]

My 2 cents:

• Current scope is perfect, please don't include any more features. I use Lucia because it is so simple and doesn't do much
• I am completely fine with removing the keys table. Migration should be pretty straight forward.
• I need password auth (for B2B apps and internal tools). All this pushing against it really confuses me.

My reasons for using Lucia:

• minimal
• using DB sessions (and not JWTs)
• PW auth
• acitvely maintained

IMO focus should be on a robust library that is forward compatible to always use best practices on account security and session management.

Great work BTW, and thanks a lot! My first production app using Lucia is going online these days!

[pilcrowOnPaper]

There’s nothing pushing back against passwords here. Lucia will still provide APIs for hashing passwords.

[osseonews]

Just found this library. Wish I found it earlier. Amazing work. As others have already stated: Just keep it simple and maintained. No need to add complexity. And yeah, passwords are critical for most applications and they are not going anywhere, so built in utilities to help with password implementation would be helpful. What I'm confused about is that your guides explain very well how to set up password properly with email verification, preventing throttling etc. What is the issue exactly or am I missing something? What more needs to be done? Assuming you are not operating some financial institution, won't most apps just work fine by following those guides?

[ArmantG]

My 2 cents as someone who has followed the development of Lucia but has never used it in a project
When I initially saw Lucia I thought of it as an auth library as opposed to a framework, I like libraries that provide low level building blocks allowing us more control over every step involved

I don't get why libraries are discouraging password authentication, it is by far the most popular method of authentication and the way to move away is not to persuade developers but rather users, I think every auth library should fully support it and the fact that it hard to pull of is all the more reason for libraries to support it so we don't have to worry about security

Certainly agree with this. If password auth is such an issue, why not make it CLEARER in the docs how to implement this properly and what steps to take instead of actively discouraging it and limiting the docs on this topic. And they can say as much as they want they arent purposely limiting the documentation on this topic, but they are by only including the base monimum required to make it work... In some cases not even that.

Would rather like to see more complete docs. They only whay devs will implement this properly is by the "experts" who offer the library educating, especially new devs, how to do it properly.

In some countries, email and password is the only option for auth. But by limiting the docs and access to this feature, these devs end up implementing auth strategies that are unusable in their target markets... Typically github auth in tuts, my users dont even know 99% of these auth providers. Anyway... Find it hard to learn and get better as a dev from the docs since there is little info there to help you in the right direction.

Completely reliant on some guy on YouTube feeling like tackling this and making a video to help other devs with whatever since no one else will.
Auth JS's svelte docs are just nowhere. So even harder there...

[Qodestackr]

It will be interesting for me to watch how this project evolves. Having the ability to bring and swap out pieces as needed is a great feature.