Authentication System
Auth.js v5 multi-provider authentication with magic links, OAuth providers, crypto wallets, and GDPR compliance.
v1.6.4 protection model
| Layer | Role |
|---|
proxy.ts | Locale rewrite + optimistic redirect to ROUTES.LOGIN(locale) (cookie presence only — not session validity) |
(authenticated)/[locale]/layout.tsx | await auth() — canonical session gate |
(admin)/[locale]/layout.tsx | Role check (admin/superadmin) |
/login | LoginAuthenticatedRedirect — client useSession bounce when genuinely authenticated (avoids stale-cookie loops; skips during OAuth callback query params) |
| API routes | Per-handler auth() |
OAuth and Google One Tap use /api/auth/* (excluded from intl middleware). See Proxy and intl.
Login canonical pattern: ROUTES.LOGIN(locale) with unified from / callbackUrl / returnTo query params. Implementation: features/auth/components/login-authenticated-redirect.tsx.
Overview
Ring Platform uses Auth.js v5 to provide seamless authentication across multiple providers while maintaining security and user privacy.
Authentication Providers
Magic Links
- Passwordless Authentication - Email-based secure login
- One-click Access - No password required
- Secure Tokens - Time-limited access tokens
- GDPR Compliant - Privacy-first approach
OAuth Providers
- Google - Primary OAuth provider for web and mobile
- Apple - iOS/macOS native integration with Sign in with Apple
- GitHub - Developer-focused authentication
- Discord - Community platform integration
Apple Sign-in Integration
Ring Platform supports seamless Sign in with Apple integration using Auth.js v5.
Prerequisites
Before setting up Apple Sign-in, ensure you have:
- Apple Developer Account - Paid developer account ($99/year)
- App ID - Registered app identifier (e.g.,
com.yourcompany.yourapp)
- Service ID - For web authentication (e.g.,
com.yourcompany.auth)
- Private Key - Generated from Apple Developer portal
- Team ID - From your Apple Developer account
Apple Developer Portal Setup
-
Create App ID:
- Go to Certificates, Identifiers & Profiles
- Click + → Choose App IDs
- Register your app with bundle ID (e.g.,
com.sonoratek.ring)
- Enable Sign in with Apple capability
-
Create Service ID:
- Under Identifiers → Click + → Choose Services IDs
- Create service ID (e.g.,
com.sonoratek.ring-auth)
- Enable Sign in with Apple
- Configure Return URLs (your app's callback URLs)
-
Generate Private Key:
- Go to Keys → Click +
- Name your key (e.g., "Auth Key for Ring Platform")
- Enable Sign in with Apple
- Select your App ID
- Download the
.p8 private key file (keep it secure!)
Environment Configuration
Add these variables to your .env.local:
Apple Sign-in Configuration
JWT Generation
Apple requires a JWT signed with your private key. Use this Node.js script:
Auth.js v5 Configuration
Apple Sign-in is automatically configured in your auth.config.ts:
Usage in Components
User Experience Features
- One-tap authentication on Apple devices
- Privacy-focused - No email collection without user consent
- Secure token exchange - Server-side validation
- Account linking - Connect with existing accounts
- Cross-platform support - Works on web and mobile
Security Considerations
- Private key protection - Never commit
.p8 files to version control
- JWT expiration - Regenerate tokens every 6 months
- Environment isolation - Use different keys for dev/staging/production
- Audit logging - Track authentication events
- Rate limiting - Protect against abuse
Troubleshooting
Common Issues:
- "Invalid client" error: Verify
AUTH_APPLE_ID matches your Service ID
- "Invalid JWT" error: Check JWT generation and expiration
- "Domain verification failed": Ensure return URLs are properly configured
- "Key not found" error: Verify private key is accessible and correct
Debug Tips:
- Check server logs for detailed error messages
- Verify JWT payload structure and signature
- Test with Apple's developer tools
- Ensure proper domain verification in Apple Developer portal
Crypto Wallets
- MetaMask - Ethereum wallet authentication
- WalletConnect - Multi-wallet support
- Coinbase Wallet - Mainstream crypto wallet
- Trust Wallet - Mobile-first wallet integration
Implementation
Authentication Setup
Role-Based Access
// Check user role
Documentation in progress
Complete authentication documentation is being expanded.
Authentication System
Auth.js v5 multi-provider authentication with magic links, OAuth providers, crypto wallets, and GDPR compliance.
v1.6.4 protection model
| Layer | Role |
|---|
proxy.ts | Locale rewrite + optimistic redirect to ROUTES.LOGIN(locale) (cookie presence only — not session validity) |
(authenticated)/[locale]/layout.tsx | await auth() — canonical session gate |
(admin)/[locale]/layout.tsx | Role check (admin/superadmin) |
/login | LoginAuthenticatedRedirect — client useSession bounce when genuinely authenticated (avoids stale-cookie loops; skips during OAuth callback query params) |
| API routes | Per-handler auth() |
OAuth and Google One Tap use /api/auth/* (excluded from intl middleware). See Proxy and intl.
Login canonical pattern: ROUTES.LOGIN(locale) with unified from / callbackUrl / returnTo query params. Implementation: features/auth/components/login-authenticated-redirect.tsx.
Overview
Ring Platform uses Auth.js v5 to provide seamless authentication across multiple providers while maintaining security and user privacy.
Authentication Providers
Magic Links
- Passwordless Authentication - Email-based secure login
- One-click Access - No password required
- Secure Tokens - Time-limited access tokens
- GDPR Compliant - Privacy-first approach
OAuth Providers
- Google - Primary OAuth provider for web and mobile
- Apple - iOS/macOS native integration with Sign in with Apple
- GitHub - Developer-focused authentication
- Discord - Community platform integration
Apple Sign-in Integration
Ring Platform supports seamless Sign in with Apple integration using Auth.js v5.
Prerequisites
Before setting up Apple Sign-in, ensure you have:
- Apple Developer Account - Paid developer account ($99/year)
- App ID - Registered app identifier (e.g.,
com.yourcompany.yourapp)
- Service ID - For web authentication (e.g.,
com.yourcompany.auth)
- Private Key - Generated from Apple Developer portal
- Team ID - From your Apple Developer account
Apple Developer Portal Setup
-
Create App ID:
- Go to Certificates, Identifiers & Profiles
- Click + → Choose App IDs
- Register your app with bundle ID (e.g.,
com.sonoratek.ring)
- Enable Sign in with Apple capability
-
Create Service ID:
- Under Identifiers → Click + → Choose Services IDs
- Create service ID (e.g.,
com.sonoratek.ring-auth)
- Enable Sign in with Apple
- Configure Return URLs (your app's callback URLs)
-
Generate Private Key:
- Go to Keys → Click +
- Name your key (e.g., "Auth Key for Ring Platform")
- Enable Sign in with Apple
- Select your App ID
- Download the
.p8 private key file (keep it secure!)
Environment Configuration
Add these variables to your .env.local:
Apple Sign-in Configuration
JWT Generation
Apple requires a JWT signed with your private key. Use this Node.js script:
Auth.js v5 Configuration
Apple Sign-in is automatically configured in your auth.config.ts:
Usage in Components
User Experience Features
- One-tap authentication on Apple devices
- Privacy-focused - No email collection without user consent
- Secure token exchange - Server-side validation
- Account linking - Connect with existing accounts
- Cross-platform support - Works on web and mobile
Security Considerations
- Private key protection - Never commit
.p8 files to version control
- JWT expiration - Regenerate tokens every 6 months
- Environment isolation - Use different keys for dev/staging/production
- Audit logging - Track authentication events
- Rate limiting - Protect against abuse
Troubleshooting
Common Issues:
- "Invalid client" error: Verify
AUTH_APPLE_ID matches your Service ID
- "Invalid JWT" error: Check JWT generation and expiration
- "Domain verification failed": Ensure return URLs are properly configured
- "Key not found" error: Verify private key is accessible and correct
Debug Tips:
- Check server logs for detailed error messages
- Verify JWT payload structure and signature
- Test with Apple's developer tools
- Ensure proper domain verification in Apple Developer portal
Crypto Wallets
- MetaMask - Ethereum wallet authentication
- WalletConnect - Multi-wallet support
- Coinbase Wallet - Mainstream crypto wallet
- Trust Wallet - Mobile-first wallet integration
Implementation
Authentication Setup
Role-Based Access
// Check user role
Documentation in progress
Complete authentication documentation is being expanded.
Authentication System
Auth.js v5 multi-provider authentication with magic links, OAuth providers, crypto wallets, and GDPR compliance.
v1.6.4 protection model
| Layer | Role |
|---|
proxy.ts | Locale rewrite + optimistic redirect to ROUTES.LOGIN(locale) (cookie presence only — not session validity) |
(authenticated)/[locale]/layout.tsx | await auth() — canonical session gate |
(admin)/[locale]/layout.tsx | Role check (admin/superadmin) |
/login | LoginAuthenticatedRedirect — client useSession bounce when genuinely authenticated (avoids stale-cookie loops; skips during OAuth callback query params) |
| API routes | Per-handler auth() |
OAuth and Google One Tap use /api/auth/* (excluded from intl middleware). See Proxy and intl.
Login canonical pattern: ROUTES.LOGIN(locale) with unified from / callbackUrl / returnTo query params. Implementation: features/auth/components/login-authenticated-redirect.tsx.
Overview
Ring Platform uses Auth.js v5 to provide seamless authentication across multiple providers while maintaining security and user privacy.
Authentication Providers
Magic Links
- Passwordless Authentication - Email-based secure login
- One-click Access - No password required
- Secure Tokens - Time-limited access tokens
- GDPR Compliant - Privacy-first approach
OAuth Providers
- Google - Primary OAuth provider for web and mobile
- Apple - iOS/macOS native integration with Sign in with Apple
- GitHub - Developer-focused authentication
- Discord - Community platform integration
Apple Sign-in Integration
Ring Platform supports seamless Sign in with Apple integration using Auth.js v5.
Prerequisites
Before setting up Apple Sign-in, ensure you have:
- Apple Developer Account - Paid developer account ($99/year)
- App ID - Registered app identifier (e.g.,
com.yourcompany.yourapp)
- Service ID - For web authentication (e.g.,
com.yourcompany.auth)
- Private Key - Generated from Apple Developer portal
- Team ID - From your Apple Developer account
Apple Developer Portal Setup
-
Create App ID:
- Go to Certificates, Identifiers & Profiles
- Click + → Choose App IDs
- Register your app with bundle ID (e.g.,
com.sonoratek.ring)
- Enable Sign in with Apple capability
-
Create Service ID:
- Under Identifiers → Click + → Choose Services IDs
- Create service ID (e.g.,
com.sonoratek.ring-auth)
- Enable Sign in with Apple
- Configure Return URLs (your app's callback URLs)
-
Generate Private Key:
- Go to Keys → Click +
- Name your key (e.g., "Auth Key for Ring Platform")
- Enable Sign in with Apple
- Select your App ID
- Download the
.p8 private key file (keep it secure!)
Environment Configuration
Add these variables to your .env.local:
Apple Sign-in Configuration
JWT Generation
Apple requires a JWT signed with your private key. Use this Node.js script:
Auth.js v5 Configuration
Apple Sign-in is automatically configured in your auth.config.ts:
Usage in Components
User Experience Features
- One-tap authentication on Apple devices
- Privacy-focused - No email collection without user consent
- Secure token exchange - Server-side validation
- Account linking - Connect with existing accounts
- Cross-platform support - Works on web and mobile
Security Considerations
- Private key protection - Never commit
.p8 files to version control
- JWT expiration - Regenerate tokens every 6 months
- Environment isolation - Use different keys for dev/staging/production
- Audit logging - Track authentication events
- Rate limiting - Protect against abuse
Troubleshooting
Common Issues:
- "Invalid client" error: Verify
AUTH_APPLE_ID matches your Service ID
- "Invalid JWT" error: Check JWT generation and expiration
- "Domain verification failed": Ensure return URLs are properly configured
- "Key not found" error: Verify private key is accessible and correct
Debug Tips:
- Check server logs for detailed error messages
- Verify JWT payload structure and signature
- Test with Apple's developer tools
- Ensure proper domain verification in Apple Developer portal
Crypto Wallets
- MetaMask - Ethereum wallet authentication
- WalletConnect - Multi-wallet support
- Coinbase Wallet - Mainstream crypto wallet
- Trust Wallet - Mobile-first wallet integration
Implementation
Authentication Setup
Role-Based Access
// Check user role
Documentation in progress
Complete authentication documentation is being expanded.
