JWT Authentication in Flutter Apps

Published: March 10, 2025 By: JWT Decode Team Category: Mobile Development

Implementing secure authentication is a crucial aspect of any mobile application. JSON Web Tokens (JWT) provide a modern, stateless approach to authentication that works exceptionally well with Flutter applications. This guide will walk you through implementing JWT authentication in Flutter apps from start to finish.

Understanding JWT in Mobile Context
Authentication Flow in Flutter
Setting Up Dependencies
Creating the Authentication Service
Secure Token Storage
Building the Login Screen
Implementing Protected Routes
Token Refresh Mechanism
Testing Authentication

Understanding JWT in Mobile Context

JSON Web Tokens (JWT) are particularly well-suited for mobile applications due to their stateless nature and compact size. When using JWT in Flutter applications, you can:

Reduce server load by eliminating session storage
Support offline authentication validation
Scale your backend more easily
Create a consistent auth experience across platforms

A typical JWT consists of three parts separated by dots: header, payload, and signature.

// Example JWT structure
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

// Decoded parts:
// Header: {"alg":"HS256","typ":"JWT"}
// Payload: {"sub":"1234567890","name":"John Doe","iat":1516239022}
// Signature: HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)

Authentication Flow in Flutter

The JWT authentication flow in a Flutter application typically works as follows:

User enters credentials on the login screen
App sends credentials to authentication server
Server validates credentials and returns JWT tokens (access token and refresh token)
App securely stores the tokens using Flutter Secure Storage
For subsequent API requests, the access token is included in the Authorization header
When the access token expires, the app uses the refresh token to get a new access token
On logout, tokens are removed from storage

Setting Up Dependencies

Start by adding the necessary dependencies to your pubspec.yaml file:

dependencies:
  flutter:
    sdk: flutter
  http: ^0.13.4
  flutter_secure_storage: ^5.0.2
  provider: ^6.0.2
  jwt_decoder: ^2.0.1

Each of these packages serves a specific purpose:

http: For making API requests to your authentication server
flutter_secure_storage: For securely storing JWT tokens
provider: For state management of authentication state
jwt_decoder: For decoding and validating JWT tokens

After adding these dependencies, run:

flutter pub get

Creating the Authentication Service

Create an authentication service class to handle all authentication-related operations:

// lib/services/auth_service.dart
import 'dart:convert';
import 'package:http/http.dart' as http;
import 'package:flutter_secure_storage/flutter_secure_storage.dart';
import 'package:jwt_decoder/jwt_decoder.dart';

class AuthService {
  final String baseUrl = 'https://your-api.com/auth';
  final storage = FlutterSecureStorage();

  // Keys for storage
  final String accessTokenKey = 'access_token';
  final String refreshTokenKey = 'refresh_token';

  // Login method
  Future login(String email, String password) async {
    try {
      final response = await http.post(
        Uri.parse('$baseUrl/login'),
        headers: {'Content-Type': 'application/json'},
        body: json.encode({
          'email': email,
          'password': password,
        }),
      );

      if (response.statusCode == 200) {
        final responseData = json.decode(response.body);
        
        // Store tokens
        await storage.write(key: accessTokenKey, value: responseData['access_token']);
        await storage.write(key: refreshTokenKey, value: responseData['refresh_token']);
        
        return true;
      }
      return false;
    } catch (e) {
      print('Login error: $e');
      return false;
    }
  }

  // Check if user is logged in
  Future isLoggedIn() async {
    try {
      final token = await storage.read(key: accessTokenKey);
      
      if (token == null) {
        return false;
      }
      
      // Check if token is expired
      bool isExpired = JwtDecoder.isExpired(token);
      
      if (isExpired) {
        // Try to refresh token
        bool refreshed = await refreshToken();
        return refreshed;
      }
      
      return true;
    } catch (e) {
      return false;
    }
  }

  // Get the access token
  Future getAccessToken() async {
    return await storage.read(key: accessTokenKey);
  }

  // Refresh token
  Future refreshToken() async {
    try {
      final refreshToken = await storage.read(key: refreshTokenKey);
      
      if (refreshToken == null) {
        return false;
      }
      
      final response = await http.post(
        Uri.parse('$baseUrl/refresh'),
        headers: {'Content-Type': 'application/json'},
        body: json.encode({
          'refresh_token': refreshToken,
        }),
      );
      
      if (response.statusCode == 200) {
        final responseData = json.decode(response.body);
        
        // Store new access token
        await storage.write(key: accessTokenKey, value: responseData['access_token']);
        
        // Sometimes the API returns a new refresh token too
        if (responseData.containsKey('refresh_token')) {
          await storage.write(key: refreshTokenKey, value: responseData['refresh_token']);
        }
        
        return true;
      }
      return false;
    } catch (e) {
      print('Token refresh error: $e');
      return false;
    }
  }

