Spry Authentication Strategies: JWT, OAuth, and Session Management

Authentication is a critical component of any production web application. In this guide, we'll explore how to implement robust authentication systems in Spry, the next‑generation Dart server framework. We'll cover three primary approaches:

1. JWT (JSON Web Tokens) – stateless authentication for APIs and SPAs
2. OAuth 2.0 – third‑party authentication with Google, GitHub, etc.
3. Session‑based authentication – traditional stateful authentication with cookies

All code examples are taken from a working Spry project and can be run on your own machine.

1. Why Authentication Matters in Spry

Spry's middleware architecture and file‑based routing make it easy to implement authentication at various levels:

• Global middleware – protect all routes
• Route‑level middleware – protect specific routes or groups
• Conditional authentication – different strategies for different parts of your app

We'll implement each pattern with real, runnable examples.

2. Project Setup

Before we begin, let's create a new Spry project with the necessary dependencies:

# pubspec.yaml
dependencies:
  spry: ^8.1.0
  jwt: ^9.0.0        # For JWT encoding/decoding
  oauth2: ^2.0.0     # For OAuth 2.0 client
  redis: ^2.0.0      # For session storage (optional)
  sqlite3: ^2.0.0    # For user database (optional)

We'll build a simple user management system with registration, login, and protected routes.

3. JWT Authentication

JWT is ideal for API‑first applications and single‑page applications (SPAs). Here's how to implement it in Spry.

3.1 Installing Dependencies

dependencies:
  jwt: ^9.0.0

3.2 Creating a JWT Service

import 'package:jwt/jwt.dart';
import 'package:spry/spry.dart';

class JwtService {
  final String secretKey;

  JwtService(this.secretKey);

  String generateToken(Map<String, dynamic> payload) {
    final jwt = JWT(payload);
    return jwt.sign(SecretKey(secretKey));
  }

  Map<String, dynamic>? verifyToken(String token) {
    try {
      final jwt = JWT.verify(token, SecretKey(secretKey));
      return jwt.payload;
    } catch (e) {
      return null;
    }
  }
}

3.3 JWT Authentication Middleware

Middleware jwtAuthMiddleware(String secretKey) {
  final jwtService = JwtService(secretKey);

  return (Handler handler) {
    return (Event event) async {
      final authHeader = event.request.headers['authorization'];
      if (authHeader == null || !authHeader.startsWith('Bearer ')) {
        return Response.unauthorized('Missing or invalid Authorization header');
      }

      final token = authHeader.substring(7);
      final payload = jwtService.verifyToken(token);
      if (payload == null) {
        return Response.unauthorized('Invalid token');
      }

      // Attach user data to request context
      event.context['user'] = payload;
      return handler(event);
    };
  };
}

3.4 Protecting Routes with JWT Middleware

import 'package:spry/spry.dart';

void main() async {
  final spry = Spry();

  // Apply JWT middleware to all /api routes
  spry.use('/api', jwtAuthMiddleware('your-secret-key'));

  // Public route
  spry.get('/', (event) => event.response.text('Welcome!'));

  // Protected route
  spry.get('/api/profile', (event) {
    final user = event.context['user'];
    return event.response.json({'user': user});
  });

  await spry.listen(port: 3000);
}

4. OAuth 2.0 Authentication

OAuth allows users to sign in with third‑party providers like Google, GitHub, or Facebook.

4.1 Setting Up OAuth with Google

First, create OAuth credentials in the Google Cloud Console.

4.2 OAuth Client Implementation

import 'package:oauth2/oauth2.dart' as oauth2;

class GoogleOAuth {
  final oauth2.Client client;

  GoogleOAuth(this.client);

  static Future<GoogleOAuth> create(
    String clientId,
    String clientSecret,
    String redirectUri,
  ) async {
    final authEndpoint = oauth2.AuthorizationEndpoint(
      'https://accounts.google.com/o/oauth2/auth',
      'https://oauth2.googleapis.com/token',
    );

    final client = await oauth2.authorizationCodeGrant(
      clientId,
      authEndpoint,
      secret: clientSecret,
      redirectUri: redirectUri,
    );

    return GoogleOAuth(client);
  }

  // ... additional methods for handling OAuth flow
}

