Oolvay uses Better Auth for authentication. Out of the box, it supports multiple sign-in methods, including Google OAuth, GitHub OAuth, Passkeys, and Magic Links.
Not all providers have the same requirements. Google OAuth, GitHub OAuth, and Passkeys can be configured immediately after installation. Magic Links require a transactional email provider and are covered separately in the Email guide.
| Method | Requires |
|---|---|
| Google OAuth | Google Cloud credentials |
| GitHub OAuth | GitHub OAuth application |
| Passkeys | No external provider |
| Magic Links | Transactional email provider |
| Email verification | Transactional email provider |
| Enterprise SSO (OIDC, SAML) | An identity provider connected by an administrator, see Enterprise SSO |
If you have just completed the installation guide, start with Google OAuth or GitHub OAuth. They are the fastest methods to configure and test.
Create a Google OAuth application.
Configure the OAuth application. In the Google OAuth Client settings, add the following authorized redirect URI.
0 / 2,000 characters
| Field | Value |
|---|---|
| Authorized redirect URI | http://localhost:3000/api/auth/callback/google |
| Field | Value |
|---|---|
| Authorized redirect URI | https://yourdomain.com/api/auth/callback/google |
Copy the generated credentials. Google will provide a Client ID and a Client Secret.
Add the credentials to .env.local.
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=Restart the development server after adding or changing authentication environment variables.
Test the integration.
Start the development server:
bun devThen visit:
http://localhost:3000/loginConfirm that authentication completes successfully.
Create a GitHub OAuth application.
Configure the OAuth application. In the GitHub OAuth application settings, enter the following values.
| Field | Value |
|---|---|
| Homepage URL | http://localhost:3000 |
| Authorization callback URL | http://localhost:3000/api/auth/callback/github |
| Field | Value |
|---|---|
| Homepage URL | https://yourdomain.com |
| Authorization callback URL | https://yourdomain.com/api/auth/callback/github |
Copy the generated credentials. GitHub will provide a Client ID and a Client Secret.
Add the credentials to .env.local.
AUTH_GITHUB_CLIENT_ID=
AUTH_GITHUB_CLIENT_SECRET=Restart the development server after adding or changing authentication environment variables.
Test the integration.
Start the development server:
bun devThen visit:
http://localhost:3000/loginConfirm that the GitHub sign-in button redirects to GitHub and successfully returns to your application.
Passkeys allow users to authenticate using device-based credentials such as Face ID, Touch ID, Windows Hello, or hardware security keys.
No third-party provider is required.
Passkeys work during local development, but production deployments should use HTTPS to ensure full browser compatibility.
Magic Links require a transactional email provider.
See the Email guide before enabling this authentication method.
Ensure the callback URL configured in your OAuth provider exactly matches the callback URL used by Oolvay.
| Provider | Local development |
|---|---|
http://localhost:3000/api/auth/callback/google | |
| GitHub | http://localhost:3000/api/auth/callback/github |
For production, replace localhost:3000 with your own custom domain.
Confirm that:
NEXT_PUBLIC_APP_URL is correctBETTER_AUTH_URL is correctPasskeys require a compatible browser and device. For production deployments, ensure your application is served over HTTPS.