  // Logout
  Future logout() async {
    try {
      // Call logout endpoint if your API has one
      // ...
      
      // Clear stored tokens
      await storage.delete(key: accessTokenKey);
      await storage.delete(key: refreshTokenKey);
    } catch (e) {
      print('Logout error: $e');
    }
  }

  // Get user info from token
  Map getUserInfo() {
    try {
      final token = storage.read(key: accessTokenKey);
      if (token != null) {
        return JwtDecoder.decode(token);
      }
      return {};
    } catch (e) {
      return {};
    }
  }
}

Secure Token Storage

Flutter Secure Storage provides a secure way to store sensitive information like JWT tokens. It uses:

Keychain on iOS
EncryptedSharedPreferences on Android

The AuthService class we created above already uses Flutter Secure Storage, but it's important to understand some best practices:

Security Note: Never store tokens in regular SharedPreferences or local storage, as they are not encrypted and can be accessed by any app with the right permissions.

If you need to configure advanced options for secure storage:

// Advanced configuration example
final storage = FlutterSecureStorage(
  aOptions: AndroidOptions(
    encryptedSharedPreferences: true,
  ),
  iOptions: IOSOptions(
    accessibility: IOSAccessibility.first_unlock,
  ),
);

Building the Login Screen

Here's an example of a simple login screen that uses the AuthService:

// lib/screens/login_screen.dart
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import '../services/auth_service.dart';

class LoginScreen extends StatefulWidget {
  @override
  _LoginScreenState createState() => _LoginScreenState();
}

class _LoginScreenState extends State {
  final _formKey = GlobalKey();
  final _emailController = TextEditingController();
  final _passwordController = TextEditingController();
  bool _isLoading = false;
  String _errorMessage = '';

  Future _submit() async {
    if (!_formKey.currentState!.validate()) {
      return;
    }

    setState(() {
      _isLoading = true;
      _errorMessage = '';
    });

    final authService = Provider.of(context, listen: false);
    final success = await authService.login(
      _emailController.text.trim(),
      _passwordController.text,
    );

    setState(() {
      _isLoading = false;
    });

    if (success) {
      // Navigate to home screen on successful login
      Navigator.of(context).pushReplacementNamed('/home');
    } else {
      setState(() {
        _errorMessage = 'Invalid email or password. Please try again.';
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('Login'),
      ),
      body: Padding(
        padding: const EdgeInsets.all(16.0),
        child: Form(
          key: _formKey,
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            crossAxisAlignment: CrossAxisAlignment.stretch,
            children: [
              TextFormField(
                controller: _emailController,
                decoration: InputDecoration(labelText: 'Email'),
                keyboardType: TextInputType.emailAddress,
                validator: (value) {
                  if (value == null || value.isEmpty) {
                    return 'Please enter your email';
                  }
                  return null;
                },
              ),
              SizedBox(height: 16),
              TextFormField(
                controller: _passwordController,
                decoration: InputDecoration(labelText: 'Password'),
                obscureText: true,
                validator: (value) {
                  if (value == null || value.isEmpty) {
                    return 'Please enter your password';
                  }
                  return null;
                },
              ),
              SizedBox(height: 24),
              if (_errorMessage.isNotEmpty)
                Padding(
                  padding: const EdgeInsets.only(bottom: 16.0),
                  child: Text(
                    _errorMessage,
                    style: TextStyle(color: Colors.red),
                    textAlign: TextAlign.center,
                  ),
                ),
              ElevatedButton(
                onPressed: _isLoading ? null : _submit,
                child: _isLoading
                    ? CircularProgressIndicator(color: Colors.white)
                    : Text('Login'),
                style: ElevatedButton.styleFrom(
                  padding: EdgeInsets.symmetric(vertical: 12),
                ),
              ),
            ],
          ),
        ),
      ),
    );
  }

  @override
  void dispose() {
    _emailController.dispose();
    _passwordController.dispose();
    super.dispose();
  }
}

Implementing Protected Routes

To protect certain screens or routes in your app, create a wrapper widget that checks for authentication:

// lib/widgets/auth_wrapper.dart
import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import '../services/auth_service.dart';

class AuthWrapper extends StatefulWidget {
  final Widget child;
  final Widget loadingWidget;
  final Widget unauthenticatedWidget;

  AuthWrapper({
    required this.child,
    required this.loadingWidget,
    required this.unauthenticatedWidget,
  });

  @override
  _AuthWrapperState createState() => _AuthWrapperState();
}

class _AuthWrapperState extends State {
  late Future _authCheckFuture;

  @override
  void initState() {
    super.initState();
    _checkAuth();
  }

