Today's Work
I decided on and implemented the login flow for Lime v1.
At first, I considered supporting both OAuth login and email/password sign-up. However, building email sign-up properly would bring in many additional features, such as password hashing, email verification, and password recovery.
At this stage, I wanted to move quickly and focus on the core product. So for v1, I decided to support only Google and Discord OAuth.
In Lime v1, users do not sign up with an email and password.
They log in with a Google or Discord account, and the backend automatically creates Lime's
User.
After a successful login, the backend issues a JWT Access Token and a Refresh Token for our service.
What I Built
- Google OAuth login
- Discord OAuth login
- OAuth callback handling
- Automatic Lime
Usercreation on first login - Linking OAuth accounts to existing users
- JWT Access Token issuance
- Refresh Token issuance and storage
- Refresh Token rotation
- Logout
- Handling OAuth failure and cancellation cases
Overall Flow
At first, I thought OAuth was simply about adding a "social login" button.
But the actual flow was longer than I expected.
Frontend
-> Backend: /auth/google/start
-> Google OAuth Page
-> Backend: /auth/google/callback?code=...&state=...
-> Google UserInfo API
-> Create or find Lime User
-> Issue JWT Access Token + Refresh Token
I designed the APIs like this.
GET /auth/{provider}/start
GET /auth/{provider}/callback
POST /auth/refresh
POST /auth/signout
Currently, there are two supported providers.
google
discord
Splitting It with VSA
This project is built with Vertical Slice Architecture, not around MVC Controllers.
So I did not put all authentication logic into one large controller. Instead, I split it by feature flow.
Features/Auth
StartOAuthLogin
HandleOAuthCallback
RefreshSession
SignOut
OAuth
Users
Sessions
Cookies
At first, having more files made it look more complicated.
But OAuth mixes several responsibilities.
- Redirecting to the provider
- Handling the callback
- Finding or creating a user
- Issuing tokens
- Writing cookies
- Handling failure cases
Putting all of this into one file would be faster at first, but it would probably become harder to read later.
So this time, I chose to split the code by flow.
Provider Abstraction
Google and Discord have similar OAuth flows, but they use different URLs and return different userinfo response formats.
So I created a common interface.
internal interface IOAuthProvider
{
string Name { get; }
string BuildAuthorizeUrl(string state, string redirectUri);
Task<OAuthUserInfo> ExchangeAndFetchAsync(
string code,
string redirectUri,
CancellationToken ct);
}
Each provider has its own implementation.
GoogleOAuthProvider
DiscordOAuthProvider
The callback endpoint finds and uses the correct provider based on the provider name.
If I add Apple login later, I can extend this by adding an AppleOAuthProvider and registering it in DI.
The Most Confusing Part: Cookies and State
The most confusing part of this work was cookies.
Cookies are used by the browser, so why am I creating cookies in backend OAuth code?
At first, I could not fully understand this.
But OAuth is a flow that goes through browser redirects.
Because of that, the backend needs a way to temporarily remember values between requests.
A typical example is state.
Where state Is Stored
When OAuth starts, the backend creates a random state value.
Then it stores this value in two places.
1. The query string of the provider authorize URL
2. A browser cookie
When the provider redirects back to the callback endpoint, it includes the state value in the query string.
The backend compares the state from the callback with the state stored in the cookie.
Same -> Valid OAuth flow
Different -> Reject
This is used to prevent CSRF attacks.
In this implementation, I created temporary cookies for the OAuth flow.
lime_oauth_state -> State value for CSRF protection
lime_oauth_return -> Path to return to after successful login
Since both values do not need to live for a long time, I made them short-lived cookies and deleted them after the callback was handled.
returnTo Should Not Be Trusted As-Is
To send users back to the original page after a successful login, I accepted a returnTo value.
However, this value should not be trusted as-is.
For example, redirecting directly to values like these can be dangerous.
https://evil.com
//evil.com
\evil
So I did not allow external URLs and only allowed internal paths.
/dashboard
/profile
It is a small detail, but for a login feature, these details matter.
Linking Users and OAuth Accounts
Lime has its own User, and OAuth provider account information is stored in a separate table.
users
user_oauth_accounts
refresh_tokens
In OAuth login, the most reliable identifier is not the email address.
It is this combination.
provider + providerUserId
An email address can change, and whether it is verified depends on the provider.
So during login, I first look for an existing OAuth account using provider + providerUserId.
OAuth account already linked
-> Log in as that User
OAuth account not linked
-> If the email is verified, link it to an existing User
-> Otherwise, create a new User
At first, it is easy to think, "If the email is the same, isn't it the same user?"
But in authentication, whether the email is verified matters.
JWT and Refresh Tokens
I did not use the OAuth provider's access token directly for Lime API authentication.
Google or Discord access tokens are meant for calling the provider's APIs.
The token used to call Lime APIs should be issued by our own service.
After a successful login, I issue two tokens.
| Token | Purpose |
|---|---|
| Access Token | Authenticate Lime API requests |
| Refresh Token | Reissue Access Tokens |
The Access Token is a JWT.
It contains minimal claims such as the user ID, email, and name, and it has a short lifetime.
The Refresh Token is a random string and is stored in the database.
However, I do not store the raw token. I only store its SHA-256 hash.
When a Refresh Token is used, the existing token is revoked and a new one is issued.
This is called refresh token rotation.
Keep the Access Token short-lived and the Refresh Token longer-lived.
But make sure the Refresh Token can be controlled through the database.
That was the basic direction for this implementation.
Storing Tokens in Cookies
In this implementation, both the Access Token and Refresh Token are stored in HttpOnly cookies.
Storing tokens in localStorage is also possible, but considering XSS, HttpOnly cookies can be a safer choice.
HttpOnly cookies cannot be read by JavaScript.
However, when using cookies, CSRF also needs to be considered.
So I explicitly configured options such as SameSite, Secure, and Path.
Also, ASP.NET Core's JWT Bearer authentication looks for the token in the Authorization header by default.
Since I store the access token in a cookie, I configured the authentication middleware to read the token from the cookie.
If this part is missed, tokens may be issued successfully, but APIs that require authentication will still treat the request as unauthenticated.
Response Format
I also defined a response format to align with the frontend.
Instead of returning a human-readable message in failure responses, I decided to return a stable code.
{
"code": "INVALID_REFRESH_TOKEN",
"data": null
}
The frontend can use this code to decide what message to show to the user.
This keeps localization and UI wording changes separate from the backend.
I also handled the OAuth cancellation case separately.
OAUTH_CANCELLED
When a user cancels on the provider's authentication page, it is closer to a normal failure flow than a system error.
So I separated it from ordinary missing-parameter cases.
What I Learned About Configuration
I also ran into an issue while binding configuration with IOptions<AuthOptions>.
The path the code expected was different from the actual structure in appsettings.json.
Expected by code: Auth:Jwt:SigningKey
Actual setting: Jwt:SigningKey
Even when a value is empty, it is not always obvious at first.
This is especially important for Jwt:SigningKey, because if it is empty, the backend cannot create or validate JWTs.
One thing I learned from this is that configuration values are just as important as code.
OAuth Client ID/Secret, JWT SigningKey, and database connection settings live outside the code, but they are core parts of making the feature actually work.
Summary
With this work, the authentication foundation for Lime v1 is now in place.
What I built was not just a "Google login button."
In practice, all of these pieces had to work together.
- OAuth redirect flow
-
statefor CSRF protection - Temporary OAuth cookies
- Safe
returnTohandling - Fetching user information from the provider
- Automatic Lime
Usercreation - Linking OAuth accounts
- JWT Access Token issuance
- Refresh Token storage and rotation
- Logout
- Response codes aligned with the frontend
OAuth requires more surrounding design than I expected.
The successful login path may look simple, but for a real service, user mapping, token storage, cookie security, and failure cases all need to be considered together.
Next, I plan to apply this authentication middleware to protected APIs and align the frontend behavior around these response codes.