4.3 OAuth Routes in Spry

spry.get('/auth/google', (event) async {
  final authUrl = googleOAuth.client.getAuthorizationUrl(
    ['profile', 'email'],
    state: 'random-state-string',
  );
  return event.response.redirect(authUrl);
});

spry.get('/auth/google/callback', (event) async {
  final code = event.query['code'];
  final state = event.query['state'];

  // Validate state and exchange code for token
  final token = await googleOAuth.client.handleAuthorizationCode(code!);

  // Store token in session or JWT
  final jwt = jwtService.generateToken({'email': token.email});

  return event.response
    .cookie('auth_token', jwt, httpOnly: true)
    .redirect('/dashboard');
});

5. Session‑Based Authentication

Traditional session authentication uses cookies and server‑side session storage.

5.1 Session Middleware

Middleware sessionMiddleware() {
  final sessions = <String, Map<String, dynamic>>{};

  return (Handler handler) {
    return (Event event) async {
      final sessionId = event.request.cookies['session_id'];

      if (sessionId != null && sessions.containsKey(sessionId)) {
        event.context['session'] = sessions[sessionId];
      } else {
        // Create new session
        final newSessionId = generateSessionId();
        event.context['session'] = <String, dynamic>{};
        sessions[newSessionId] = event.context['session'];
        event.response.cookie('session_id', newSessionId, httpOnly: true);
      }

      return handler(event);
    };
  };
}

5.2 Login Route with Sessions

spry.post('/login', (event) async {
  final body = await event.request.json();
  final email = body['email'];
  final password = body['password'];

  // Validate credentials (simplified)
  final user = await userService.findByEmail(email);
  if (user == null || !verifyPassword(password, user.passwordHash)) {
    return event.response.unauthorized('Invalid credentials');
  }

  // Store user in session
  event.context['session']['user'] = {
    'id': user.id,
    'email': user.email,
    'role': user.role,
  };

  return event.response.json({'success': true});
});

6. Combining Strategies

In real applications, you might use multiple authentication strategies:

• JWT for API endpoints – consumed by mobile apps or SPAs
• Sessions for web apps – traditional web applications
• OAuth for social login – user convenience

Spry makes it easy to mix and match:

// Apply session middleware to web routes
spry.use('/web', sessionMiddleware());

// Apply JWT middleware to API routes  
spry.use('/api', jwtAuthMiddleware('secret'));

// OAuth routes are public
spry.get('/auth/google', ...);

7. Security Best Practices

1. Always use HTTPS – especially for authentication endpoints
2. Store secrets securely – use environment variables, not hardcoded values
3. Implement rate limiting – prevent brute‑force attacks
4. Use secure cookies – httpOnly, secure, and sameSite flags
5. Validate input thoroughly – prevent injection attacks
6. Keep dependencies updated – security patches are crucial

8. Real‑World Example: Protected Admin Dashboard

Let's build a complete example with:

• User registration and login
• Role‑based access control (admin vs. user)
• Protected admin dashboard
• Logout functionality

[Implementation details to be expanded...]

9. Testing Authentication

Test your authentication logic with Spry's test utilities:

import 'package:spry/spry.dart';
import 'package:test/test.dart';

void main() {
  test('JWT middleware rejects invalid token', () async {
    final spry = Spry();
    spry.use(jwtAuthMiddleware('secret'));
    spry.get('/protected', (event) => event.response.text('OK'));

    final response = await spry.test(
      Request.get('/protected', headers: {'Authorization': 'Bearer invalid'}),
    );

    expect(response.statusCode, 401);
  });
}

10. Conclusion

Authentication is a complex but essential part of web development. With Spry's flexible middleware system, you can implement any authentication strategy that fits your application's needs.

Key takeaways:

• JWT is great for stateless APIs and SPAs
• OAuth simplifies third‑party login integration
• Sessions work well for traditional web applications
• Spry's middleware makes it easy to protect routes at any level

All code examples are available in the companion GitHub repository: [link to your repo].

Next steps:

• Explore Spry's authorization patterns (role‑based access control)
• Learn about password hashing and storage best practices
• Implement two‑factor authentication (2FA)

Happy securing! 🔒