  void _checkAuth() {
    final authService = Provider.of(context, listen: false);
    _authCheckFuture = authService.isLoggedIn();
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder(
      future: _authCheckFuture,
      builder: (context, snapshot) {
        if (snapshot.connectionState == ConnectionState.waiting) {
          return widget.loadingWidget;
        }

        final isAuthenticated = snapshot.data ?? false;
        
        if (isAuthenticated) {
          return widget.child;
        } else {
          return widget.unauthenticatedWidget;
        }
      },
    );
  }
}

You can then use this wrapper in your navigation setup:

// Usage example in main.dart or navigation setup
MaterialApp(
  // ...
  routes: {
    '/home': (context) => AuthWrapper(
      child: HomeScreen(),
      loadingWidget: LoadingScreen(),
      unauthenticatedWidget: LoginScreen(),
    ),
    '/profile': (context) => AuthWrapper(
      child: ProfileScreen(),
      loadingWidget: LoadingScreen(),
      unauthenticatedWidget: LoginScreen(),
    ),
    // Public routes
    '/login': (context) => LoginScreen(),
    '/register': (context) => RegisterScreen(),
  },
  // ...
);

Token Refresh Mechanism

To handle token expiration gracefully, implement an HTTP interceptor that automatically refreshes tokens:

// lib/services/api_client.dart
import 'dart:convert';
import 'package:http/http.dart' as http;
import 'auth_service.dart';

class ApiClient {
  final String baseUrl;
  final AuthService authService;

  ApiClient({required this.baseUrl, required this.authService});

  Future get(String endpoint) async {
    return _sendRequest(() => http.get(
      Uri.parse('$baseUrl/$endpoint'),
      headers: await _getHeaders(),
    ));
  }

  Future post(String endpoint, dynamic data) async {
    return _sendRequest(() => http.post(
      Uri.parse('$baseUrl/$endpoint'),
      headers: await _getHeaders(),
      body: json.encode(data),
    ));
  }

  Future put(String endpoint, dynamic data) async {
    return _sendRequest(() => http.put(
      Uri.parse('$baseUrl/$endpoint'),
      headers: await _getHeaders(),
      body: json.encode(data),
    ));
  }

  Future delete(String endpoint) async {
    return _sendRequest(() => http.delete(
      Uri.parse('$baseUrl/$endpoint'),
      headers: await _getHeaders(),
    ));
  }

  Future> _getHeaders() async {
    final token = await authService.getAccessToken();
    return {
      'Content-Type': 'application/json',
      if (token != null) 'Authorization': 'Bearer $token',
    };
  }

  Future _sendRequest(Future Function() request) async {
    try {
      final response = await request();
      
      // If token has expired
      if (response.statusCode == 401) {
        final refreshed = await authService.refreshToken();
        
        if (refreshed) {
          // Retry the request with the new token
          return await request();
        }
      }
      
      return response;
    } catch (e) {
      rethrow;
    }
  }
}

Testing Authentication

Testing your authentication flow is crucial. Here's a simple way to write tests for your auth service:

// test/auth_service_test.dart
import 'package:flutter_test/flutter_test.dart';
import 'package:mockito/mockito.dart';
import 'package:http/http.dart' as http;
import 'package:flutter_secure_storage/flutter_secure_storage.dart';
import 'package:your_app/services/auth_service.dart';

// Create mocks
class MockHttpClient extends Mock implements http.Client {}
class MockFlutterSecureStorage extends Mock implements FlutterSecureStorage {}

void main() {
  late AuthService authService;
  late MockHttpClient mockHttpClient;
  late MockFlutterSecureStorage mockStorage;

  setUp(() {
    mockHttpClient = MockHttpClient();
    mockStorage = MockFlutterSecureStorage();
    authService = AuthService();
    // Inject mocks
    // ...
  });

  group('AuthService Tests', () {
    test('login should return true on successful login', () async {
      // Test implementation
      // ...
    });

    test('login should return false on failed login', () async {
      // Test implementation
      // ...
    });

    test('isLoggedIn should return true when valid token exists', () async {
      // Test implementation
      // ...
    });

    test('refreshToken should get new token when refresh token is valid', () async {
      // Test implementation
      // ...
    });
  });
}

Conclusion

Implementing JWT authentication in Flutter applications provides a secure and efficient way to authenticate users. By following the steps outlined in this guide, you can create a robust authentication system that protects your users' data while providing a seamless user experience.

Remember to:

Always store tokens securely using Flutter Secure Storage
Implement proper token refresh mechanisms
Validate tokens on both client and server sides
Handle authentication errors gracefully

With these foundations in place, you can build secure, production-ready Flutter applications with confidence.

Table of Contents